Appendix E. Core filters
Prev |  | Next

# Appendix E. Core filters

Filters are a subset of Phing `data types` which provide for the transformation of file contents during the operation of another task. For example, a filter might replace tokens in a file as part of a copy task.

Filters have to be defined within a `<filterchain>` context to work. Example:

    <filterchain>
      <expandproperties />
    </filterchain>

There are two ways to use a filter: System filters (the ones shipped with Phing) can be used with their own tag name, such as `<xsltfilter`>, <`expandpropertyfilter`> or `<tabtospaces`>. User-defined filters can use the way is to use the `<filterreader>` tag.

## E.1 PhingFilterReader

The PhingFilterReader is used when you want to use filters that are not directly available through their own tag. Example:

    <filterchain>
      <filterreader classname="phing.filter.ReplaceTokens">
        <!-- other way to set attributes -->
        <param name="begintoken" value="@@" />
        <param name="endtoken" value="@@" />

        <!-- other way to set nested tags -->
        <param type="token" key="bar" value="foo" />
      </filterreader>
    </filterchain>

In the `filterreader` tag you have to specify the path the class is in. The `FilterReader` will then load this class and pass the parameters to the loaded filter. There are two types of parameters: First, you can pass "normal" parameters to the loaded filter. That means, you can pass parameters as if they were attributes. If you want to do this, you only specify the `name` and `value` attributes in the `param` tag. You can also pass nested elements to the filter. Then, you have to specify the `type` attribute. This attribute specifies the name of the nested tag.

The result of the example above is identical with the following code:

    <filterchain>
      <replacetokens begintoken="@@" endtoken="@@">
        <token key="bar" value="foo" />
      </replacetokens>
    </filterchain>

Table E.1: Attributes for `<filterreader>`

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
`classname` | `String` | Name of class to use (in dot-path notation). | n/a | Yes
`classpath` | `String` | The classpath to use when including classes. This is added to PHP's include_path. | n/a | No
classpatxlink:href | `String` | Reference to classpath to use when including classes. This is added to PHP's include_path. | n/a | No

### E.1.1 Nested tags

The `PhingFilterReader` supports nested <classpaentry>.

### E.1.2 Advanced

In order to support the `<filterreader ... />` sytax, your class must extend the BaseParamFilterReader class. Most of the filters that are bundled with Phing can be invoked using this syntax. The noteable exception (at time of writing) is the ReplaceRegexp filter, which expects find/replace parameters that do not fit the name/value mold. For this reason, you must always use the shorthand `<replaceregexp .../>` to invoke this filter.

Prev |  | Next
D.6 PearPackageFileSet | Home | E.2 ExpandProperties