Phing Guide - Core Mappers

# Appendix D-3: Core Mappers

While filters are applied to the content of files, Mappers are applied to the filenames. All mappers have the same API, i.e. the way you use them is the same:

    <mapper type="mappername" from="frompattern" to="topattern" />

### Attributes

Attributes for the <mapper> tag
Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
type | String | Type of the mapper. | n/a | One of these is required.
classname | String | Dot-path to a custom mapper class to use. | n/a
from | String | The pattern the filename is to be matched to. The exact meaning is dependent on the implementation of the mapper. | n/a | depends on the implementation of the mapper
to | String | The pattern according to which the filename is to be changed to. Here, the usage is dependent on the implementation of the mapper, too. | n/a | depends on the implementation of the mapper

## FlattenMapper

The FlattenMapper removes the directories from a filename and solely returns the filename.

    <copy todir="/tmp">
      <mapper type="flatten" />

      <fileset refid="someid" />
    </copy>

This code will copy all files in the fileset to /tmp. All files will be in the target directory.

### Examples

    <mapper type="flatten" />

Applying the mapper, you will get the following results from the following filenames:

From | To
--- | ---
test.txt | test.txt
./foo/bar/test.bak | test.bak

## GlobMapper

The GlobMapper works like the copy command in DOS:

    <copy todir="/tmp">
      <mapper type="glob" from="*.php" to="*.php.bak"/>

      <fileset refid="someid" />
    </copy>

This will change the extension of all files matching the pattern *.php to .php.bak.

### Examples

    <mapper type="glob" from="*txt" to="*txt.bak"/>

Applying the mapper, you will get the following results from the following filenames:

From | To
--- | ---
test.txt | test.txt.bak
./foo/bar/test.txt | ./foo/bar/test.txt.bak
mytxt | mytxt.bak
SomeClass.php | ignored, SomeClass.php

## IdentityMapper

The IdentityMapper will not change anything on the source filenames.

## MergeMapper

The MergeMapper changes all source filenames to the same filename.

### Examples

    <mapper type="merge" to="test.tar"/>

Applying the mapper, you will get the following results from the following filenames:

From | To
--- | ---
test.txt | test.tar
./foo/bar/test.txt | test.tar
mytxt | test.tar
SomeClass.php | test.tar

## RegexpMapper

The RegexpMapper changes filenames according to a pattern defined by a regular expression. This is the most powerful mapper and you should be able to use it for every possible application.

### Examples

    <mapper type="regexp" from="^(.*)\.conf\.xml" to="\1.php"/>

The mapper as above will do the following mappings:

From | To
--- | ---
test.txt | ignore, test.txt
./foo/bar/test.conf.xml | ./foo/bar/test.php
someconf.conf.xml | someconf.php