File roles

Pyrus and The PEAR Installer categorize file types by their role. A file role is equivalent to the web's concept of MIME type, a concept that allows web browsers to determine how a file should be displayed or processed. A file role allows Pyrus and the PEAR Installer to determine where a file should be installed, the conditions under which the role can be used, and even whether the file should be installed at all. A file may only have one role in a package.

Generally speaking, each file role has its own installation location. For example, php files (files whose file role is php) are installed into the location specified by the php_dir configuration variable, data files (files whose file role is data) are installed into the location specified by the data_dir configuration variable. Some file roles do not have a direct mapping of role name to configuration variable, such as Pyrus's customcommand file role. This file role is installed into the location specified by the data_dir configuration variable.

File roles also control how package.xml attributes are handled. The php file role installs files into the exact relative path as specified in package.xml. The data file role always installs files into a subdirectory containing the package name for PEAR packages, and both the channel and package name for packages designed to be installed by Pyrus.

Here is an example of the same file path in package.mxl as php role and as data role. All examples assume this is a package named PackageName in the pear2.php.net channel.

  <contents>
   <dir name="\">
    <dir name="base">
     <file name="foo" role="php">
    </dir>
   </dir>
  </contents>

This installs as base/foo in the location specified by php_dir.

  <contents>
   <dir name="\">
    <dir name="base">
     <file name="foo" role="data">
    </dir>
   </dir>
  </contents>

For PEAR Installer packages, this installs as PackageName/base/foo in the location specified by php_dir. For Pyrus packages, this installs as pear2.php.net/PackageName/base/foo.

How the baseinstalldir attribute is handled by different file roles

The baseinstalldir (base installation directory) attribute is a tool that can be used to install a file into a different directory than its location in the source repository.

As an example, the path in the subversion repository to the file PEAR2\Foo.php is at Foo.php. To inform the installer to install this package into the PEAR2 directory, we would use a baseinstalldir attribute:

   <contents>
    <dir name="\">
     <file name="Foo.php" role="php" baseinstalldir="PEAR2">
    </dir>
   </contents>

The attribute can also be used on <dir> tags to apply the base installation directory to all files within the directory:

   <contents>
    <dir name="\" baseinstalldir="PEAR2">
     <file name="Foo.php" role="php">
    </dir>
   </contents>

The baseinstalldir role can also be used to inform the PEAR Installer or Pyrus to strip all relative paths by using / as the base installation directory. Here is an example from the PEAR package:

   <dir name="scripts" baseinstalldir="/">
    <file name="pear.bat" role="script"/>

This file would be installed as scripts/pear.bat, but the baseinstalldir attribute of / informs the installer to instead install it to pear.bat.

Each file role reacts differently to the baseinstalldir attribute. Packages designed to be installed by the PEAR Installer also handle them differently from packages designed for installation by Pyrus. The php, script and www file roles react the same way as documented above. In packages designed for the PEAR Installer, the other file roles do not honor the baseinstalldir attribute, meaning they ignore it. For example:

   <contents>
    <dir name="\" baseinstalldir="PEAR2">
     <file name="Foo.dat" role="data">
    </dir>
   </contents>

installs Foo.dat into the PackageName/Foo.dat directory. The same XML in a package designed for installation by Pyrus will install the file into pear2.php.net/PackageName/PEAR2/Foo.dat.