The user configuration file is always stored in the user's personal directory, the home directory on unix, and My Documents on Windows. For a unix user with username user, the user configuration file is stored in /home/user/.pear/pearconfig.xml. For a Windows user, the configuration is stored in My Documents\pear\pearconfig.xml. The file is saved in XML format and can be hand-edited if necessary.

Unlike the system configuration file, the user configuration file is always saved when an operation that writes to disk is called, such as installing a package. On startup, Pyrus uses the configuration file's existence to determine whether it is being executed for the first time, and if so, prompts the user to initialize a few default settings such as the PEAR path.

There are two kinds of user configuration variables, installation-wide variables such as verbose, and channel-specific variables such as openssl_cert. Channel-specific variables can have different values for different channels. This allows setting a different certificate for each channel, for instance. The channel name is used as a tag, with non-XML friendly characters translated into simple mnemonics (such as . becoming DOT).

Here is a sample user configuration file (with line breaks added for readability):

<?xml version="1.0"?>
<pearconfig version="1.0">
 <default_channel>pear2.php.net</default_channel>
 <auto_discover>0</auto_discover>
 <http_proxy></http_proxy>
 <cache_dir>/home/user/testpear/cache</cache_dir>
 <temp_dir>/home/user/testpear/temp</temp_dir>
 <verbose>1</verbose>
 <paranoia>2</paranoia>
 <preferred_state>stable</preferred_state>
 <umask>0022</umask>
 <cache_ttl>3600</cache_ttl>
 <my_pear_path>/home/user/testpear:/usr/local/lib/php</my_pear_path>
 <plugins_dir>/home/user/.pear</plugins_dir>
 <openssl_cert>
  <pear2DOTphpDOTnet>/home/user/mykey.p12</pear2DOTphpDOTnet>
 </openssl_cert>
 <handle>
  <pear2DOTphpDOTnet>cellog</pear2DOTphpDOTnet>
 </handle>
</pearconfig>

The system configuration file is always saved in a file named .config in the base of the PEAR installation. Thus, if php files are installed in /usr/local/lib/pear/php, then the configuration for that installation is installed in /usr/local/lib/pear/.config. The configuration is stored in XML format, and can be modified by hand if necessary.

The configuration will not be saved if no values are modified from the default values

Here is a sample system configuration file (with line breaks added for readability):

<?xml version="1.0"?>
<pearconfig version="1.0">
 <ext_dir>/usr/local/lib/php/extensions/debug-non-zts-20090115</ext_dir>
 <cfg_dir>/home/user/testpear/cfg</cfg_dir>
 <doc_dir>/home/user/testpear/mydata</doc_dir>
 <bin_dir>/usr/local/bin</bin_dir>
 <www_dir>/home/user/testpear/www</www_dir>
 <test_dir>/home/user/testpear/tests</test_dir>
 <src_dir>/home/user/testpear/src</src_dir>
 <php_bin>/usr/local/bin/php</php_bin>
 <php_ini>/usr/local/lib/php.ini</php_ini>
 <php_prefix></php_prefix>
 <php_suffix></php_suffix>
</pearconfig>

Pyrus is a re-factored version of the PEAR installer, re-designed for new features available in PHP 5.3 and newer. As a result, Pyrus is more robust than PEAR as well as faster. Several of the subtle design flaws in the PEAR Installer have been fixed, and so Pyrus is more stable than the PEAR Installer for handling an existing PEAR repository.

Here is a brief summary of the differences from PEAR:

One of the most important conceptual changes in Pyrus is how configuration is handled. PEAR was designed to handle at most 2 installations by default, a system and a user PEAR installation, and it excels at this. As soon as PEAR is used on multiple installations, a separate configuration file must be specified (as in pear -c /path/to/another/pear.conf install blah). This leads to what is colloquially referred to as "config hell", where it is easy to accidentally install things into the wrong place without realizing it. Pyrus's configuration handling is specifically engineered to eliminate config hell, and to make handling multiple PEAR installations simple.

PEAR stores all configuration values in a single configuration file, and allows specifying a different configuration file for different setups. In addition, PEAR supports automatic cascade of a system configuration file and a user configuration file. The configuration values are used when installing applications, and for customizing things like the path to php in the PEAR Installer's pear command. Configuration files are stored separate from the PEAR installations that they represent.

Pyrus instead splits up configuration files into two separate components: one file contains user customizations such as the preferred stability of packages to install, the username and password for logging into a channel, the verbose setting and so on. Configuration variables that affect where to install files are stored in a separate configuration that is tightly bound to the PEAR installation.

Thus, a PEAR configuration setup might look like:

• System configuration in /etc/pear.conf, defines php_dir as /usr/local/lib/php
• User configuration in /home/username/.pearrc, defines php_dir as /home/username/pear.
• include_path is set to /home/username/pear:/usr/local/lib/php.

The equivalent configuration setup with Pyrus would look like:

• Pyrus-based installation in /usr/local/lib/pear, system configuration stored in /usr/local/pear/.config and php files in /usr/local/lib/pear/php.
• Another Pyrus-based installation in /home/username/pear, system configuration stored in /home/username/pear/.config and php files in /home/username/pear/php.
• User configuration in /home/username/.pear/pearconfig.xml.
• include_path is set to /home/username/pear:/usr/local/lib/pear/php.

By default, Pyrus uses the include_path to locate PEAR installations, but this is configurable with the new user configuration variable my_pear_path, which is a PATH_SEPARATOR separated list of paths to PEAR installations.

In addition, an explicit path can be directly passed to Pyrus:

php pyrus.phar /home/username/pear:/usr/local/lib/pear list-packages

The above command will list the installed packages in both registries in /home/username/pear and in /usr/local/lib/pear/php.

A detailed reference of Pyrus's handling of configuration files is here

Pyrus fully supports PEAR's registry format, but introduces 2 new registry formats, an sqlite3 database-based registry, and an XML file-based registry. These registries are fully redundant, and can be used to repair or reconstruct a corrupt registry.

In addition, unlike PEAR, which stores the registry in the same directory as the PHP source files, Pyrus stores the registry in its parent directory. Thus, PHP files stored in /usr/local/lib/php have their registry in /usr/local/lib.

For backwards compatibility, an older PEAR registry is always stored in the location the PEAR Installer expects it to be stored.

Pyrus is intelligent enough to detect which registries are present, and to use them. If only an older PEAR registry exists, Pyrus will not automatically upgrade to the newer format. However, the upgrade-registries command is available to convert from an older registry to the newer format.

Some of the benefits of the newer registry format include much speedier processing of a large registry at installation time due to Sqlite3's speedy processing. Additionally, truly safe uninstall-time resolution of dependencies is possible, something that PEAR can only do for relatively simple package dependency trees.

In addition, the XML registry consists of storing the package.xml and channel.xml files for package releases in the same location that they are packaged. This is what makes it possible to extract a package created with Pyrus and then later use Pyrus to upgrade it.

For instance, the hypothetical PEAR2_Foo package from channel pear2.php.net version 1.2.3 will store its package.xml in path .xmlregistry/packages/pear2.php.net/PEAR2_Foo/1.2.3-package.xml inside the archive, so that when it is extracted, it lines up exactly with how the package would look on disk when installed with the XML registry.

Pyrus no longer supports package.xml version 1.0, although it will include a package.xml version 1.0 in an archive designed to support both earlier PEAR versions and the more recent versions. It does not validate the package.xml, however, and so it is important to validate any older package.xml format using PEAR and not Pyrus.

In addition, Pyrus has introduced support for PEAR2 packages that can be extracted to disk and then later upgraded using Pyrus. To implement this feature, Pyrus transforms paths in a different way from PEAR.

For example, this entry from a package.xml:

   <dir name="php" baseinstalldir="PEAR2">
    <dir name="Pyrus">
     <dir name="Developer">
      <dir name="CoverageAnalyzer">
       <dir name="SourceFile">
        <file role="php" name="PerTest.php"/>
       </dir>
      </dir>
     </dir>
    </dir>
   </dir>

would cause PEAR to install PerTest.php into the relative path PEAR2/php/Pyrus/Developer/CoverageAnalyzer/SourceFile/PerTest.php. Pyrus, however, recognizes that php is actually the default value of the php_dir system configuration variable, and strips it from the path, resulting in PerTest.php being installed into the path: PEAR2/Pyrus/Developer/CoverageAnalyzer/SourceFile/PerTest.php.

To enable this handling, one need only set the <pearinstaller> dependency to version 2.0.0a1 or newer. Pyrus will automatically recognize any package.xml with a <pearinstaller> dependency on any version of the PEAR Installer as an older package.xml, and will not perform the magic removal of configuration values from directories.

No other changes have been made to package.xml handling, except that the default version of package.xml used when generating a package.xml is version 2.1, which has been supported by the PEAR Installer since version 1.5.0.

The PEAR Installer allowed packages to install custom commands as well as custom file roles and custom file tasks that are used in package.xml. Pyrus also allows this, but the format of plugins is very different. If you are simply a user of PEAR, you probably won't notice the difference, except that some packages that use custom file roles or tasks will not be installable by Pyrus until the maintainer releases an update that will work with both PEAR and Pyrus.

PEAR extensions are installed directly into the location where the PEAR installer is located. Thus, if PEAR is located in /usr/local/lib/php/PEAR, a custom command must install its XML information file and PHP script into /usr/local/lib/php/PEAR/Command, a custom file role must install its XML information file and PHP script into /usr/local/lib/php/PEAR/Installer/Role and a custom file task must install its PHP script into /usr/local/lib/php/PEAR/Task.

Pyrus is distributed as a phar archive, so this model is no longer physically possible, one cannot just magically insert files into the phar archive without considerable pain and annoyance (the phar.readonly INI setting must be disabled by hand). Instead, Pyrus installs all plugins into a location specified by the new plugins_dir user configuration variable. By default, this installs plugins into $HOME/.pear/plugins on unix systems, and My Documents\pear\plugins on Windows.

All plugins to Pyrus now must provide an xml file with one of the three new file roles customcommand, customrole or customtask in package.xml. Pyrus uses the information in the XML file to locate the PHP script that will execute the plugin. In addition, only one plugin is allowed per package, and the first one Pyrus encounters is the one that will be used. More information on custom plugins is provided in the Pyrus plugins section of the manual.

For developers of existing PEAR custom roles/tasks and post-install scripts, a special kind of file role that allows configuration of your package after installation, making your work compatible with Pyrus can be accomplished. See the documentation on Custom Roles, Custom Tasks, and Post-install scripts.

PEAR's handling of PECL extensions has been somewhat dodgy, with reports of issues with phpize failing, and other problems. Pyrus attempts to fix this through two major changes to the way PECL packages are built and installed.

1. PECL packages are installed into a new location src/ and then built directly inside this location.
2. The same tool process used to build extensions by hand is used verbatim by pyrus to build the extension

     
phpize --clean
phpize
./configure [any options specified by <configureoptions>]
make
make install
     
    

Post-install scripts (documented here and here) are mostly the same in Pyrus with a few important differences.

The XML format in package.xml is identical, so no change need be made to the <paramgroup> or other tags. The script itself should still follow the naming conventions of PEAR. The only real difference is the naming of methods within the script.

PEAR requires that all post-install scripts implement init(), run() and optionally postProcessPrompts(). Pyrus requires post-install scripts to implement init2(), run2(), and optionally postProcessPrompts2(). This allows PEAR and Pyrus-based post-install scripts to co-exist in the same package without difficulty. Note that post-install scripts must be E_STRICT and E_DEPRECATED compliant, otherwise many PHP warnings will be emitted. One way of handling this issue is to put PHP4 non-E_STRICT-compatible code into a separate file and include it dynamically at run-time. The same should be done for any PHP5+ non-PHP4 compatible code if the post-install script is expected to be able to run in PHP 4.

The init2() method should accept two parameters like so:

$pkg is an object representing the package, and $lastversion is the last installed version of the package.

These two methods should accept identical parameters to what the PEAR equivalent accepted. The only reason these are called is to allow easy differentiation between what kind of installer is calling the post-install script.

Custom commands have changed substantially in Pyrus. PEAR commands draw their information from Xml files located in the directory PEAR/Command and require all commands to be implemented in a single file. Pyrus is much more flexible on this account, and extends the custom XML format used to define commands. Because of this difference, it is theoretically possible to create custom commands that will work in both the PEAR Installer and in Pyrus, although the internal implementation of these commands will necessarily be quite different.

The biggest difference between how a custom command is implemented in Pyrus has to do with the new plugin system (documented here). Before reading any further, it may be a good idea to familiarize yourself with the way that plugins work in Pyrus by reading the documentation on plugins, then return back to finish reading about custom commands.

Here is PEAR's version of the xml for the install command:

<commands version="1.0">
 <install>
  <summary>Install Package</summary>
  <function>doInstall</function>
  <shortcut>i</shortcut>
  <options>
   <force>
    <shortopt>f</shortopt>
    <doc>will overwrite newer installed packages</doc>
   </force>
   <loose>
    <shortopt>l</shortopt>
    <doc>do not check for recommended dependency version</doc>
   </loose>
   <nodeps>
    <shortopt>n</shortopt>
    <doc>ignore dependencies, install anyway</doc>
   </nodeps>
   <register-only>
    <shortopt>r</shortopt>
    <doc>do not install files, only register the package as installed</doc>
   </register-only>
   <soft>
    <shortopt>s</shortopt>
    <doc>soft install, fail silently, or upgrade if already installed</doc>
   </soft>
   <nobuild>
    <shortopt>B</shortopt>
    <doc>don&#039;t build C extensions</doc>
   </nobuild>
   <nocompress>
    <shortopt>Z</shortopt>
    <doc>request uncompressed files when downloading</doc>
   </nocompress>
   <installroot>
    <shortopt>R</shortopt>
    <doc>root directory used when installing files (ala PHP&#039;s INSTALL_ROOT), use packagingroot for RPM</doc>
    <arg>DIR</arg>
   </installroot>
   <packagingroot>
    <shortopt>P</shortopt>
    <doc>root directory used when packaging files, like RPM packaging</doc>
    <arg>DIR</arg>
   </packagingroot>
   <ignore-errors>
    <shortopt></shortopt>
    <doc>force install even if there were errors</doc>
   </ignore-errors>
   <alldeps>
    <shortopt>a</shortopt>
    <doc>install all required and optional dependencies</doc>
   </alldeps>
   <onlyreqdeps>
    <shortopt>o</shortopt>
    <doc>install all required dependencies</doc>
   </onlyreqdeps>
   <offline>
    <shortopt>O</shortopt>
    <doc>do not attempt to download any urls or contact channels</doc>
   </offline>
   <pretend>
    <shortopt>p</shortopt>
    <doc>Only list the packages that would be downloaded</doc>
   </pretend>
  </options>
  <doc>[channel/]&lt;package&gt; ...
Installs one or more PEAR packages.  You can specify a package to
install in four ways:

&quot;Package-1.0.tgz&quot; : installs from a local file

&quot;http://example.com/Package-1.0.tgz&quot; : installs from
anywhere on the net.

&quot;package.xml&quot; : installs the package described in
package.xml.  Useful for testing, or for wrapping a PEAR package in
another package manager such as RPM.

&quot;Package[-version/state][.tar]&quot; : queries your default channel&#039;s server
({config master_server}) and downloads the newest package with
the preferred quality/state ({config preferred_state}).

To retrieve Package version 1.1, use &quot;Package-1.1,&quot; to retrieve
Package state beta, use &quot;Package-beta.&quot;  To retrieve an uncompressed
file, append .tar (make sure there is no file by the same name first)

To download a package from another channel, prefix with the channel name like
&quot;channel/Package&quot;

More than one package may be specified at once.  It is ok to mix these
four ways of specifying packages.
</doc>
 </install>
  </commands>

And the same command as implemented in Pyrus:

<?xml version="1.0" encoding="UTF-8"?>
<commands version="2.0" xmlns="http://pear2.php.net/dtd/customcommand-2.0">
 <command>
  <name>install</name>
  <class>PEAR2\Pyrus\ScriptFrontend\Commands</class>
  <function>install</function>
  <summary>Install a package.  Use install --plugin to install plugins</summary>
  <shortcut>i</shortcut>
  <options>
   <option>
    <name>plugin</name>
    <shortopt>p</shortopt>
    <type><bool/></type>
    <doc>Manage plugin installation only</doc>
   </option>
   <option>
    <name>packagingroot</name>
    <shortopt>r</shortopt>
    <type><string/></type>
    <doc>Install the package in a directory in preparation for packaging with tools like RPM</doc>
   </option>
   <option>
    <name>optionaldeps</name>
    <shortopt>o</shortopt>
    <type><bool/></type>
    <doc>Automatically download and install all optional dependencies</doc>
   </option>
   <option>
    <name>force</name>
    <shortopt>f</shortopt>
    <type><bool/></type>
    <doc>Force the installation to proceed independent of errors.  USE SPARINGLY.</doc>
   </option>
  </options>
  <arguments>
   <argument>
    <name>package</name>
    <multiple>1</multiple>
    <optional>0</optional>
    <doc>package.xml, local package archive, remove package archive, or abstract package.</doc>
   </argument>
  </arguments>
  <doc>Installs listed packages.

local package.xml example:
php pyrus.phar install package.xml

local package archive example:
php pyrus.phar install PackageName-1.2.0.tar

remote package archive example:
php pyrus.phar install http://www.example.com/PackageName-1.2.0.tgz

Examples of an abstract package:
php pyrus.phar install PackageName
 installs PackageName from the default channel with stability preferred_state
php pyrus.phar pear/PackageName
 installs PackageName from the pear.php.net channel with stability preferred_state
php pyrus.phar install channel://doc.php.net/PackageName
 installs PackageName from the doc.php.net channel with stability preferred_state
php pyrus.phar install PackageName-beta
 installs PackageName from the default channel, beta or stable stability
php pyrus.phar install PackageName-1.2.0
 installs PackageName from the default channel, version 1.2.0</doc>
 </command>
</commands>

The format for commands in Pyrus is much more fine-grained, and provides both better validation and better presentation of options and arguments as passed in from the user. In addition, Pyrus allows fine-grained specification of where a command is located, and automatically registers an autoloader to load the class implementing the command, and any dependent classes in the same location.

The details of new tags like <classprefix> and <autoloadpath> are documented in the full documentation of custom roles here.

This XML metadata file is identified by Pyrus through the use of the file role customcommand, which is used in the custom command's package.xml. Here is an example from the <contents> of a package.xml:

...
  <contents>
   <dir name="data">
    <file name="commands.xml" role="customcommand"/>
    <file name="someotherdata.csv" role="data"/>
   </dir>
  </contents>
...

Custom file roles (documented here) have changed substantially in Pyrus. Fortunately, the usage of roles in package.xml remains unchanged, and Pyrus's expectation of custom role implementation does not conflict or overlap with PEAR's at all, so custom role packages can easily be designed to work with both PEAR and Pyrus.

The biggest difference between how a custom role is implemented in Pyrus has to do with the new plugin system (documented here). Before reading any further, it may be a good idea to familiarize yourself with the way that plugins work in Pyrus by reading the documentation on plugins, then return back to finish reading about custom roles.

Pyrus modifies the XML description file for custom file roles slightly, here is the PEAR version of a role:

<role version="1.0">
 <releasetypes>php</releasetypes>
 <releasetypes>extsrc</releasetypes>
 <releasetypes>extbin</releasetypes>
 <releasetypes>zendextsrc</releasetypes>
 <releasetypes>zendextbin</releasetypes>
 <installable>1</installable>
 <locationconfig>php_dir</locationconfig>
 <honorsbaseinstall>1</honorsbaseinstall>
 <unusualbaseinstall />
 <phpfile>1</phpfile>
 <executable />
 <phpextension />
 <config_vars />
</role>

And the same role as implemented in Pyrus:

<role version="2.0" xmlns="http://pear2.php.net/dtd/customrole-2.0">
 <name>php</name>
 <class>PEAR2\Pyrus\Installer\Role\Php</class>
 <releasetypes>php</releasetypes>
 <releasetypes>extsrc</releasetypes>
 <releasetypes>extbin</releasetypes>
 <releasetypes>zendextsrc</releasetypes>
 <releasetypes>zendextbin</releasetypes>
 <installable>1</installable>
 <locationconfig>php_dir</locationconfig>
 <honorsbaseinstall>1</honorsbaseinstall>
 <unusualbaseinstall />
 <executable />
</role>

The most obvious difference is that Pyrus now includes the name of the role, PEAR extracts the role name from the name of the file (which in the example above was Php.xml). In addition, the <phpfile> and <phpextension> elements have been removed.

The details of new tags like <class> and <autoloadpath> are documented in the full documentation of custom roles here.

This XML metadata file is identified by Pyrus through the use of the file role customrole, which is used in the custom role's package.xml. Here is an example from the <contents> of a package.xml:

...
  <contents>
   <dir name="data">
    <file name="myrole.xml" role="customrole"/>
    <file name="someotherdata.csv" role="data"/>
   </dir>
  </contents>
...

Custom file tasks (documented here) have changed substantially in Pyrus. Fortunately, the XML format of tasks used in package.xml remains the same, and Pyrus's expectation of custom task implementation does not conflict or overlap with PEAR's at all, so custom task packages can easily be designed to work with both PEAR and Pyrus.

The biggest difference between how a custom task is implemented in Pyrus has to do with the new plugin system (documented here). Before reading any further, it may be a good idea to familiarize yourself with the way that plugins work in Pyrus by reading the documentation on plugins, then return back to finish reading about custom tasks.

In PEAR, custom tasks are detected simply by scanning the PEAR/Tasks directory, and no differentiation is made between tasks built into PEAR, and external custom tasks.

Pyrus custom tasks are detected through the use a new XML metadata format. The format is simple, and looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<task xmlns="http://pear2.php.net/dtd/customtask-2.0" version="2.0">
 <name>mytask</name>
 <classprefix>vendor_PackageName</classprefix>
 <autoloadpath/>
</task>

The details of what <classprefix> and <autoloadpath> mean are revealed in the full documentation of custom tasks here.

This XML metadata file is identified by Pyrus through the use of the file role customtask, which is used in the custom task's package.xml. Here is an example from the <contents> of a package.xml:

...
  <contents>
   <dir name="data">
    <file name="mytask.xml" role="customtask"/>
    <file name="someotherdata.csv" role="data"/>
   </dir>
  </contents>
...

Custom commands add new functionality to pyrus.phar. An example of a plugin that implements custom commands is the PEAR2_Pyrus_Developer package, which implements the make, package, pickle, and run-phpt commands.

Custom command plugins can implement multiple commands, and are defined by an xml file that is noted in package.xml with the customcommand file role. The XML format is defined and validated by pyrus with the customcommand.xsd XSchema file.

php pyrus.phar install PackageName

php pyrus.phar install PackageName package.xml http://example.com/Foo.tgz

php pyrus.phar package -p --tar

php pyrus.phar install -r /path/to/packagingroot PackageName

php pyrus.phar install --packagingroot=/path/to/packagingroot PackageName

Overview of the Custom Command XML Format

Here is a human-readable overview of a custom command's XML definition file. Optional tags are enclosed in [brackets]. If there is a choice of tags, they are separated by a vertical line | and enclosed in parentheses like (<this>|<example>).

<?xml version="1.0" encoding="UTF-8"?>
<commands version="2.0" xmlns="http://pear2.php.net/dtd/customcommand-2.0">
 <command>
  <name>commandname</name>
  <class>CommandClass\Name</class>
  <function>makePackageXml</function>
[ <webfunction>webCommand</webfunction>]
[ <gtkfunction>gtkCommand</gtkfunction>]
[ <autoloadpath>CommandClass</autoloadpath>]
  <summary>Short description of command purpose</summary>
  <shortcut>CN</shortcut>
  <options>
  [<option>
    <name>optionname</name>
    <shortopt>O</shortopt>
    <type>(<bool/>|<string/>|<int/>|<float/>|<counter/>|
           <callback>optionProcessorCallback</callback>|
           <set><value>value1</value><value>value2</value>...</set>)</type>
   [<default>defaultvalue</default>]
    <doc>Short description of option purpose</doc>
   </option>]
  </options>
  <arguments>
  [<argument>
    <name>argname</name>
    <multiple>0</multiple>
    <optional>1</optional>
    <doc>Short argument description</doc>
   </argument>]
  </arguments>
  <doc>
Long description of command usage for help output
  </doc>
 </command>
</commands>

A command need not require or accept any arguments or options, and can accept multiple arguments and multiple options. In addition, a custom command definition XML file may declare multiple commands.

Commands can also implement a shortcut, which is a shorter alias. The upgrade command, for instance, has a shortcut of up.

By convention, all command names of external projects should be prefixed with the vendor name. For instance, if the vendor is Zend Framework, commands should be prefixed with something like zf- or with zend-. An install command would be zf-install.

In addition, all shortcuts from external vendors should be upper-cased and consist of the first letter of the vendor, and the first two letters of the command. zf-install would have a shortcut of Zin. This helps to avoid name collisions between vendors.

Telling Pyrus how to load your command: <class> and <autoloadpath>

This is the same method used for all plugins, and is documented here.

The three frontend command handlers are discussed in the CLI section, Web section, and the Gtk section.

Defining arguments

Pyrus recognizes both optional and required arguments, as well as the ability to specify repeating arguments. The logic is very similar to function signatures in PHP. Each argument is placed by name into an associative array and passed to the function. Note that invalid input is not passed to custom commands, so a command can assume valid input if it is called.

Here is a sample argument definition and the way that Pyrus will handle different valid inputs for the hypothetical foo command:

 <arguments>
  <argument>
   <name>argname</name>
   <multiple>0</multiple>
   <optional>0</optional>
   <doc>required arg</doc>
  </argument>
  <argument>
   <name>argname2</name>
   <multiple>0</multiple>
   <optional>1</optional>
   <doc>optional arg</doc>
  </argument>
  <argument>
   <name>argname3</name>
   <multiple>1</multiple>
   <optional>1</optional>
   <doc>optional arg, multiple</doc>
  </argument>
 </arguments>

php pyrus.phar foo arg1

php pyrus.phar foo arg1 arg2

php pyrus.phar foo arg1 arg2 arg3

php pyrus.phar foo arg1 arg2 arg3 arg4

Defining options

Options must define a short and a long option, a type for the option, and a short description of the option for help text.

Options fall into two categories, those that accept arguments, and those that don't. Options that don't accept arguments are of type <bool/> and <counter/>.

The types recognized are:

• <bool/>
• <counter/>
• <string/>
• <int/>
• <float/>
• <callback></callback>
• <set></set>

  <options>
   <option>
    <name>nocompatible</name>
    <shortopt>n</shortopt>
    <type><bool/></type>
    <doc>Do not generate package_compatible.xml</doc>
   </option>
  </options>

php pyrus.phar foo

php pyrus.phar foo -n

php pyrus.phar foo --nocompatible

  <options>
   <option>
    <name>verbose</name>
    <shortopt>v</shortopt>
    <type><counter/></type>
    <doc>How verbose to be with output</doc>
   </option>
  </options>

php pyrus.phar foo

php pyrus.phar foo -v

php pyrus.phar foo --verbose -vv --verbose

  <options>
   <option>
    <name>name</name>
    <shortopt>n</shortopt>
    <type><string/></type>
    <doc>Name of foo</doc>
   </option>
  </options>

php pyrus.phar foo

php pyrus.phar foo -n myname

php pyrus.phar foo --name=myname

  <options>
   <option>
    <name>namecount</name>
    <shortopt>n</shortopt>
    <type><int/></type>
    <doc>Number of foo names</doc>
   </option>
  </options>

php pyrus.phar foo

php pyrus.phar foo -n 3

php pyrus.phar foo --namecount=3

  <options>
   <option>
    <name>foopercent</name>
    <shortopt>f</shortopt>
    <type><float/></type>
    <doc>Foo percent in decimal notation</doc>
   </option>
  </options>

php pyrus.phar foo

php pyrus.phar foo -f .2

php pyrus.phar foo --foopercent=0.3

  <options>
   <option>
    <name>foocallback</name>
    <shortopt>f</shortopt>
    <type><callback>processfoo</callback></type>
    <doc>Foo date</doc>
   </option>
  </options>

php pyrus.phar foo

php pyrus.phar foo -f 2009-12-31

php pyrus.phar foo --foocallback=2009-12-31

  <options>
   <option>
    <name>numbah</name>
    <shortopt>n</shortopt>
    <type>
     <set>
      <value>one</value>
      <value>two</value>
      <value>three</value>
      <value>four</value>
     </set>
    </type>
    <doc>Numbers less than five</doc>
   </option>
  </options>

php pyrus.phar foo

php pyrus.phar foo -n four

php pyrus.phar foo --numbah=one

Declaring CLI command method

A class must implement a command-line handler, which should have this method signature:

The first argument is the CLI frontend, and can be used for asking the user a question with the ask() method, or passing control to a built-in command. $args is an associative array of arguments. Only required arguments are guaranteed to be present, all optional arguments must be verified as present before using. $options is an associative array of options. All options will be present, those not present will be initialized to NULL.

Options should be accessed using their long names, and arguments using their names (see examples in the documentation sections for arguments and options above).

The ask() method accepts 3 arguments:

1. string $question the question to ask the user. It should end in a question mark

2. (optional) array $choices an array of possible answers

3. (optional) string $default the default answer

Declaring Web command method

Although a Web frontend has not yet been written for Pyrus, the XML command format supports the eventual addition of a Web frontend. A separate method should be used for the Web handling, and is named via the <webfunction> tag.

Declaring GTK command method

Although a GTK frontend has not yet been written for Pyrus, the XML command format supports the eventual addition of a GTK frontend. A separate method should be used for the GTK handling, and is named via the <gtkfunction> tag.

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:

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.

If you are not familiar with how file tasks work, read the introduction to file tasks first.

Custom file tasks can implement a single task, and are defined by an xml file that is noted in package.xml with the customtask file role. The XML format is defined and validated by pyrus with the customtask-2.0.xsd XSchema file.

Here is a human-readable custom file task xml file definition. Optional elements are enclosed in [brackets].

<?xml version="1.0" encoding="UTF-8"?>
<task version="2.0" xmlns="http://pear2.php.net/dtd/customtask-2.0">
 <name>taskname</name>
 <class>MyPlugin_Taskname</class>
[<autoloadpath>relative/path/to/MyPlugin</autoloadpath>]
</task>

Telling Pyrus how to load your task: <class> and <autoloadpath>

This is the same method used for all plugins, and is documented here.

Defining the task: the task class

A custom file task must extend the \PEAR2\Pyrus\Task\Common class, and must implement a few methods:

• validateXml()
• startSession()

Optionally, __construct() may be used to do special pre-processing, storing of information or other setup tasks.

A task must also define two class constants, TYPE and PHASE. TYPE should be one of 'simple' or 'script'. 'script' tasks are post-install scripts, and are executed by the run-scripts command. 'simple' tasks are executed while installation is in progress.

PHASE should be one of:

• \PEAR2\Pyrus\Task\Common::PACKAGE
• \PEAR2\Pyrus\Task\Common::INSTALL
• \PEAR2\Pyrus\Task\Common::PACKAGEANDINSTALL
• \PEAR2\Pyrus\Task\Common::POSTINSTALL

\PEAR2\Pyrus\Task\Common::POSTINSTALL is only used by post-install scripts, the other 3 are used to determine at what time the task should be called. If your custom task only works at installation-time, use \PEAR2\Pyrus\Task\Common::INSTALL. If the task can perform only at package time (this is exceedingly rare), use \PEAR2\Pyrus\Task\Common::PACKAGE. Most tasks should use \PEAR2\Pyrus\Task\Common::PACKAGEANDINSTALL. If your task can perform its task at packaging time, then you should override the isPreProcessed() method and return true. Some tasks, such as the replace task, perform some of their actions at package time, and the rest at install time. The isPreProcessed() method should only return true if the XML of the specific task could be processed at package time.

The startSession() method is used to actually execute the task, and is passed a read/write file resource that is set to the beginning of the file being installed. The full path of the file's final installation location is also passed in, and can be used for throwing exceptions. All errors should be handled by throwing a PEAR2\Pyrus\Task\Exception or one of its descendants.

The validateXml() method should validate the XML as represented in an array format. The array uses associative arrays for tags, the attribs index for attributes, and for a tag with both attributes and content, the _content index contains the content. If present, the tasks: namespace is removed from the tags prior to passing to validateXml(). On encountering validation errors, the method should throw one of the four exceptions in the example below.

Example Custom Task

Pyrus is particularly well-suited to maintaining a PEAR2 package, and can be used to easily create a package.xml with the make command. Once the requisite files are in place for this command, creating a release is as simple as

php -dphar.readonly=0 pyrus.phar make -pphar,tar,tgz,zip

In addition, Pyrus provides a simple facility for creating a new PEAR2 package, the generate-pear2 command. With this command, a skeleton directory and file setup is created that can be immediately used to get started with a new package.

Using Pyrus to manage your existing PEAR package is simple, although not as easy as managing a PEAR2 package or PECL extension. Generally speaking, the command you will take advantage of the most is the package command, which can be used to create the release needed.

As a PECL developer, managing your extensions could not be simpler with Pyrus. The new pickle command makes creating a package.xml as simple as creating a few text files and then running the command. In addition, the PECL packages created with the pickle command are installable by the most widely installed version of PEAR as well as by the newest versions of PEAR and by Pyrus.

Pyrus's pickle command fully eliminates the need to ever even look at package.xml, greatly simplifying the lives of PECL extension developers.

In addition, the run-phpt command can be used to run all the extension's phpt test files.

Creating a new PECL package with Pyrus

If you are creating a brand new extension, you should use the generate-ext command to create the basic structure of your extension.

After creating your extension, edit the newly-created CREDITS file to have the correct information:

 
;; extensionname
My Name (myhandle) <myemail@php.net> (lead)
 

Add any additional maintainers using the same format.

Next, edit the README file that describes your package. The first line should be a brief summary of what the extension does, and the rest of the file should be a detailed description of information the user should know about the origin of the extension, and perhaps a simple example of its usage.

Finally, edit the file named RELEASE-0.1.0. Put any release notes in here. Generally initial release is enough information for the first release.

Last, you can optionally create a file named API-0.1.0. Pyrus and the PEAR Installer differentiate between API version and release version, to allow clearly defining an API change or backwards compatibility break. Put information on any API changes into API-0.1.0.

After creating these files, simply run:

php pyrus.phar pickle extensionname

where extensionname is the name of your extension. If you have not yet installed the developer tools, Pyrus will ask if you would like to download and install them. Choose yes and then re-run the command.

Pyrus will create a package.xml and a release called extensionname-0.1.0.tgz, or extensionname-0.1.0.tar if the zlib extension is not enabled. This release can be uploaded to pecl.php.net for immediate distribution.

Note that the directory structure described in pickle command documentation is required for pickle to detect documentation, tests, or data files.

Readying an existing PECL package for Pyrus

To prepare an existing PECL package for Pyrus, you should create all of the information files described in the section Creating a new PECL Package with Pyrus, but instead of creating RELEASE-0.1.0 and API-0.1.0, you would create a file named RELEASE-X.Y.Z where X.Y.Z is the version of the extension. So if your extension's version is 1.2.3 you would create a file named RELEASE-1.2.3. For each of the files above, rather than putting new content, you can copy/paste the existing description, summary and release notes from your existing package.xml. Note that any entities such as < should be converted to their values <, as Pyrus escapes automatically from the text files.

Note that the directory structure described in pickle command documentation is required for pickle to detect documentation, tests, or data files.

Future releases

When the time rolls around for the next release, readying for this is also simple. If you are about to release version 0.2.0, create a file named RELEASE-0.2.0 and put the release notes into the file. Pyrus will automatically detect that 0.2.0 is newer than 0.1.0 and create a new release with those notes.

If you are not familiar with the package.xml format, you will need to read The description of the file.

This guide is divided into several segments.

• If you want to access basic properties such as the name of the package, the channel, summary, description, license, version, stability, date, time, or notes, read the section on Accessing basic properties

• To learn about how to manage maintainers of the package, read the section on Accessing package maintainers.

• To learn about how to manage and iterate over dependencies, read the section on Accessing dependencies.

• To understand how to iterate over and add files to both the contents and release sections of package.xml, read the section on Accessing files

• To learn about managing custom tasks, roles, and compatible packages, read the section on usesrole, usestask and compatible.

• To learn about accessing PECL-specific properties such as configureoption, srcpackage, srcuri and providesextension, read the section on Accessing PECL properties

The package.xml file is represented using a PEAR2\Pyrus\PackageFile\v2 object, but most of the time you will access it using the most packagefile version-agnostic PEAR2\Pyrus\Package class, which supports the same API seamlessly for accessing any kind of package as well as a few higher level options such as directly accessing the source of a file in a package. This documentation assumes you are working with a PEAR2\Pyrus\Package object named $package.

To instantiate a PEAR2\Pyrus\Package, simply pass in the path to a local package, a URI of a remote package, or an abstract remote package name to the constructor.

Basic properties can be accessed as if they were object properties:

By the same token, changing these properties is as simple as setting an object property:

Maintainers are accessed through the maintainer property. An of maintainers organized by maintainer role can be obtained via the allmaintainers property, but it is also possible to iterate over the maintainer property to iterate over all maintainers.

The maintainer property acts as an array organized by developer handle. To learn more about maintainers in package.xml, see the concepts section on maintainers in the user guide.

An individual maintainer's properties are set via a fluent method call. The order of method call is not important, but a call to the role() method is required in order to properly save the data.

The maintainers can be iterated over as well, and even modified:

The allmaintainers property returns an associative array of arrays of maintainer objects indexed by maintainer role.

Before it is possible to understand how Pyrus provides access to dependencies, it is necessary to understand their format in package.xml, which is documented here.

Pyrus provides access to dependencies through the dependencies property. In addition to supporting access to and creation of individual dependencies, it is possible to iterate over all dependencies, or over just required dependencies, or just a particular dependency type.

Each of the dependency types (package, subpackage, pearinstaller, extension, php, arch, and os) is accessed slightly differently based on how they are used in package.xml.

Perhaps the best introduction is 3 examples highlighting the different methods of accessing dependency properties. First, an example highlighting the methods for reading existing dependency properties:

Iteration is similar to the access, in that each dependency object is the same object as that when accessed using the full access syntax:

Finally, setting dependencies can be accomplished in several ways.