Section 10.2. PEAR Concepts

10.2. PEAR Concepts

This section explains some PEAR concepts, namely packages, releases, and the versioning scheme.

10.2.1. Packages

When you want to install something from PEAR, you download and install a particular release of a package. (You learn more about releases later on.) Each package has some information associated with it:

• Package name (for example, HTML_QuickForm)

• Summary, description, and home page URL

• One or more maintainers

• License information

• Any number of releases

PEAR packages are not unlike other package formats, such as Linux's RPM, Debian packages, or the System V UNIX PKG format. One of the major differences with most of these is that PEAR packages are designed to be platform-independent, and not just within one family of operating systems, such as System V or Linux. Most PEAR packages are platform-independent; you can install them on any platform PHP supports, including all modern UNIX-like platforms, Microsoft Windows, and Apple's MacOS X.

10.2.2. Releases

As with PHP itself, the code that you actually install is packaged in a tar.gz or zip file along with installation instructions. PEAR packages are also released through tar.gz (or tgz) files, and contain install instructions that are read by the PEAR Installer.

In addition to this package-specific information, each release contains

• A version number

• A list of files and installation instructions for each

• A release state (stable, beta, alpha, devel, or snapshot)

When you install a PEAR package, you receive the latest stable release by default, for example

 $ pear install XML_Parser downloading XML_Parser-1.1.0.tgz ... Starting to download XML_Parser-1.1.0.tgz (7,273 bytes) .....done: 7,273 bytes install ok: XML_Parser 1.1.0 

By running the command pear install XML_Parser, you obtain the latest stable release of the XML_Parser package, with the version number 1.1. You learn about these details later in this chapter.

There are several reasons why PEAR did not use an existing format such as RPM as its package format. The most obvious reason is that PHP is very portable, so the package format would have to be supported on every platform PHP runs on. That would have meant either porting and maintaining ports of RPM (for example) to Windows and Darwin, or implementing RPM in PHP. Both options were considered too much work, so the choice was to implement the installation tools in PHP to be able to use the tools on various platforms easily.

PEAR addresses the issues of integrating with RPM and other packaging systems by allowing PEAR packages to be wrapped inside operating system packages.

10.2.3. Version Numbers

PEAR defines some standards for packages, a coding standard that you will learn about in Chapter 12, "Building PEAR Components," and a versioning standard. The versioning standard tells you how to interpret a version number and, more importantly, how to compare two version numbers.

PEAR's version number standard is pretty much what you are used to from open-source packages, but it has been put in writing and implemented through PHP's version_compare() function.

10.2.3.1 Version Number Format

A version number can be everything from a simple "1" to something awful, like "8.1.1.2.9b2." However, PEAR cares about at most three numbers, plus an extra part at the end reserved for special cases, like "b1," "RC2," and so on. The syntax is like this:

 Major [ . minor [ . patch ]] [ dev | a | b | RC | pl [ N ]] 

All these forms of version numbers are valid (see Table 10.1).

Table 10.1. Example Version Numbers

Version String	Major Version	Minor Version	Patch Level	Release State'
1	1
1b1	1			b1
1.0	1	0
1.0a1	1	0		a1
1.2.1	1	2	1
1.2.1dev	1	2	1	dev
2.0.0-dev	2	0	0	dev
1.2.1RC1	1	2	1	RC1

Most PEAR packages use the two- or three-number variation, sometimes adding a "release state" part, such as "b1," during release cycles. Here's an overview of the meaning of the release state component (see Table 10.2).

Table 10.2. Example Release States

Extra	Meaning
Dev	In development; used for experimental releases.
A	Alpha release; anything may still change, may have many bugs, and the API not final.
B	Beta release; API is more or less stable, but may have some bugs.
RC	Release candidate; if testing reveals no problems, an RC is re-released as the final release.
Pl	Patch level; (not very often) used when doing an "oops" release with last-minute fixes.

10.2.3.2 Comparing Version Numbers

PEAR sometimes compares two version numbers to determine which signifies a "newer" release. For example, when you run the pear list-upgrades command, the version numbers of your installed packages are compared to the newest version numbers in the package repository on pear.php.net.

This comparison works by comparing the major version first. If the major version of A is bigger than the major version of B, A is newer than B, and vice versa. If the major version is the same, the minor version is compared the same way. But as specified in the previous syntax, the minor version is optional so if only B has a minor version, B is considered newer than A. If the minor versions of A and B are the same, the patch level is compared in the same way. If the patch level of A and B are equal, too, the release state part determines the result.

The comparison of the "extra" part is a little bit more involved because if A is missing a release state, that does not automatically make B newer. Release states starting with "dev," "a," "b," and "RC" are considered older than "no extra part," while "pl" (patch level) is considered newer.

Some example comparisons include those shown in Table 10.3.

Table 10.3. Example Version Comparisons

Version A	Version B	Newest?	Reason?
1.0	1.1	B	B has a greater minor version.
2.0	1.1	A	A has a greater major version.
2.0.1	2.0	A	A has a patch level; B does not.
2.0b1	2.0	B	A "beta" release state is "older" than no release state.
2.0RC1	2.0b1	A	"Release candidate" is newer than "beta" for the same major.minor version.
1.0	1.0.0	B	This one is subtle, adding a level makes a version newer.

Major Versus Minor Version Versus Patch Level

So, what does it mean when the newest release of a package has a different major version than the one you have installed? Well, this is the theory: It should always be safe to upgrade to a newer patch level within the same major.minor version. If you use 1.0.1, upgrading to 1.0.2 is safe. There will only be bug fixes and very minor feature changes between patch levels. The API is completely backward compatible.

It may or may not be safe to upgrade to a newer minor version within the same major version. A minor version increase is used to signify from small to big feature additions, and may introduce API changes. You should always read the release notes and change log for the releases between the one you have and the one you are upgrading to, to become aware of potential problems.

If the major version of a package changes, it no longer attempts to be backward compatible. The package may have been re-implemented around a different paradigm or simply removed obsolete features.

Major Version Changes

When the major version of a package changes, the package name is changed and, as a result, the class names inside the package changes, too. This is to support having multiple major versions of the same package installed in the same file layout.

For example, when version 2.0 of the package Money_Fast is released, the package name for that major version changes to either Money_Fast2, Money_Fastv2, or Money_Fast_v2.