Pyrus Custom File Roles: differences from PEAR

Custom file roles (documented here) have changed substantially in Pyrus. Fortunately, the usage of roles in package.xml remains unchanged, and Pyrus's expectation of custom role implementation does not conflict or overlap with PEAR's at all, so custom role packages can easily be designed to work with both PEAR and Pyrus.

The biggest difference between how a custom role is implemented in Pyrus has to do with the new plugin system (documented here). Before reading any further, it may be a good idea to familiarize yourself with the way that plugins work in Pyrus by reading the documentation on plugins, then return back to finish reading about custom roles.

Pyrus modifies the XML description file for custom file roles slightly, here is the PEAR version of a role:

<role version="1.0">
 <releasetypes>php</releasetypes>
 <releasetypes>extsrc</releasetypes>
 <releasetypes>extbin</releasetypes>
 <releasetypes>zendextsrc</releasetypes>
 <releasetypes>zendextbin</releasetypes>
 <installable>1</installable>
 <locationconfig>php_dir</locationconfig>
 <honorsbaseinstall>1</honorsbaseinstall>
 <unusualbaseinstall />
 <phpfile>1</phpfile>
 <executable />
 <phpextension />
 <config_vars />
</role>

And the same role as implemented in Pyrus:

<role version="2.0" xmlns="http://pear2.php.net/dtd/customrole-2.0">
 <name>php</name>
 <class>PEAR2\Pyrus\Installer\Role\Php</class>
 <releasetypes>php</releasetypes>
 <releasetypes>extsrc</releasetypes>
 <releasetypes>extbin</releasetypes>
 <releasetypes>zendextsrc</releasetypes>
 <releasetypes>zendextbin</releasetypes>
 <installable>1</installable>
 <locationconfig>php_dir</locationconfig>
 <honorsbaseinstall>1</honorsbaseinstall>
 <unusualbaseinstall />
 <executable />
</role>

The most obvious difference is that Pyrus now includes the name of the role, PEAR extracts the role name from the name of the file (which in the example above was Php.xml). In addition, the <phpfile> and <phpextension> elements have been removed.

The details of new tags like <class> and <autoloadpath> are documented in the full documentation of custom roles here.

This XML metadata file is identified by Pyrus through the use of the file role customrole, which is used in the custom role's package.xml. Here is an example from the <contents> of a package.xml:

...
  <contents>
   <dir name="data">
    <file name="myrole.xml" role="customrole"/>
    <file name="someotherdata.csv" role="data"/>
   </dir>
  </contents>
...