= sfPropelActAsRecommendableBehaviorPlugin =

== Introduction ==
This plugin implements a behavior that permits to recommend objects. A recommandation acts as the incrementation of a counter "à la Digg".

== Features ==

 * add a recommendation on an object (increments the counter)
 * get the object's score
 * unit-tested

== Philosophy of the stuff ==

 * recommendable objects must have a primary key
 * users objects muse have a primary key
 * recommendations can only be attached on objects that have already been saved
 * recommendations are saved when applied
 * unregistered user's recommendations are saved via cookies
 * unit-tests needs an sfGuardUser object

== Get it installed ==

 * go to your project's root

 * Install the plugin:
   {{{
     ./symfony plugin-install http://plugins.symfony-project.com/sfPropelActAsRecommendableBehaviorPlugin
   }}}

 * if not already done, enabled behaviors in config/propel.ini:
   {{{
     propel.builder.addBehaviors = true
   }}}

 * edit the classes that you want to make Recommendable. For instance, for lib/model/Post.php:
   {{{
   #!php
   <?php
     class Post extends BasePost
     {
     }

     sfPropelBehavior::add('Post', array('sfPropelActAsRecommendableBehavior'));
   }}}

 * rebuild the model:
   {{{
     ./symfony propel-build-all
   }}}

 * clear cache:
   {{{
     ./symfony cc
   }}}


== Usage ==

=== Adding recommendation to a Recommendable object ===
Consider a Propel "Post" class:

{{{
#!php
<?php
class Post extends BasePost
{
}

sfPropelBehavior::add('Post', array('sfPropelActAsRecommendableBehavior'));
}}}

When the sfPropelActAsRecommendableBehaviorPlugin is applied to the Post class, that class automagically gets Recommendable:
{{{
#!php
<?php
$post = new Post();
// blah
$post->save();
$post->recommend(); // for unregistered users
$post->recommend($user->getPrimaryKey()); // $user is a registered user object
}}}

=== Retrieving one object's recommendation score ===
{{{
#!php
<?php
$post = PostPeer::retrieveByPk(1);
$score = $post->getRecommendationScore();
echo '<p>This post has been recommended by '.$score.' users</p>';
}}}

== API ==
The behavior implement the following methods:
 * '''recommend($user_id)''' - add a recommendation on the object (increments the counter). The user id is not mandatory: if not given, a cookie is set to avoid multiple recommendation by a single user
 * '''getRecommendationScore()''' - retrieves the object's score

== Unit testing ==
The plugin has been unit-tested. The tests are located in test/unit/sfPropelActAsRecommendableBehaviorTest.php. If you want to run them:
 * install the plugin
 * be sure you are using sfGuardUser object in your application
 * configure a model for using it, for instance "Post"
 * edit this file and, if required, modify the application name and the TEST_CLASS constant, line 3:
   {{{
     define('TEST_CLASS', 'Post');
   }}}
 * run the tests:
   {{{
     php plugins/sfPropelActAsRecommendableBehaviorPlugin/test/unit/sfPropelActAsRecommendableBehaviorTest.php
   }}}

== License and credits ==
This plugin is licensed under the MIT license. You can contact the maintainer at rcieplicki@clever-age.com

== Changelog ==

=== version 0.1 - 2007-09-13 ===
Initial public release. Features recommendation for both registered and unregistered users, and score retrieving.

== Roadmap ==
 * recommendation helpers
 * handle non-sfGuardUser users