Defining a customized role for use in a package.xml

To define a custom role, you need to create a package containing a single file. Here is a sample package.xml that could be a custom role:

<?xml version="1.0"?>
<package version="2.0" xmlns=""
 <summary>Chiarafoo role</summary>
  The chiarafoo role installs files into your customized Foo directory
  <name>Greg Beaver</name>
 <license uri="">PHP License</license>
  Provides the chiarafoo file role
  <dir name="/" baseinstalldir="PEAR/Installer/Role">
   <file name="Chiarafoo.xml" role="php"/>
   <file name="Chiarafoo.php" role="php">
    <tasks:replace from="@package_version@" to="version" type="package-info"/>
  </dir> <!-- / -->

The XML file Chiarafoo.xml should be similar to this file:

<role version="1.0">
 <unusualbaseinstall />
 <executable />
 <phpextension />
   <doc>directory where foo files are installed</doc>
   <prompt>PHP foo directory</prompt>
   <group>File Locations</group>

The script in Chiarafoo.php is incredibly simple:

 * PEAR_Installer_Role_Chiarafoo
 * PHP versions 4 and 5
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 *  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to so we can mail you a copy immediately.
 * @category   pear
 * @package    Chiarafoo
 * @author     Greg Beaver <>
 * @copyright  2005 Greg Beaver
 * @license  PHP License 3.0
 * @version    CVS: $Id: customroles.xml,v 1.4 2005/11/03 05:06:52 cellog Exp $
 * @link
 * @since      File available since Release 0.1.0

 * @category   pear
 * @package    Chiarafoo
 * @author     Greg Beaver <>
 * @copyright  2005 Greg Beaver
 * @license  PHP License 3.0
 * @version    Release: @package_version@
 * @link
 * @since      Class available since Release 0.1.0
 */ class PEAR_Installer_Role_Chiarafoo extends PEAR_Installer_Role_Common
     * @param PEAR_Installer
     * @param PEAR_PackageFile_v2
     * @param array file attributes
     * @param string relative path to file in package.xml
    function setup(&$installer, $pkg, $atts, $file)
        // do something special with the installer

Since PEAR 1.4.3, nothing else is necessary for a successful implementation of a file role.

The contents of the role's XML file must contain these tags:

The optional <config_vars> tag

This tag is used to define configuration variables that should be added to the installer by this custom file role. Note that the installer will not allow a custom file role to create more than 3 configuration variables. To define configuration variables, create tags with the name of the configuration variable, and then sub-tags defining information about the configuration variable.

These tags are transformed into the PHP array format expected by the PEAR_Config class using an adapted version of Stephan Schmidt's excellent XML_Unserializer class (from the XML_Serializer package). As such, it is easiest to understand the XML format by examining existing configuration variables.

        'password' => array(
            'type' => 'password',
            'default' => '',
            'doc' => '(maintainers) your PEAR account password',
            'prompt' => 'PEAR password (for maintainers)',
            'group' => 'Maintainers',
        // Advanced
        'verbose' => array(
            'type' => 'integer',
            'default' => PEAR_CONFIG_DEFAULT_VERBOSE,
            'doc' => 'verbosity level
0: really quiet
1: somewhat quiet
2: verbose
3: debug',
            'prompt' => 'Debug Log Level',
            'group' => 'Advanced',
        'preferred_state' => array(
            'type' => 'set',
            'doc' => 'the installer will prefer releases with this state when installing packages without a version or state specified',
            'valid_set' => array(
                'stable', 'beta', 'alpha', 'devel', 'snapshot'),
            'prompt' => 'Preferred Package State',
            'group' => 'Advanced',

These sample configuration values from the actual PEAR_Config class would translate into this XML:

  <default />
  <doc>(maintainers) your PEAR account password'</doc>
  <prompt>PEAR password (for maintainers)</prompt>
  <doc>verbosity level
0: really quiet
1: somewhat quiet
2: verbose
3: debug</doc>
  <prompt>Debug Log Level</prompt>
  <doc>the installer will prefer releases with this state when installing packages without a version or state specified</doc>
  <prompt>Preferred Package State</prompt>

Note that the simple array defining the set converts each value into a separate <valid_set> tag for the preferred_state configuration variable.

The <default> tag's value can accept either a simple string, or three different kinds of tags:

  • <text> - this will be converted into a PHP string

  • <constant> - the contents of this sub-tag will be used to retrieve the value of a pre-defined PHP constant, or a pre-defined PEAR constant (as defined in PEAR_Config or PEAR_Common) and substitute the value for the <constant> tag.

  • any default configuration variable. These include default_channel, preferred_mirror, remote_config, auto_discover, master_server, http_proxy, php_dir, ext_dir, doc_dir, bin_dir, data_dir, test_dir, cache_dir, php_bin, username, password, verbose, preferred_state, umask, cache_ttl, sig_type, sig_bin, sig_keyid, and sig_keydir.

    when used, the configuration variable should simply be an empty tag like <php_dir/>. The tag will be replaced with the default value of the configuration variable, not the currently assigned value.

For instance, this example default value:

<default><text0>hi there </text0><constant>PHP_OS</constant><text1> user, your default php_dir is </text1><php_dir/></default>

might convert into something like "hi there Linux user, your default php_dir is /usr/local/lib/php/pear".

Our example Chiarafoo role's foo_dir default value:


might convert into something like "/usr/local/lib/php/Foo" or "C:\php5\pear\Foo".

Note that in order to use multiple <constant> or <text> tags, you must append a numbered suffix as in the <text0> <text1> example above. Only one PEAR configuration variable may be used per default value.

Note that if you use <type>integer</type>, no matter what default value is specified, it will be casted into an integer by PEAR_Config.

    Поддержать сайт на родительском проекте КГБ