= sfPayloadFilterChainPlugin plugin =

The `sfPayloadFilterChainPlugin` is an implementation of the [http://www.phpwact.org/pattern/intercepting_filter Intercepting Filter] design pattern. 
It provides means to apply filtering to a custom "payload".

== Features ==

 * Support for multiple chain "profiles"
 * Built on symfony classes

== Installation ==

{{{
#!sh
symfony plugin-install http://plugins.symfony-project.com/sfPayloadFilterChainPlugin
}}}

== Usage ==

=== Preambule ===

This plugin does not provide any concrete filter nor payload implementations. The application developer is responsible for providing these.
The following examples describe a possible implementation of the filtering of a blog post comment.

=== Defining a filtering profile ===

 * Create a `config/pfc` directory in your application
 * Create a `profiles.yml` file in this directory.
 * Specify the post comment filtering profile :
 
{{{
post_comment: [censor_bad_words, urls_to_html, expand_smileys]
}}}

This means that any post comment payload passed through the filter chain will be filtered sequentially using the defined filters.

Executing the filter chain on a comment text will :

 * replace forbidden words in it with "*CENSORED*"
 * replace plain text urls with their HTML (`<a href=...`) equivalent
 * replace smileys with appropriate `<img />`

=== Specifying filters ===

Filters specification is done in your application's `config/pfc/filters.yml` file.

Let's specify the filters we mentioned in the `profiles.yml` file :

{{{
censor_bad_words:
  enabled: on
  class:   myCensorshipFilter
  params:
    bad_words:        [bite, poil, couille, nichon]
    replacement_word: *CENSORED*
    
urls_to_html:
  enabled: on
  class:   myUrlsToHtmlFilter
  params:
    enable_nofollow: on

expand_smileys:
  enabled: on
  class:   mySmileyExpansionFilter
  params:
    base_url: images/smileys
}}}

=== Implementing filters ===
Some notes :
 * filters must extend the `sfFilter` class
 * params defined in `filters.yml` are available through filter's `getParameter('name', 'default_value')` method

Here's a sample implementation of the `myCensorshipFilter` filter :

{{{
#!php
<?php

# lib/filter/myCensorshipFilter.class.php

class myCensorshipFilter extends sfFilter
{
  /**
   * Replace some words in text by a configurable replacement word.
   * 
   * @param     string     $text
   * @return    string
   */
  public function execute($chain, $payload)
  {
    // Get forbidden words from filter specification
    $forbidden_words = $this->getParameter('bad_words', array());

    // Retrieve text from payload
    $text = $payload->getText();

    // Replace words in text. Only full words occurences are replaced
    foreach($forbidden_words as $word)
    {
      $pattern = sprintf('/\b%s\b/i', $word);
      $text = preg_replace($pattern, $this->getParameter('replacement'), $text);
    }

	// Replace payload text
    $payload->setText($text);
    
    // Execute next filter in chain
    $chain->execute($payload);
  }
}

}}}


=== Implementing payload ===

The developer must provide a payload object that can be used by the filter chain. Our example deals only with text transformation, so let's implement an appropriate payload :

{{{
#!php
<?php

# lib/payload/myTextPayload.class.php

class myTextPayload
{

  public function getText()
  {
    return $this->text;
  }

  public function setText($text)
  {
    $this->text = $text;
  }

}
}}}

=== Executing filter chain on a payload ===

==== Manually, in an action ====

{{{
#!php
<?php

# apps/blog/modules/comment/actions.class.php#executeAddComment

// Create payload
$payload = new myTextPayload();
$payload->setText($this->getRequestParameter('comment_text'));
    
// Filter payload
$chain = new pfcPayloadFilterChain();
$chain->loadProfile('post_comment');
$chain->setPayload($payload);
$chain->execute();

// Save comment
$comment = new PostComment();
$comment->setText($payload->getText());
$comment->save();
}}}

==== Automatically, in model ====

{{{
#!php
<?php

# lib/model/PostComment.php

public function save()
{
  // Create payload
  $payload = new myTextPayload();
  $payload->setText($this->getText());
    
  // Filter payload
  $chain = new pfcPayloadFilterChain();
  $chain->loadProfile('post_comment');
  $chain->setPayload($payload);
  $chain->execute();

  // Save comment
  $this->setText($payload->getText());
  parent::save();
}
}}}

== Changelog ==

=== 2007-03-14 | 0.1.0 beta ===

Initial public release.