<?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:
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.
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:
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.
