Pyrus plugins: custom file roles
Introduction
If you are not familiar with how file roles install, read the
introduction to file roles
first. This segment of the documentation assumes you are familiar with
concepts such as baseinstalldir and with what a file
role means in terms of installation location.
Custom file roles can implement a single role, and are defined by
an xml file that is noted in package.xml with the customrole
file role. The XML format is defined and validated by pyrus with the
customrole-2.0.xsd
XSchema file.
Here is a human-readable custom file role xml file definition.
Optional elements are enclosed in [brackets], and if there is a choice of
values, they are delimited with a vertical bar | and
enclosed in (parentheses).
<?xml version="1.0" encoding="UTF-8"?>
<role version="2.0" xmlns="http://pear2.php.net/dtd/customrole-2.0">
<name>rolename</name>
<class>MyPlugin_Rolename</class>
[<validationmethod>validate</validationmethod>]
[<autoloadpath>relative/path/to/MyPlugin</autoloadpath>]
(<releasetype>php</releasetype>|<releasetype>extsrc</releasetype>|
<releasetype>extbin</releasetype>|<releasetype>zendextsrc</releasetype>|
<releasetype>zendextbin</releasetype>)
<installable>(1|0)</installable>
<locationconfig>config_var</locationconfig>
<honorsbaseinstall>(1|0)</honorsbaseinstall>
<unusualbaseinstall>(1|0)</unusualbaseinstall>
<executable>(1|0)</executable>
[<configvar>
<name>config_name</name>
<type>string</type>
<default>
<![CDATA[
<?php $default = 'hi'; ?>
]]>
</default>
<doc>Extensive, multi-line documentation</doc>
[<validset>val1</validset><validset>val2</validset>...]
<prompt>summary documentation</prompt>
<group>Custom</group>
<configtype>(system|user|channel-specific)</configtype>
</configvar>]*
</role>
Telling Pyrus how to load your role: <class> and <autoloadpath>
This is the same method used for all plugins, and is documented here.
Validating your custom role at packaging time
Some roles benefit from the ability to validate the files they represent
at packaging time. For instance, a customcommand file
is checked to ensure it conforms to its XML schema, so that a custom command
with invalid XML cannot be distributed by mistake.
By convention, a validation method should be named validate,
although the xml supports any name. The method name should be placed in
the <validationmethod tag, and the method itself should
have the same method signature as this example from Pyrus's
customrole validation:
<?php
function validate(\PEAR2\Pyrus\IPackage $package, array $file)
{
$parser = new \PEAR2\Pyrus\XMLParser;
$schemapath = \PEAR2\Pyrus\Main::getDataPath();
if (!file_exists(\PEAR2\Pyrus\Main::getDataPath() . '/customrole-2.0.xsd')) {
$schemapath = realpath(__DIR__ . '/../../../../data');
}
$taskschema = $schemapath . '/customrole-2.0.xsd';
try {
$taskinfo = $parser->parse($package->getFilePath($file['attribs']['name']), $taskschema);
} catch (\Exception $e) {
throw new \PEAR2\Pyrus\Installer\Role\Exception('Invalid custom role definition file,' .
' file does not conform to the schema', $e);
}
}
?>
A custom file role package-time validator should throw a
PEAR2_Pyrus_Installer_Role_Exception exception object
with an error message describing the reason for validation failure, or simply
return on success.
Release Types and file roles
The <releasetype> element is used to tell Pyrus
which releases can contain a file with this role. For instance, the
src role only has meaning in a PHP extension source release,
and is only allowed in extsrc and zendextsrc
release types.
There are 5 release types that Pyrus recognizes:
php- this is for PEAR-style packages distributing PHP codeextsrc- this is for PHP extension source packagesextbin- this is for PHP extension binary packageszendextsrc- this is for PHP Zend extension source packageszendextbin- this is for PHP Zend extension binary packages
<installable>
If set to 0, the file will not actually be installed onto
the system. Most file roles should set this to 1.
<locationconfig>
This element is used to tell Pyrus which configuration variable should be used to determine where to install the file. This can be a custom configuration variable.
<honorsbaseinstall> and <unusualbaseinstall>
The <honorsbaseinstall> element tells Pyrus to
honor the baseinstalldir attribute (documentation on
baseinstalldir is here)
for roles like php.
The <unusualbaseinstall> element tells Pyrus to
honor the baseinstalldir attribute for roles like
data that also prepend channel/package name to the
installation location.
<executable>
If <executable> is set to 1,
Pyrus will make the installed file an executable file on unix systems
(the equivalent of
chmod +x filename
).
Defining custom configuration variables
A custom file role can optionally define a single or multiple custom
configuration variables. There are 3 kinds of configuration variables
that Pyrus supports, system, user and
channel-specific. Documentation on configuration is
available here. Read that before
continuing in order to understand how different configuration variables work.
Pyrus supports one type of configuration variable: string.
The values can be restricted to a specific set of values with the
<validset> element.