sfPropelActAsRatableBehaviorPlugin - 0.7.1

Propel ratable behavior

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
This plugin is deprecated and is not maintained anymore. I don't use Propel anymore. Feel free to request if you want to take over the plugin development.
Show source | Show as Markdown

sfPropelActAsRatableBehaviorPlugin

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

rating_capture.png

Installation

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

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

The source code is also available: * from the code browser * from the SVN repository (please always use a tagged version in production)

SVN repository

The plugin is also available through the Symfony SVN repository.

Stable versions are available in the tags folder, experimental ones in the branches one and the current alpha in the trunk.

Caution: Never use the trunk version in a production environment.

Configuration

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

propel.builder.addBehaviors = true

In one (or more) of your existing model object classes, apply the behavior. Eg. for an Article Propel model class:

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

You can fine-tune behavior with optional parameters, see the advanced configuration section.

Once your model configured, you have to rebuild it:

symfony propel-build-all

And clear the cache :

symfony cc

Advanced configuration

Behavior optional parameters

<?php
class Article extends BaseArticle
{
}
sfPropelBehavior::add(
  'Article', 
  array('sfPropelActAsRatableBehavior',
        array('max_rating'      => 10,              // Max rating value for an Article
              'rating_field'    => 'AverageRating', // refers to ArticlePeer::AVERAGE_RATING
              'reference_field' => 'Reference')));  // refers to ArticlePeer::REFERENCE
  • The max_rating parameter sets the maximum rating available for an object (this must be an integer greater than 0 - default is 5)
  • The rating_field parameter, which refer to a float column in phpName format of your ratable object table which will store cached value of actual rating for the object. Useful for queries and performances ;)
  • The reference_field parameter sets the name of the field where you store the identifier of the object to rate. By default, the plugin will use the primary key of the object. You must return an integer fo referencing a custom identifier.

Ensure rating consistency

A clean way to ensure rating consistency is to associate a rating to a unique identified user reference stored server side, typically the primary key of a user record in your database.

If no user reference can be retrieved, the plugin will rely on cookies, but you should consider this alternative solution with caution, as cookies are easily deletable by the user.

User reference retrieval configuration

By default, the plugin will search for an sfGuardPlugin(/plugins/sfGuardPlugin sfGuardPlugin) installation to retrieve authenticated user primary key. If you are using sfGuard, you have nothing more to configure.

If you don't use sfGuard, you can specify the way a unique user reference (eg. primary key) will be retrieved, using these available plugin settings in your app.yml file:

  • You can specify a PHP function, eg. get_connected_user_id():

    rating: user_id_getter: get_connected_user_id

  • Or a static method of a PHP class, eg. MyCustomUtilsClass::getConnectedUserId():

    rating: user_id_getter: getConnectedUserId

The return value of these calls should always be the primary key of your connected user.

Using the Ajax rating system

This plugin provides an Ajax-based rating system, with pretty stars to click on.

rating_capture.png

To activate this feature, you must enable the sfRating module in the config/settings.yml file of the app you want to use the helper in :

all:
  .settings:
    enabled_modules:        [sfRating](default,)

If you are under Microsoft Windows, you also have to manually copy the ./web directory of the plugin in the %SF_ROOT_DIR%/web directory of your project and rename it to sfPropelActAsRatableBehaviorPlugin. Then you will have this on the filesytem :

project_root
  [...]
  web
    sfPropelActAsRatableBehaviorPlugin
      css
        sf_rating.css
      images
        alt_star.gif

Then, you can use the sf_rater helper in any of your templates:

<?php sfLoader::loadHelpers('sfRating') ?>
<?php echo sf_rater($article) ?>

Using the rating details display component

RatingDetails.png

Just call the component from any of your templates:

<?php include_component('sfRating', 'ratingDetails', array('object' => $article) ?>

API Usage

Note: In below examples, $user_id is a string representing a unique reference to a user, eg. if you're using the sfGuardPlugin, sfContext::getInstance()->getUser()->getGuardUser()->getId().

If you don't provide this parameter, the configured user reference retrieval configuration will apply.

To set a rating for a given user:

$article->setRating(10, $user_id);

To test if the object has already been rated :

$article->hasBeenRated();

To test if the object has already been rated by a particular user:

$article->hasBeenRatedByUser($user_id);

To retrieve user rating for this object :

$article->getUserRating($user_id);

To get the average rating of the object :

$article->getRating([$precision]);

Note: If you have concerns about performances, you will better use the cached value of rating stored in the rating_column you configured previously.

To retrieve the maximum possible rating for an object (which you have defined in the max_rating behavior optional parameter - default is 5) :

$article->getMaxRating();

To clear user rating :

$article->clearUserRating($user_id);

To retrieve rating details :

$details = $article->getRatingDetails();

Results will be this form:

array(
  2 => 12, // 12 people has rated the object 2
  5 => 7   // 7 people has rated the object 5
)

You can also retrieve details for all available ratings:

$full_details = $article->getRatingDetails(true);

Results will be this form:

array(
  1 => 0,  // Nobody has rated the object 1
  2 => 12, // 12 people has rated the object 2
  3 => 0,  // Nobody has rated the object 3
  4 => 0,  // Nobody has rated the object 4
  5 => 7,  // 7 people has rated the object 5
)

To clear all ratings for the object :

$article->clearRatings();

Unit testing

The plugin is provided with a test suite located in the ./test directory. To run the tests, type this line from the root of your project :

$ php plugins/sfPropelActAsRatableBehaviorPlugin/test/unit/sfPropelActAsRatableBehaviorTest.php

Note that you have to provide a Propel test object class name to run the test in the test file:

define('TEST_CLASS', 'Article');

Uninstallation

symfony plugin-uninstall symfony/sfPropelActAsRatableBehaviorPlugin

You will need to remove the behavior to all your model, then rebuild your model and purge your cache.

TODO

  • Add functional tests

Changelog

2007-10-29 | v0.7.1

  • Ratable model objects instances references are now tokenized in the session and are no more passed as request parameters

2007-09-23 | v0.7

  • big behavior refactoring, with model and API BC (sorry for that, but it is much better now)
  • removed ugly reference field configuration and behavior methods, now we use object getPrimaryKey() method: fast, portable and reliable
  • removed sfPropelActAsRatableBehavior::isRatable() buggy method
  • added Fabian Lange patch to allow ratings details retrieval (thanks!)
  • added a component to display rating details graphically
  • removed all IP address handling related stuff (unsecure when passed as parameters)
  • ratings storing in dedicated column in ratable object table (submitted by Vojtech Rysanek - thanks!)
  • added i18n strings management

2007-09-12 | v0.6.2

  • Reference keys are now stored as a md5 hash
  • Corrected custom reference keys handling bug in Ajax rater widget
  • Added a isRatable static method in behavior class
  • Some bugs corrected

2007-09-09 | v0.6.1

  • Added a way to specify a custom reference field to identify a ratable Propel object
  • Added ability to set the maximum rating for an object when the behavior is added
  • Key length as also been decreased to avoid a strange MySQL bug on KEY length
  • Added unit tests

2007-09-07 | v0.6.0

  • Added an AJAX rating system as a helper
  • Added constant MAX_RATING management for consistency control in ratable model class
  • Moved int fields to varchar for storing unique user reference descriptor (eg. storing the IP address, an email, a md5 hash, etc.)
  • sfRatings table has been renamed to sf_ratings: you have to rebuild your SQL files and insert them in your DB if you upgrade from 0.5.0. Hopefully, one day we'll have a migration system in Symfony core...
  • Removed configuration file to set up Propel object to unit test in the test suite

2007-09-05 | v0.5.0

  • Initial release

Maintener

This plugin is maintened by Nicolas Perriault (nperriault -> gmail.com)

Feel free to send feture request, enhancement suggestion or idealy a patch.

Credits

  • The eye-candy star-based Ajax system is based on the great work of Komodomedia: http://komodomedia.com/blog/samples/star_rating/example2.htm