Developers

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Optional settings

The plugin has been designed to allow comments from authenticated users, as
well as anonymous users. But in general, you will want to adapt the layout of
the form, depending on whether the user is authenticated or not. In the app.yml
file, you can tweak the default setup:

the allowed_tags rule fixes the list of allowed html tags in the comment
field. All the other html tags will be removed by HTMLPurifier.

the anonymous rules will tweak the way the plugin handles anonymous
comments:

enabled : enables or disables anonymous comments.

layout : defines the layout of the comment form. Required fields will
get a "required" class and will get validated. If you want a field
not to appear (for instance, the "title" field), simply remove the
associated line. Supported field names are :

name

email

website

title

text

name : the default name of the user, in case the anonymous comment
form does not as for an author name.

the count rules are useful for optimizing objects sorting on their
comments count. See the paragraph "Retrieving one object's comments number"
for more details.

the date_format option tells the plugin in which format the date of one
comment should be displayed. This can be "words" (the default tweak), or any
Symfony-compliant formatting string

the max_tokens option is the maximal amount of commentable-objects
tokens to be stored in session. As you do not want to reveal the technical id
of the commentable objects, the plugin generates encrypted tokens and stores
them in the session.

the namespaces parameter lists the namespaces for which a security
check must be made:

when a namespace is listed under the namespaces parameter, its value
represents the required credentials for writing in it.

If you use namespaces in your comments, please make sure that you fill
this parameter accordingly to your needs. For instance, if your application
provide back-office internal comments, you won't want a normal front-office
user being able to add comments on the back-office.

You can of course use your own namespaces names (ie., "backend"
and "frontend" are not compulsory names).

the salt option is the private key to encrypt the commentable tokens
(see max_tokens for more explanations)

the use_css rule tells the plugin whether or not to include the default
CSS file of the plugin

the use_gravatar rule indicates whether or not the comment system must
display gravatar. This option uses the sfGravatarPlugin.

the user rules will tweak the way the plugin handles comments from
authenticated users:

enabled : enables or disables comments from authenticated users.

layout : defines the layout of the comment form. Required fields
will get a "required" class and will get validated. If you want a field not
to appear (for instance, the "title" field), simply remove the associated
line. Supported field names are :

name

email

website

title

text

table : name of the table that stores the users data.

id : name of the primary key of a user in the users table.

class : class associated to the users.

id_method : name of a method of your user's class, that permits to
get the authenticated user id. Usually, you will have to define this method
in the myUser.class.php file.

toString : name of a method that outputs the name of a user (an
instance of the class defined two lines before)

Usage

How to use the comments module

You do not have to know the plugin internals in order to get started with the
behavior. You simply have to include two components:

By default, the comment list displays all the comments that do not belong to
one namespace. If you want to display comments for the namespace "gerard", then
simply pass this optionnal parameter to the component:

One common problem is about sorting objects by their number of comments. For
the moment, the plugin does not propose any immediate solution, so you will have
to join with the comments table:

SELECT `post.title`,
`post.text`,
COUNT(`sf_comment.id`) as `count`
FROM `post`, `sf_comment`
WHERE `sf_comment.commentable_id`=`post.id`
AND `sf_comment.commentable_model`='post'
GROUP BY (`sf_comment.commentable_id`)
SORT BY `count` DESC;

However, a trick is available in the plugin: if you create a column named
"sf_comment_count" (or something else, depending on your app.yml configuration)
in the commentable model, its value will be updated each time a new comment is
added using the addComment() method.

Several app.yml parameters are involved in this trick:

count:
enabled: true # whether or not the method must be called for updating the comments count
method: setSfCommentCount # name of the method to call in order to update the comments count. If you call the comments count column "gerard", simply put "setGerard" on this line
namespace: frontend # namespaces of the comments that have to be counted (usefull for frontend counts). If you don't use namespaces, don't fill this line.

With this trick, sorting objects by their comment numbers is rather straightforward:

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 may contain several restriction
options: namespace, order. The Criteria may be used to programmatically
restrict the results.

getNbComments() - Returns the number of the comments attached to the
object. The options array may contain several restriction options: namespace,
order. The Criteria may be used to programmatically restrict the results.

removeComment($comment_id) - Removes one comment from the object.

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:

you're done! Only users with "administrator" credential are able to add
comments to objects in the back-office, while everyone can add comments in the
front-office. You can tweak the required credentials by modifying the
app.yml file.

Comments administration

optionnaly, have a look at the sfCommentAdmin module, that uses the
admin-generator for providing a view of all comments.

Tweaking the plugin's default module

As every plugin module, the modules bundled in this plugin can be
overloaded. You simply have to create a module called sfComment in your
application, and it will override the plugin's module.

the sfPropelActAsCommentableStripper can also be overloaded. Simply
create your own class somewhere in your project. This class must be named
"sfPropelActAsCommentableStripper", and must implement a "clean()"
method. For instance, the following stripper won't strip anything (nor validate
the user's entry):