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:

  <expandproperties />

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:

  <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" />

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:

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

Table E.1: Attributes for <filterreader>

classnameStringName of class to use (in dot-path notation).n/aYes
classpathStringThe classpath to use when including classes. This is added to PHP's include_path.n/aNo
classpatxlink:hrefStringReference to classpath to use when including classes. This is added to PHP's include_path.n/aNo

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 notable 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.