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