Leveraging Pyrus's installation API

Introduction

Pyrus provides a very simple API for performing installation tasks. This API begins with the ability to pass any packagename that can be specified on the command-line to a PEAR2\Pyrus\Package object:

<?php
// examples of the range of valid package names
$package = new \PEAR2\Pyrus\Package('package.xml');
$package = new \PEAR2\Pyrus\Package('/full/path/to/package.xml');
$package = new \PEAR2\Pyrus\Package('Package-1.2.3.tgz');
$package = new \PEAR2\Pyrus\Package('/full/path/to/Package-1.2.3.zip');
$package = new \PEAR2\Pyrus\Package('RemotePackage');
$package = new \PEAR2\Pyrus\Package('RemotePackage-alpha');
$package = new \PEAR2\Pyrus\Package('RemotePackage-1.2.3');
$package = new \PEAR2\Pyrus\Package('channelname/RemotePackage');
$package = new \PEAR2\Pyrus\Package('http://example.com/RemotePackage-1.2.3.phar');
?>

If there is a problem with the package name as passed to the constructor, an exception is thrown. This can be any of a wide variety of exceptions ranging from a PEAR2\Pyrus\PackageFile\Exception for invalid package.xml, a PEAR2\Pyrus\Package\Exception for higher-level errors (file does not exist, invalid abstract package name), a PEAR2\Pyrus\Package\InstalledException if an abstract remote package was requested and a newer version is installed, and a PEAR2\Pyrus\Channel\Exception if any problems with retrieving remote REST information occur. Also possible are PEAR2\Pyrus\Package\Phar\Exception for errors relating to local tar, tgz, zip or phar archives.

Installing and Uninstalling packages

Once you have a valid package object, installation is very simple. Pyrus conducts all installation activities within a transaction, meaning that all changes are applied nearly simultaneously, and any failure mid-transaction does not leave an invalid installation lying around.

<?php
// import the class names into the current scope
// this step is optional, you can also use the full class names
// like PEAR2\Pyrus\Installer::begin()
use PEAR2\Pyrus\Installer as Installer,
    
PEAR2\Pyrus\Package as Package;

try {
    
$p1 = new Package('package.xml');
    
$p2 = new Package('Package.tgz');
    
$p3 = new Package('pear2/RemotePackage');

    
// here is the meat of the installation transaction
    
Installer::begin();

    
Installer::prepare($p1);
    
Installer::prepare($p2);
    
Installer::prepare($p3);

    
Installer::commit();
} catch (\
Exception $e) {
    echo 
"Install failed\n";
}
?>

Uninstalling a package is even simpler:

<?php
// import the class names into the current scope
// this step is optional, you can also use the full class names
// like PEAR2\Pyrus\Uninstaller::begin()
use PEAR2\Pyrus\Uninstaller as Uninstaller;

try {
    
Uninstaller::begin();

    
Uninstaller::prepare('pear2.php.net/Package1');
    
Uninstaller::prepare('pear.php.net/Package');
    
Uninstaller::prepare('__uri/Package');

    
Uninstaller::commit();
} catch (\
Exception $e) {
    echo 
"Uninstall failed\n";
}
?>