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="http://pear.php.net/dtd/package-2.0" xmlns:tasks="http://pear.php.net/dtd/tasks-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0 http://pear.php.net/dtd/tasks-1.0.xsd http://pear.php.net/dtd/package-2.0 http://pear.php.net/dtd/package-2.0.xsd"> <name>Chiarafoo</name> <channel>pear.chiaraquartet.net</channel> <summary>Chiarafoo role</summary> <description> The chiarafoo role installs files into your customized Foo directory </description> <lead> <name>Greg Beaver</name> <user>cellog</user> <email>cellog@php.net</email> <active>yes</active> </lead> <date>2005-03-21</date> <version> <release>1.0.0</release> <api>1.0.0</api> </version> <stability> <release>stable</release> <api>stable</api> </stability> <license uri="http://www.php.net/license">PHP License</license> <notes> Provides the chiarafoo file role </notes> <contents> <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"/> </file> </dir>  </contents> <dependencies> <required> <php> <min>4.2.0</min> </php> <pearinstaller> <min>1.4.3</min> </pearinstaller> </required> </dependencies> <phprelease/> </package>

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

<role version="1.0"> <releasetypes>php</releasetypes> <installable>1</installable> <locationconfig>foo_dir</locationconfig> <honorsbaseinstall>1</honorsbaseinstall> <unusualbaseinstall /> <phpfile>1</phpfile> <executable /> <phpextension /> <config_vars> <foo_dir> <type>directory</type> <default><php_dir/><constant>DIRECTORY_SEPARATOR</constant><text>Foo</text></default> <doc>directory where foo files are installed</doc> <prompt>PHP foo directory</prompt> <group>File Locations</group> </foo_dir> </config_vars> </role>

The script in Chiarafoo.php is incredibly simple:

<?php /** * 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: * http://www.php.net/license/3_0.txt. 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 license@php.net so we can mail you a copy immediately. * * @category pear * @package Chiarafoo * @author Greg Beaver <cellog@php.net> * @copyright 2005 Greg Beaver * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @version CVS: $Id: customroles.xml,v 1.4 2005/11/03 05:06:52 cellog Exp $ * @link http://pear.chiaraquartet.net/index.php?package=Chiarafoo * @since File available since Release 0.1.0 */ /** * @category pear * @package Chiarafoo * @author Greg Beaver <cellog@php.net> * @copyright 2005 Greg Beaver * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @version Release: @package_version@ * @link http://pear.chiaraquartet.net/index.php?package=Chiarafoo * @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 <releasetypes> tag

This tag can only contain one of the following values:

php
extsrc
extbin

In order to specify compatibility with multiple release types, use multiple <releasetypes> tags as in:

<releasetypes>php</releasetypes> <releasetypes>extsrc</releasetypes> <releasetypes>extbin</releasetypes>

releasetypes defines the kind of releases that this role can be used in. For instance, the "src" role is reserved for extsrc packages, and cannot be used in regular PEAR-style php releases. The "data" role can be used in any release, and would define <releasetypes> as:

<releasetypes>php</releasetypes> <releasetypes>extsrc</releasetypes> <releasetypes>extbin</releasetypes>

The <installable> tag

This tag must be either <installable>1</installable> or empty (<installable/>) and determines whether files utilizing this custom role can be installed. Any file that should be installed must set this to 1. Only roles such as the "src" role that is processed and used to create the files that are eventually installed should set this to an empty tag.

The <locationconfig> tag

This tag is used for all installable files to determine which configuration variable contains the directory in which the file should be installed. For instance, the php role uses the "php_dir" locationconfig, the data role uses "data_dir".

Our example role, chiarafoo, uses the "foo_dir" configuration variable, and then through the definition of <config_vars> tells the installer what foo_dir means. Note that once a custom role is installed, the user can config-set/ config-get/config-show the variable just like any other configuration variable!

<config_vars> can define more than one configuration variable, but note that more than 3 variables will trigger an error, disallowing any of them, as a security precaution.

The <honorsbaseinstall> tag

This tag controls whether a role reacts to the "baseinstalldir" attribute of a <file> or <dir> tag. Any role that honors baseinstalldir can potentially allow conflicting files from different packages, and so a check has to be made. A file role that does not honor baseinstalldir is always installed into:

Packagename/full/path/from/contents/file.ext

To specify this value, use <honorsbaseinstall>1</honorsbaseinstall> For all other cases, it should be an empty tag (<honorsbaseinstall/>)

The <unusualbaseinstall> tag

This tag controls whether a role that would normally ignore the "baseinstalldir" attribute of a <file> or <dir> tag would honor it, but still use the Packagename/baseinstalldir/full/path/from/contents/file.ext instead of baseinstalldir/full/path/from/contents/file.ext. Any role that supports the unusual baseinstalldir type cannot conflict with other files because the package name is always the parent directory. To specify this value, use <unusualbaseinstall>1</unusualbaseinstall> For all other cases, it should be an empty tag (<unusualbaseinstall/>)

The <phpfile> tag

This tag should be set to 1 (<phpfile>1</phpfile>) for any roles that contain php script files. These files are analyzed at package time, possibly catching errors before release. For all other cases, it should be an empty tag (<phpfile/>)

The <executable> tag

This tag should be set to 1 (<executable>1</executable>) for roles like the "script" role that should have their executable attribute set via chmod() on install. For all other cases, it should be an empty tag (<executable/>)

The <phpextension> tag

This tag should be used for roles like the "ext" role that provide a binary PHP extension. To specify this value, use <phpextension>1</phpextension> For all other cases, it should be an empty tag (<phpextension/>)

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.

array( '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', 'default' => PEAR_CONFIG_DEFAULT_PREFERRED_STATE, '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:

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

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:
<default><php_dir/><constant>DIRECTORY_SEPARATOR</constant><text>Foo</text></default>

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.