Documenting custom file roles

Standard file roles provided by default with PEAR are:

• php

• data

• doc

• test

• script

• src

• ext

If your package chooses to use a role provided by a third party that implements some more advanced file installation handling, all you need to do is specify the role in the xml for the <file> tag that contains it like so:

<file role="foo"/>

However, if a user does not have the package installed that provides the custom role "foo", then the error message on installation will simply say "unknown role 'foo'", which is not very helpful.

The <usesrole> tag instead prompts the installer to tell the user "this package uses the custom role 'foo', install package pear.example.com/Foo to use"

<usesrole>
 <role>foo</role>
 <package>Foo</package>
 <channel>pear.example.com</channel>
</usesrole>

Note that static URI packages (channel-less packages) are also supported:

<usesrole>
 <role>foo</role>
 <uri>http://pear.example.com/Foo-1.2.0</uri>
</usesrole>