Phing Guide - Core Types

# Appendix D: Core Types

This appendix contains a reference of the system data types contained in Phing.

## FileList

FileLists offer a way to represent a specific list of files. Unlike FileSets, FileLists may contain files that do not exist on the filesystem. Also, FileLists can represent files in a specific order -- whereas FileSets represent files in whichever order they are returned by the filesystem.

### Usage Examples

    <filelist dir="/etc" files="httpd/conf/httpd.conf,php.ini"/>

Or you can use a listfile, which is expected to contain one filename per line:

    <filelist dir="conf/" listfile="ini_files.txt"/>

This will grab each file as listed in ini_files.txt. This can be useful if one task compiles a list of files to process and another task needs to read in that list and perform some action to those files.

### Attributes

Attributes for the <fileset> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
dir | String | The directory, to which the paths given in files or listfile are relative. | n/a | Yes
files | String | Comma or space-separated list of files. | n/a | Yes (or listfile)
listfile | String | A text file with one filename per line. | n/a | Yes (or files)

## FileSet

FileSets offer an easy and straightforward way to include files. The tag supports Selectors and PatternSets. Additionally, you can include/exclude files in/from a fileset using the <include>/<exclude> tags. In patterns, one asterisk (*) maps to a part of a file/directory name within a directory level. Two asterisks (**) may include above the "border" of the directory separator.

### Examples

- test*.xml will include test_42.xml, but it will not include test/some.xml.
- test**.xml fits to test_42.xml as well as to test/bla.xml, for example.
- **/*.ent.xml fits to all files that end with ent.xml in all subdirectories of the directory specified with the dir attribute of the <fileset> tag. However, it will not include any files that are directly in the base directory of the file set.

### Usage Example

    <fileset dir="/etc" >
      <include name="httpd/**" />
      <include name="php.ini" />
    </fileset>

    <fileset dir="/etc" >
      <patternset>
        <include name="**/*.php"/>
        <exclude name="**/*Test*"/>
      </patternset>
    </fileset>

This will include the apache configuration and PHP configuration file from /etc.

### Attributes

Attributes for the <fileset> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
dir | String | The directory, the paths given in include/exclude are relative to. | n/a | Yes
defaultexcludes | Boolean | Whether default exclusions should be used or not. Default excludes are:
    *~, #*#, .#*, %*%, CVS, CVS/**, .cvsignore, SCCS, SCCS/**, vssver.scc, .svn, .svn/**, ._*, .DS_Store, .darcs, .darcs/**
| True | No
casesensitive | Boolean | The case sensitivity of the file system. | True | No
expandsymboliclinks | Boolean | Whether to expand/dereference (follow) symbolic links - set to 'true' to emulate old Phing behavior. | False | No
includes | String | Comma- or space-separated list of patterns of files that must be included; all files are included when omitted. | n/a | No
includesfile | String | The name of a file; each line of this file is taken to be an include pattern. | n/a | No
excludes | String | comma- or space-separated list of patterns of files that must be excluded; no files (except default excludes) are excluded when omitted. | n/a | No
excludesfile | String | The name of a file; each line of this file is taken to be an exclude pattern. | n/a | No

### Nested Tags

The tags that are supported by Fileset are <include>, <exclude> and <patternset>. The <include> and the <exclude> tags tags must have a name attribute that contains the pattern to include/exclude.

## PatternSet

The PatternSet data type defines patterns that can be grouped into sets and nested into FileSets. Patterns can be specified by nested <include> or <exclude> elements.

### Usage Example

    <patternset id="no.tests">
      <include name="**/*.php"/>
      <exclude name="**/*Test*"/>
    </patternset>

### Attributes

Attributes for <patternset> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
includes | String | Comma- or space-separated list of patterns of files that must be included; all files are included when omitted. | n/a | No
includesfile | String | The name of a file; each line of this file is taken to be an include pattern. | n/a | No
excludes | String | comma- or space-separated list of patterns of files that must be excluded; no files (except default excludes) are excluded when omitted. | n/a | No
excludesfile | String | The name of a file; each line of this file is taken to be an exclude pattern. | n/a | No

### Nested Tags

The <patternset> tag only supports <include> and <exclude>. The <include> and the <exclude> tags tags must have a name attribute that contains the pattern to include/exclude.

## Path / Classpath

The Path data type can be used to respresent path structures. In many cases the path type will be used for nested <classpath> tags. E.g.

    <path id="project.class.path">
      <pathelement dir="lib/"/>
      <pathelement dir="ext/"/>
    </path>

    <target name="blah">
      <taskdef name="mytask" path="myapp.phing.tasks.MyTask">
        <classpath refid="project.class.path"/>
      </taskdef>
    </target>

### Attributes

Attributes for <path> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
dir | String | Specific path to directory | n/a | No
path | String | A path (which contains multiple locations separated by path.separator) to add. | n/a | No

### Nested Tags

The <path> tag supports nested <fileset> and <dirset> tags.