# sfPropelActAsCommentableBehaviorPlugin

## Introduction

This behavior permits to attach comments to Propel objects.

## Features

  * add/remove comment(s) on an object
  * unit-tested

## Philosophy of the stuff

  * commentable objects must have a primary key
  * comments can only be attached on objects that have already been saved
  * comments are saved when applied

## Get it installed

  * go to your project's root

  * Install the plugin:
       
         ./symfony plugin-install http://plugins.symfony-project.com/sfPropelActAsCommentableBehaviorPlugin
       

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

  * edit the classes that you want to make taggable. For instance, for lib/model/Post.php:
       
       [php]
       <?php
         class Post extends BasePost
         {
         }
    
         sfPropelBehavior::add('Post', array('sfPropelActAsCommentableBehavior'));
       

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

  * clear cache:
       
         ./symfony cc
       


## Usage

### Attaching tags to a commentable object

Consider a Propel "Post" class:

    
    [php]
    <?php
    class Post extends BasePost
    {
    }
    
    sfPropelBehavior::add('Post', array('sfPropelActAsCommentableBehavior'));
    

When the sfPropelActAsCommentableBehaviorPlugin is applied to the Post class, that class automagically gets commentable:
    
    [php]
    <?php
    $post = new Post();
    // blah
    $post->save();
    $post->addComment('This is a cool comment.');
    $post->addComment(array('title' => 'this is a cool title', 'text' => 'this is a cool comment', 'author_id' => sfContext::getInstance()->getUser()->getUserId()));
    $post->addComment(array('This is a cool comment.', 'this is one other comment'));
    

### Retrieving one object's tags

It is possible to retrieve tags from a taggable object:
    
    [php]
    <?php
    $post = PostPeer::retrieveByPk(1);
    $tags = $post->getTags();
    
    foreach ($tags as $tag)
    {
      echo $tag.'<br />';
    }
    

### Removing one object's tags

Of course, tags can also be removed:
    
    [php]
    <?php
    $post = PostPeer::retrieveByPk(1);
    $post->removeTag('toto');
    $post->removeTag('toto, tutu');
    $post->removeAllTags();
    

## API

The behavior implement the following methods:
  * **addComment($comment)** - Adds a comment to the object. The "comment" param can be an associative array (in which each element represents one of the comment properties), or an array of associative arrays. In this case, it adds all the comments to the object.
  * **clearComments()** - Deletes all the comments attached to the object
  * **getComments($options = array())** - Returns the list of the comments attached to the object. The options array can contain several options
  * **getNbComments()** - Returns the number of the comments attached to the object.
  * **removeComment($comment_id)** - Removes one comment from the object.

The behavior class also implement the following method, which is a facility for preloading all the tags for a set of taggable objects
  * **preloadTags($objects)** - Preload tags for a set of objects

## Unit testing

The plugin has been deeply unit-tested. The tests are located in test/unit/sfPropelActAsCommentableBehaviorTest.php. If you want to run them:
  * install the plugin
  * 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/sfPropelActAsCommentableBehaviorPlugin/test/unit/sfPropelActAsCommentableBehaviorTest.php
       

## License and credits

This plugin is licensed under the MIT license. You can contact the maintainer at xavier@lacot.org

## Changelog

### version 0.1 - 2007-09-13

Initial public release. Features comments attachment to heterogene Propel objects.

## Roadmap

  * add a symfony module for posting and displaying comments
  * handle other custom fields in comments
  * use sfPropelActAsPolymorphicBehaviorPlugin ? :)