Working with installed packages and channels: The Registry API

Introduction

Pyrus provides a very simple API for accessing its registry. Pyrus stores meta-information on installed packages in redundant registries. There are three kinds of registries that Pyrus recognizes, Sqlite3, Xml and the legacy Pear1 registry. A pyrus-based installation can have up to all three kinds of registries redundantly storing the installed packages and the known channels. By default the Sqlite3 registry is the primary registry used for querying information, with the Xml registry as a backup.

When Pyrus is used to manage an installation, it checks to see which registries are already present, if any, and will use the existing registries. This fact can be used to provide more flexible installation options. For instance, Pyrus can be used to manage an existing legacy PEAR installation without any special configuration, it will simply detect that the legacy registry is present and use it. If a package is extracted into a bundled location, Pyrus will detect its extracted package.xml as belonging to the Xml registry, and will use only that registry for installation purposes, which allows upgrading the extracted package and avoids placing any absolute paths into the installation.

Pyrus provides full atomic installation transactions for all of its registry types, including the legacy Pear1 registry, unlike the PEAR installer. In addition, each registry provides a single method which can be used to remove it from disk, and there is also a single method which can be used for converting from one registry type to another. Another method is available for repairing a corrupted registry from one of its redundant registries.

Pyrus provides a separate logical registry for storing channels from the registry that stores packages. Each registry handles this slightly differently. The Sqlite3 registry, for instance, stores all information in a single database. The Xml registry stores information in separate files, like the legacy Pear1 registry.

Basic Registry principles

All registry classes implement the PEAR2\Pyrus\IChannel interface, and all channelregistry classes implement the PEAR2\Pyrus\ChannelRegistry interface. The PEAR2\Pyrus\Registry class acts as an aggregator of underlying registries, and implements the ability to cascade to parent registries, as does the PEAR2\Pyrus\ChannelRegistry class.

The simplest way to retrieve a registry object is to use the one strongly tied to the PEAR2\Pyrus\Config object:


<?php
$reg = PEAR2\Pyrus\Config::current()->registry;
$creg = PEAR2\Pyrus\Config::current()->channelregistry;
?>

Accessing a specific installed package retrieves an object that is API-identical to a PackageFile object. The registry is implemented logically as an associative array. By requesting a package's logical name, which is channel/packagename, we get an object that can be manipulated just as if it were the package prior to installation


<?php
$package = PEAR2\Pyrus\Config::current()->registry->package['pear2.php.net/PEAR2_Pyrus_Developer'];
$remotepackage = new PEAR2\Pyrus\Package('pear2.php.net/PEAR2_Pyrus_Developer');
// both packages can be queried with the same API
?>

The same principle applies to channels:


<?php
$channel = PEAR2\Pyrus\Config::current()->channelregistry['pear2.php.net'];
$localchannel = new PEAR2\Pyrus\ChannelFile('channel.xml');
// both channels can be queried with the same API
?>

Iteration also works with both just as it would for an array:


<?php
foreach (PEAR2\Pyrus\Config::current()->registry->package as $name => $package) {
    // $name is channel/package
    // $package is a packagefile object
}
foreach (PEAR2\Pyrus\Config::current()->channelregistry as $name => $channel) {
    // $name is the channel name
    // $channel is a channelfile object
}
?>

Installation-related API tasks

There are 4 installation-related methods, as well as 3 transaction methods. These methods are:

install() and replace()
uninstall()
exists()
begin(), commit() and rollback().

The install() method registers a package as installed, and sets its date/time to the current time so that the installation time can be tracked. The replace() method registers a package as installed, but does not modify its date/time. This is useful for repairing a corrupted entry, or simply storing a package as it is. Both methods accept a PEAR2\Pyrus\IPackageFile object. A packagefile object can be retrieved from a PEAR2\Pyrus\Package object by calling its getPackageFileObject() method. A PEAR2\Pyrus\Registry\Exception is thrown on any errors.

The uninstall() method accepts two parameters, the name of the package, and the package's channel. A PEAR2\Pyrus\Registry\Exception is thrown on any errors.

The exists() method also accepts two parameters, and returns TRUE or FALSE depending on whether the package exists. If severe errors occur such as registry corruption, a PEAR2\Pyrus\Registry\Exception object is thrown.

Note that array access can also be used to handle installation-related tasks:


<?php
$reg = PEAR2\Pyrus\Config::current()->registry;

$package = new PEAR2\Pyrus\Package('/path/to/package.xml');

// equivalent to $reg->install($package)
$reg->package[] = $package;

// equivalent to $reg->uninstall('Foo', 'pear2.php.net')
unset($reg->package['pear2.php.net/Foo']);

// equivalent to $reg->exists('Foo', 'pear2.php.net');
isset($reg->package['pear2.php.net/Foo']);
?>

When performing any installation or uninstallation task, it is recommended to use the registry's built-in transaction support. The Sqlite3 registry uses the database's native transaction support. Both the Xml and Pear1 registries use Pyrus's PEAR2\Pyrus\AtomicFileTransaction for its transaction support. Thus, it is always best to do a transaction by first enabling the registry transaction, and then the atomic file transaction within this registry transaction:


<?php
$reg = PEAR2\Pyrus\Config::current()->registry;
$package = new PEAR2\Pyrus\Package('Whatever');
try {
    $reg->begin();
    PEAR2\Pyrus\AtomicFileTransaction::begin();
    $reg->install($package);
    PEAR2\Pyrus\AtomicFileTransaction::commit();
    $reg->commit();
} catch (Exception $e) {
    $reg->rollback();
    PEAR2\Pyrus\AtomicFileTransaction::rollback();
    throw $e;
}
?>

If using the Installer API, the transactions and installation to registry is all automatic, this code is only needed for customizing installation.

Specialized querying of the registry

Other methods for querying the registry include:

info()
listPackages()
getDependentPackages()
detectFileConflicts()
detectRegistries()
removeRegistry()

info()

The info() method provides a way of peeking at a single attribute of a package. When used with the Sqlite3 registry, it is extremely efficient both in terms of memory use and speed. Both the Xml and Pear1 registries are far slower because they must load the complete packagefile into memory for every query. For these registries, it is better to simply retrieve a packagefile and query it using the PackageFile API.

Parameters to info() are the package name, package channel, and the field name to retrieve.

All of the Basic package.xml properties can be directly accessed using info(). In addition, two special properties, installedfiles and dirtree are available.

installedfiles returns a list of files and their properties as they have been installed. Here is a sample return value:


<?php
array(
      '/full/path/todocs/PEAR2_SimpleChannelServer/pear2.php.net/examples/update_channel.php' =>
      array(
        'role' => 'doc',
        'name' => 'examples/update_channel.php',
        'installed_as' => '/full/path/to/docs/PEAR2_SimpleChannelServer/pear2.php.net/examples/update_channel.php',
        'relativepath' => 'PEAR2_SimpleChannelServer/pear2.php.net/examples/update_channel.php',
        'configpath' => '/full/path/to/docs',
           ),
      // ... and so on
     );
?>

dirtree returns a list of every directory that would have been created if installing the package in a new installation. This can be used to prune empty directories after uninstalling. Here is a sample return value:


<?php
array (
      '/full/path/to/php/PEAR2/SimpleChannelServer/REST',
      '/full/path/to/php/PEAR2/SimpleChannelServer/Categories',
      '/full/path/to/php/PEAR2/SimpleChannelServer',
      '/full/path/to/php/PEAR2',
      '/full/path/to/php',
      '/full/path/to/docs/PEAR2_SimpleChannelServer/pear2.php.net/examples',
      '/full/path/to/docs/PEAR2_SimpleChannelServer/pear2.php.net',
      '/full/path/to/docs/PEAR2_SimpleChannelServer',
      '/full/path/to/docs',
      '/full/path/to/bin',
    );
?>

listPackages()

This method accepts a channel name as an argument, and returns an array of the names of installed packages from that channel.

getDependentPackages()

getDependentPackages() requires a single argument, a PEAR2\Pyrus\IPackageFile object. This method returns an array of PEAR2\Pyrus\Package objects representing installed packages that depend upon the package passed in. If the optional second boolean parameter is set to true (which it is by default), performance is improved when querying an Sqlite3 database by returning packages containing only the name of the package and its dependencies.

detectFileConflicts()

This method is used to implement file conflict detection to prevent overwriting installed files with those from another package. It accepts a single argument, a PEAR2\Pyrus\IPackageFile object. The Pear1 registry is the most efficient at this operation (at the expense of drastically decreased efficiency at installation or uninstallation), the Sqlite3 is the next most efficient, and the Xml registry is the least efficient, and in fact is so inefficient, this method should only be called on an Xml registry that is for a very small installation.

detectRegistries()

This static method accepts a string containing the path to check for registries, and returns an array containing the names of registries found. The possible return values include Sqlite3, Xml and Pear1. Note that only a call to PEAR2\Pyrus\Registry::detectRegistries() will return a list of all registries found. A call to PEAR2\Pyrus\Registry\Sqlite3::detectRegistries() will only return either array() or array('Sqlite3') depending on whether the registry exists.

removeRegistry()

This static method accepts a string containing the path to remove a registry from. A call to PEAR2\Pyrus\Registry::removeRegistry() will completely remove all traces of a PEAR installation. A call to an individual registry's removeRegistry, such as a call to PEAR2\Pyrus\Registry\Pear1::removeRegistry() will only remove that registry from the installation path.