Chapter 3. Leveraging Full Application Support with the PEAR Installer

In the last chapter we learned a great deal about the internals of package.xml. In this chapter, we are stepping up the intensity a notch, and exploring the exciting new features that enable us to easily distribute PHP applications and manage their installation and post-installation customization.

If you've ever wanted to make it easy to customize an installation of your PHP application across multiple platforms, PHP versions, and user setups, then this is the chapter for you.

package.xml Version 2.0: Your Sexy New Friend

The title of this section says it all. package.xml 2.0 is a major improvement over package.xml 1.0. The implementations of several important new features in the PEAR installer such as custom file roles/tasks, enterprise-level dependencies, and channels are reflected by new tags in package.xml 2.0. In addition, the structure is designed to be easily validated using other tools.

package.xml Version 2.0: Your Sexy New Friend

The title of this section says it all. package.xml 2.0 is a major improvement over package.xml 1.0. The implementations of several important new features in the PEAR installer such as custom file roles/tasks, enterprise-level dependencies, and channels are reflected by new tags in package.xml 2.0. In addition, the structure is designed to be easily validated using other tools.

PEAR Channels: A Revolution in PHP Installation

The smallest addition to package.xml 2.0 is the<channel> tag. Don't be fooled though, channels are the most significant new feature implemented in the PEAR installer. Channels are to PEAR what dependencies are to team development. By opening up the ease of the PEAR installer to sites other than pear.php.net, a number of free choices have been made available to PHP users. For the first time, it is possible to design an application that depends upon packages from pear.php.net, pear.example.com, and any number of sites, and all of them can be automatically downloaded, installed, and easily upgraded on the end-user's computer with a single command. Although Chapter 5 discusses the minutiae of channels and the channel.xml channel definition file, it is good to have a basic understanding of how channels work when designing your packages.

There are two problems that channels effectively solve:

• Distributing application development across multiple...

Application Support

So far, we have learned that the PEAR installer was designed to support libraries first, and then application support was added in PEAR version 1.4.0. Let's take a closer look at what that specifically means by examining four exciting new features: custom file roles, custom file tasks, post-installation scripts, and the ability to bundle several packages into a single archive.

In this section, we will explore the details of these features by creating a new custom file role chiaramdb2schema, a custom file task chiara-managedb, a post-install script to populate needed data, and a sample application. We'll then distribute the role and task in a single archive.

Note

Before we begin, you need to examine one vital point:

What problem are you solving? Should you use a custom file role, custom file task, post-install script, or something else?

Custom file roles are designed to group related file classes together. If, for instance, you wish to install all web-based image files in...

Bundling Several Packages into a Single Archive

Often, it is a desired feature to bundle a package and its dependencies into a single installable archive. There are two ways of doing this. The simplest way is to use a package.xml file similar to this one:

<?xml version="1.0" encoding="UTF-8"?>
<package version="2.0" xmlns="http://pear.php.net/dtd/package-2.0"
xmlns:tasks="http://pear.php.net/dtd/tasks-1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0
http://pear.php.net/dtd/tasks-1.0.xsd
http://pear.php.net/dtd/package-2.0
http://pear.php.net/dtd/package-2.0.xsd">
<name>PEAR_all</name>
<channel>pear.php.net</channel>
<summary>PEAR Base System</summary>
<description>
The PEAR package and its dependencies
</description>
<lead>
<name>Greg Beaver</name>
<user>cellog</user>
<email>[e-mail]</email>
<active>yes</active...

Backwards Compatibility: Using package.xml 1.0 and 2.0

One of the most important new features of PEAR version 1.4.0 and newer that comes with the advent of package.xml 2.0 is the ability to make a package installable by older PEAR versions. The package command, invoked with the following historically takes a package.xml and spits out a GZIP-compressed tar (.tgz) file.

$ pear package

If the package name is Foo, and the version is 1.0.0, the .tgz file will be named Foo-1.0.0.tgz. New in version 1.4.0, if there is a second package.xml named package2.xml, the package command will attempt to include it in the archive. When PEAR downloads a package for installation, it first looks for a package2.xml file, which is always in version 2.0 format, and then falls back to package.xml. In this way, older versions of PEAR are supported, because they always look for package.xml first.

For this to work, PEAR does a very strict comparison of the contents of the package.xml files. package.xml version 1.0...

Why Support Old and Crusty package.xml 1.0?

This is a common debate in the PHP world. Why support backwards compatibility? These are old, buggy versions of PEAR, right? Yes, they are old and buggy versions and anyone using them is asking for trouble, but people may not find a compelling reason to upgrade their PEAR installer just so that they can use your package because what they have already "works for them". It is (or should be) your goal as a package distributor to make the process of upgrading as painless as possible. You should only drop package.xml version 1.0 support if you are in fact using new features of PEAR itself in the PHP code, or your package is a new one without an installed userbase.

PEAR development has progressed at a rapid pace, but the adoption of the new installer will not happen overnight. Large software projects like Linux distributions need time to evaluate the new features and make sure that everything works properly prior to adopting a new version. As PEAR developers...

Case Study: The PEAR Package

PEAR is a perfect example of a package that will always need to support package.xml 1.0. We will always have users who are upgrading from an earlier version to the latest one and PEAR 1.3.6 and older simply doesn't know anything about package.xml 2.0. If we don't make it possible to upgrade PEAR, there isn't much point in making the code available.

However, at the same time, the new dependency features and tasks of package.xml 2.0 are very important for the PEAR package, and so both package.xml 1.0 and package.xml 2.0 are needed. For instance, the pear command itself is a shell script on UNIX (with UNIX \n line endings) and a batch file on Windows (with Windows \r\n line endings). Before package.xml 2.0, it was necessary to add these scripts as binary files to CVS, so that the line endings are not replaced with the packager's system line endings. Now, through the use of the<tasks:windowseol/> and<tasks:unixeol/> tasks, this is no longer necessary...

PEAR_PackageFileManager

Although the commands convert and pickle can be used in limited situations to manage both a package.xml version 1.0 and version 2.0, these commands can also be dangerous. A far safer way to maintain two versions of package.xml from a single location is through the use of the PEAR package PEAR_PackageFileManager. This package provides a simple interface from which to import an existing package.xml file and update with current information, or to create a new package.xml file from scratch. In addition, it is very simple to take an existing package.xml 2.0, no matter how complicated it is, and easily create an equivalent package.xml 1.0 with absolute control over the contents of each package.xml.

Obtaining PEAR_PackageFileManager

PEAR_PackageFileManager can be easily obtained by using the PEAR installer. As of the writing of this book, version 1.6.0b1 is available. To install it, you must set the preferred_state configuration variable to beta via:

$ pear config-set preferred_state...

Creating a Package for Installation with the PEAR Installer

The final step in the process is creating a package. Once you have a package.xml file that has been generated, you can use it to create a file containing the contents of the package. To do this, you should use the package command:

$ pear package

This command should be executed from the directory containing the package.xml file. This will create a .tgz file like Package-version.tgz where Package is the package name, and version is the release version. If your package is named Foo and is version 1.2.3 the package command will create a file named Foo-1.2.3.tgz. This file can be installed with:

$ pear install Foo-1.2.3.tgz

Or can also be uploaded to a channel server for public release (discussed in Chapter 5).

The package command can also be used to create an uncompressed .tar file with the --uncompress or -Z option:

$ pear package Z

In some cases, you may have renamed a package file. In this case, it is necessary to explicitly specify...

Summary

At this stage, we've explored the inner workings of the PEAR installer and of package.xml to the highest level—it is safe to say that you are now a package.xml expert.