Defining a customized role for use in a package.xml

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:

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.

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.

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/>)

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/>)

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/>)

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/>)

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/>)

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.

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.