Pyrus plugins: custom file roles
Prev		Next

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 code
extsrc - this is for PHP extension source packages
extbin - this is for PHP extension binary packages
zendextsrc - this is for PHP Zend extension source packages
zendextbin - 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.

Prev	Creating plugins for Pyrus	Next
Pyrus plugins: custom commands	PEAR Manual	Pyrus plugins: custom file tasks