# sfPayloadFilterChainPlugin plugin

The `sfPayloadFilterChainPlugin` is an implementation of the [Intercepting Filter](http://www.phpwact.org/pattern/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: [urls_to_html, expand_smileys](censor_bad_words,)
    

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:        [poil, couille, nichon](bite,)
        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.