# sfPropelActAsRatableBehaviorPlugin

This plugin aims at providing rating capabilities to any Propel object with the help of a dedicated Propel behavior.

## Installation

To install the plugin, run this command within your symfony project :

    
    symfony plugin-install http://plugins.symfony-project.com/sfPropelActAsRatableBehaviorPlugin
    

To activate this Propel behavior in Symfony, you must first activate behaviors in your propel.ini file :

    
    propel.builder.addBehaviors = true
    

Add the behavior to one or more of your existing model object classes, eg. an `Article` object :

    
    <?php
    class Article extends BaseArticle
    {
    }
    
    sfPropelBehavior::add('Article', array('sfPropelActAsRatableBehavior'));
    

Then, rebuild your model :

    
    symfony propel-build-all
    

And clear the cache :

    
    symfony cc
    

## Usage

You can rate your previously configured `Article` objects through the [plugin API](source:/symfony/plugins/sfPropelActAsRatableBehaviorPlugin/trunk/lib/sfPropelActAsRatableBehavior.class.php). Note that you can provide a user PK to determine if one of your user has already rated the object.

Here we imagine a `User` object instance `$user` which represent a member, an author, a person or anything like this.

To set a rating for a given user :

    
    $article->setRating(10, $user->getId());
    

To retrieve user rating for this object :

    
    $article->getUserRating($user->getId());
    

To get the average rating of the object :

    
    $article->getRating();
    

To clear user rating :

    
    $article->clearRating($user->getId());
    

To clear all ratings for the object :

    
    $article->clearRatings();
    

You can test if the object has already been rated :

    
    $article->hasBeenRated();
    

You can also test if the object has already been rated by a particular user:

    
    $article->hasBeenRatedByUser($user->getId());
    

## Unit testing

The plugin is provided with a [unit tests suite located here](source:/symfony/plugins/sfPropelActAsRatableBehaviorPlugin/trunk/test/sfPropelActAsRatableBehaviorTest.php). To run the tests, type this line from the root of your project :

    
    $ php plugins/sfPropelActAsRatableBehaviorPlugin/test/sfPropelActAsRatableBehaviorTest.php
    

Note that you have to provide a test object to run the test. By default its an `Article` object with a `title` field which the behavior is supposed to be applied, but feel free to edit the tests file to adapt it to your need and your existing schema.