= 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 [source:/symfony/plugins/sfPropelActAsRatableBehaviorPlugin/trunk/lib/sfPropelActAsRatableBehavior.class.php plugin API]. 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 [source:/symfony/plugins/sfPropelActAsRatableBehaviorPlugin/trunk/test/sfPropelActAsRatableBehaviorTest.php unit tests suite located here]. 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.