Phing Guide - Core Filters

# Appendix D-2: 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.

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

### Attributes

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
classpathref | String | Reference to classpath to use when including classes. This is added to PHP's include_path. | n/a | No

### Nested Tags

The PhingFilterReader supports nested <classpath>.

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

## ExpandProperties

The ExpandProperties simply replaces property names with their property values. For example, if you have the following in your build file:

    <property name="description.txt" value="This is a text file" />

    <copy todir="/tmp">
      <filterchain>
        <expandproperties />
      </filterchain>

      <fileset dir=".">
        <include name="**" />
      </fileset>
    </copy>

And the string ${description.txt} it will be replaced by This is a text file.

## HeadFilter

This filter reads the first n lines of a file; the others are not further passed through the filter chain. Usage example:

    <filterchain>
      <headfilter lines="20" />
    </filterchain>

### Attributes

Attributes for the <headfilter> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
lines | Integer | Number of lines to read. | 10 | No

## IconvFilter

The IconvFilter encodes file from `in` encoding to `out` encoding. Usage example:

    <filterchain>
        <iconvfilter inputencoding="UTF-8" outputencoding="CP1251" />
    </filterchain>

### Attributes

Attributes for the <iconvfilter> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
inputencoding | string | Input encoding. | n/a | Yes
outputencoding | string | Output encoding. | n/a | Yes

## Line Contains

This filter is only "permeable" for lines that contain the expression given as parameter. For example, the following filterchain would only let all the lines pass that contain class:

    <filterchain>
      <linecontains>
        <contains value="class" />
      </linecontains>
    </filterchain>

### Nested Tags

The linecontains tag must contain one or more contains tags. Latter must have a value attribute that has to be set to the string the line has to contain to be let through.

## LineContainsRegexp

This filter is similar to LineContains but you can specify regular expressions instead of simple strings.

    <filterchain>
      <linecontainsregexp>
        <regexp pattern="foo(.*)bar" />
      </linecontainsregexp>
    </filterchain>

### Nested Tags

The LineContains filter has to contain at least one regexp tag. This must have a pattern attribute that is set to a regular expression.

## PrefixLines

This filter adds a prefix to every line. The following example will add the string foo: in front of every line.

    <filterchain>
      <prefixlines prefix="foo: " />
    </filterchain>

### Attributes

Attributes for the <prefixlines> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
prefix | string | Strint to prepend to every line. | n/a | Yes

## ReplaceTokens

The ReplaceTokens filter will replace certain tokens. Tokens are strings enclosed in special characters. If you want to replace ##BCHOME## by the path to the directory set in the environment variable BCHOME, you could do the following:

    <property environment="env" />

    <filterchain>
      <replacetokens begintoken="##" endtoken="##">
        <token key="BCHOME" value="${env.BCHOME}" />
      </replacetokens>
    </filterchain>

### Attributes

Attributes for the <replacetokens> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
begintoken | string | The string that marks the beginning of a token. | @ | No
endtoken | string | The string that marks the end of a token. | @ | No

### Nested Tags

The ReplaceTokens filter must contain one or more token tags. These must have a key and a value attribute.

## ReplaceTokensWithFile

The ReplaceTokensWithFile filter will replace certain tokens with the contents of a file. The name of the file to use as replacement is derived from the token name itself. Tokens are strings enclosed in special characters which are user selectable.

This filter could for example be used to insert code examples in documentation where the example code are real executable files kept outside the documentation.

If you for example want to replace #!example1## with the content of the file " `example1.php` " you could do the following

          <filterchain>
          <replacetokenswithfile begintoken="#!" endtoken="##"
              dir="exampledir/" postfix=".php" />
          </filterchain>

The filer above will replace all tokens within the begin and end token specified with the contents of the file whose base name is that of the token with the added postfix ".php". Only the directory specified in the dir attribute is searched. If the file is not found the token is left untouched and an error message is given. It is important to note that all found tokens will be replaced with the corresponding file. So in the example below even #!example2## will be replaced with the content of the file " `example2.php` "

### Attributes

Attributes for the <replacetokenswithfile> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
begintoken | string | The string that marks the beginning of a token. | #@# | No
endtoken | string | The string that marks the end of a token. | #@# | No
prefix | string | A string that will be added in front of the token to construct the filename that will be used as source when replacing the token. | '' | No
postfix | string | A string that will be added to the end of the token to construct the filename that will be used as source when replacing the token. | '' | No
dir | string | The directory where to look for the files to use as replacements for the tokens | './' | No
translatehtml | boolean | If true all html special characters (e.g. ">") in the file to there corresponding html entities (e.g. "&gt;") before the file is inserted. | true | No

### Nested Tags

None.

## ReplaceRegexp

The ReplaceRegexp filter will perform a regexp find/replace on the input stream. For example, if you want to replace ANT with Phing (ignoring case) and you want to replace references to *.java with *.php:

    <filterchain>
      <replaceregexp>
    	<regexp pattern="ANT" replace="Phing" ignoreCase="true"/>
    	<regexp pattern="(\w+)\.java" replace="\1.php"/>
      </replaceregexp>
    </filterchain>

### Nested Tags

The ReplaceTokens filter must contain one or more regexp tags. These must have pattern and replace attributes. The full list of supported attributes is as following:

Attributes for the <regexp> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
pattern | string | Regular expression used as needle. Phing relies on Perl-compatible regular expressions. | n/a | Yes
replace | string | Replacement string. | n/a | Yes
ignoreCase | boolean | Whether search is case-insensitive. | false | No
multiline | boolean | Whether regular expression is applied in multi-line mode. | false | No
modifiers | string | Raw regular expression modifiers. You can pass several modifiers as single string, and use raw modifiers with ignoreCase and multiline attributes. In case of conflict, value specified by dedicated attribute takes precedence. | '' | No

The previous example (using modifiers attribute this time):

    <filterchain>
      <replaceregexp>
    	<regexp pattern="ANT" replace="Phing" modifiers="i"/>
    	<regexp pattern="(\w+)\.java" replace="\1.php"/>
      </replaceregexp>
    </filterchain>

## StripLineBreaks

The StripLineBreaks filter removes all linebreaks from the stream passed through the filter chain.

    <filterchain>
      <striplinebreaks />
    </filterchain>

## StripLineComments

The StripLineComments filter removes all line comments from the stream passed through the filter chain:

    <filterchain>
      <striplinecomments>
        <comment value="#" />
        <comment value="--" />
        <comment value="//" />
      </striplinecomments>
    </filterchain>

### Nested Tags

The striplinecomments tag must contain one or more comment tags. These must have a value attribute that specifies the character(s) that start a line comment.

## StripPhpComments

The StripPhpComments filter removes all PHP comments from the stream passed through the filter.

    <filterchain>
      <stripphpcomments />
    </filterchain>

## StripWhitespace

The StripWhitespace filter removes all PHP comments and whitespace from the stream passed through the filter. Internally, this filter uses the php_strip_whitespace() function.

    <filterchain>
      <stripwhitespace />
    </filterchain>

## TabToSpaces

The TabToSpaces filter replaces all tab characters with a given count of space characters.

    <filterchain>
      <tabtospaces tablength="8" />
    </filterchain>

### Attributes

Attributes for the <tabtospaces> filter
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
tablength | Integer | The number of space characters that a tab is to represent. | 8 | No

## TailFilter

Similar to HeadFilter, this filter reads the last n lines of a file; the others are not further passed through the filter chain. Usage example:

    <filterchain>
      <tailfilter lines="20" />
    </filterchain>

### Attributes

Attributes for the <tailfilter> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
lines | Integer | Number of lines from the back to read. | 10 | No

## TidyFilter

The TidyFilter allows you to use the PHP tidy extension to clean up and repair HTML documents. Usage example:

    <filterchain>
      <tidyfilter encoding="utf8">
        <config name="indent" value="true" />
        <config name="output-xhtml" value="true" />
      </tidyfilter>
    </filterchain>

### Attributes

Attributes for the <tidyfilter> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
encoding | String | The expected input encoding of the file. | utf8 | No

### Nested Tags

The TidyFilter supports nested <config> tags to configure how Tidy should manipulate the documents. For a complete list of configuration options see the offical Quick Reference.

## XincludeFilter

The XincludeFilter processes a stream for Xinclude tags, and processes the inclusions. This is useful for processing modular XML files. DocBook book files are one example of modular XML files. Usage example:

    <!--
      Render a DocBook book file called manual.xml, which
      contains Xinclude tags to include individual book sections.
      -->
    <copy todir="${manual.dest.dir}">
      <filterchain>
        <xincludefilter basedir="${manual.src.dir}" />
        <xsltfilter style="${manual.src.dir}/html.xsl">
          <param name="base.dir" expression="${manual.dest.dir}/" />
        </xsltfilter>
      </filterchain>
      <fileset dir="${manual.src.dir}">
        <include name="manual.xml" />
      </fileset>
    </copy>

### Attributes

Attributes for the <xincludefilter> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
basedir | String | The working directory from which to process the Xincludes. Relative pathnames in the include tags are based on this location. | Project basedir | No
resolveexternals | Boolean | Whether to resolve entities. (see this link for details) | false | No

## XsltFilter

The XsltFilter applies a XSL template to the stream. Though you can use this filter directly, you should use XsltTask which is shortcut to the following lines:

    <filterchain>
      <xsltfilter style="somexslt.xsl" />
    </filterchain>

### Attributes

Attributes for the <xsltfilter> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
style | String | The XSLT stylesheet to use for transformation. | n/a | Yes
html | Boolean | Whether to parse the input as HTML (using libxml2 DOMDocument::loadHTML()). | false | No
resolvedocumentexternals | Boolean | Whether to resolve entities in the XML document. (see this link for details) | false | No
resolvestylesheetexternals | Boolean | Whether to resolve entities in the stylesheet. | false | No

### Nested Tags

The XsltFilter filter may contain one or more param tags to pass any XSLT parameters to the stylesheet. These param tags must have name and expression attributes.