Introduction

PEAR is the PHP Extension and Application Repository, a collection of open source classes that work together. Developers can use PEAR classes to generate HTML, make SOAP requests, send MIME mail, and a variety of other common tasks. A pear is also a tasty fruit.

Only a few core PEAR packages are bundled with the main PHP release. However, part of PEAR is a program called, appropriately enough, pear , that makes it easy for you to download and install additional PEAR packages. This program is also known as the PEAR package manager. Recipe 21.2 shows how to use the PEAR package manager.

PEAR packages divide into two major parts. One is the PHP Foundation Classes — object-oriented code written in PHP that's high quality and usable in production environments on any platform and web server. The other is PECL, or PHP Extension Code Library. PECL, pronounced pickle, is a series of extensions to PHP written in C. These extensions are just like ones distributed with the main PHP release, but they're of more specialized interest — such as an interface to the XMMS multimedia player or the ImageMagick graphics library.

Additionally, the PEAR package manager allows you to use the PEAR class management infrastructure with your personal projects. By creating your own packages that follow the PEAR format, your users can use pear to download and install the files from your project's web site.

This chapter explains how to find a PEAR package you may want to use and how to install it on your machine. Because PEAR has many classes, you need an easy way to browse them. Recipe 21.3 covers the different ways to find PEAR packages; once you've found a package's name, Recipe 21.4 shows how to view package details and information.

Once you locate a class you want to use, you need to run pear to transfer the class to your machine and install it in the correct location on your server. Installing PEAR packages and PECL extensions are the subjects of Recipe 21.5 and Recipe 21.6, respectively. Recipe 21.7 shows how discover if any upgrades are available to packages on your machine and how to install the latest versions. If you want to remove a package, see Recipe 21.8.

Finally, Recipe 21.9 describes how PEAR developers can write classes that abide by PEAR's coding standards and how to document your class with PHPDoc.

PHP 4.3 includes the first stable release of PEAR. Earlier copies of PHP bundled versions of PEAR prior to PEAR 1.0, but pear and the other packages weren't guaranteed to work, as they were still in beta. If you are having problems using PEAR, you should remove any old files that may be interfering with the release version. This includes the pear application itself; it can't always upgrade itself to the latest release.

If you can't upgrade to PHP 4.3 and need to bootstrap a copy of PEAR onto your system, run the following:

% lynx -source http://go-pear.org | php -q
Welcome to go-pear!
Go-pear will install the 'pear' command and all the files needed by
it. This command is your tool for PEAR installation and maintenance.
Go-pear also lets you download and install the PEAR packages bundled
with PHP: DB, Net_Socket, Net_SMTP, Mail, XML_Parser.
If you wish to abort, press Control-C now, or press Enter to continue:

This downloads a PHP script from the PEAR web site and hands it to PHP for execution. The program downloads all files needed to run pear and gets you up and running.

On some Unix systems, you may need to run links instead of lynx. If you have the command-line version of PHP installed, remove the -q flag to PHP; the CLI version automatically suppresses HTTP headers. If go-pear seems to hang, set output_buffering to off in your php.ini configuration file.

The go-pear script requires PHP 4.1 or greater. For the Windows installation, php-cli is the command-line version of PHP.

PHP installs PEAR by default, so if you're running PHP 4.3, you should be able to use PEAR without any additional setup.[1] Out of the box, PEAR installs pear in the same directory as php and places PEAR packages in prefix/lib/php.[2] To install PEAR in another directory, add --with-pear=DIR when configuring PHP.

Once a PEAR package is installed, use it in your PHP scripts by calling require. For example, here's how to include the Net_Dig package:

require 'Net/Dig.php';

If a package name contains an underscore, replace it with a slash, and add .php to the end.

Some packages may require you to include multiple classes, such as SOAP, so instead of requiring SOAP.php, you include SOAP/Client.php or SOAP/Server.php. Read the documentation to discover if a particular package requires nonstandard file includes.

Because PEAR packages are included as regular PHP files, make sure the directory containing the PEAR classes is in your include_path. If it isn't, include and require can't find PEAR classes.

To view instructions and examples showing how to use a particular PEAR class, check the PEAR Manual at http://pear.php.net/manual/en/packages.php or read the top section of the package's PHP files. For an example of a full-featured PEAR class in action, see the discussion of PEAR's database library in Recipe 10.4.

Using the PEAR Package Manager

Problem

You want to use the PEAR package manager, pear. This allows you to install new packages, and upgrade and get information about your existing PEAR packages.

Solution

To execute a command with the PEAR package manager, type the command name as the first argument on the command line:

% pearcommand

Discussion

Here's how to list all installed PEAR packages with the list command:[3]

For a list of all valid PEAR commands, use list-commands . Many commands also have abbreviated names; for example, list is also just l. These names are usually the first few letters of the command name. See Table 21-1 for a list of frequently used commands.

Table 21-1. PEAR package manager commands

Command name

Shortcut

Description

install

i

Download and install packages

upgrade

up

Upgrade installed packages

uninstall

un

Remove installed packages

list

l

List installed packages

list-upgrades

lu

List all available upgrades for installed packages

search

None

Search for packages

pear has commands both for using and for developing PEAR classes; as a result, you may not need all the commands. The package command, for example, creates a new PEAR package. If you only run other peoples' packages, you can safely ignore this command.

Like all programs, if you want to run pear, you must have permission to execute it. If you can run pear while running as root, but not as a regular user, make sure the group- or world-execute bit is set. Similarly, for some actions, pear creates a lock file in the directory containing the PEAR files. You must have write permission to the file named .lock located in that directory.

To find where your PEAR packages are located, run the config-get php_dir command. You can check the value of the include_path by calling ini_get('include_path') from within PHP or by looking at your php.ini file. If you can't alter php.ini because you're in a shared hosting environment, add the directory to the include_path at the top of your script before including the file. See Recipe 8.24 for more on setting configuration variables from within PHP.

If you're behind a HTTP proxy server, configure PEAR to use it with the command:

% pear config-set http_proxy proxy.example.com:8080

You can configure PEAR package manager settings using:

% pear set-configsetting value

Here setting is the name of the parameter to modify and value is the new value. To see all your current settings, use the config-show command:

Discussion

There are a few ways to review PEAR's packages. First, to browse the listings in a directory-style fashion, go to http://pear.php.net/packages.php. From there you can burrow into each individual PEAR category.

This request displays a slightly different set of information. It doesn't include the release data but does include the general PEAR category and the latest version number for the package.

The package home page provides a more complete view and also provides links to earlier releases, a change log, and browseable access to the CVS repository. You can also view package download statistics. Figure 21-1 shows a sample package information page.

See Also

Installing PECL Packages

Problem

You want to install a PECL package; this builds a PHP extension written in C to use inside PHP.

Solution

Make sure you have all the necessary extension libraries and then use the PEAR package manager install command:

% pear install xmms

To use the extension from PHP, load it using dl( ) :

dl('xmms.so');

Discussion

The frontend process for installing PECL packages is just like installing PEAR packages for code written in PHP. However, the behind-the-scenes tasks are very different. Because PECL extensions are written in C, the package manager needs to compile the extension and configure it to work with the installed version of PHP. As a result, at present, you can build PECL packages on Unix machines and on Windows machines if you use MSDev.

Unlike PHP-based PEAR packages, PECL extensions don't automatically inform you when you lack a library necessary to compile the extension. Instead, you are responsible for correctly preinstalling these files. If you are having trouble getting a PECL extension to build, check the README file and the other documentation that comes with the package. The package manager installs these files inside the docs directory under your PEAR hierarchy.

When you install a PECL extension, the PEAR package manager downloads the file, extracts it, runs phpize to configure the extension for the version of PHP installed on the machine, and then makes and installs the extension. It may also prompt you for the location of libraries:

If these libraries are in a standard location, hitting Return selects the autodetect option. PHP then searches for the libraries and selects them; you don't need to enter an explicit pathname, as in the case of the xmms library shown earlier.

PECL extensions are stored in different places than non-PECL packages. If you want to run pear, you must be able to write inside the PHP extensions directory. Some PECL packages, such as xmms, install files in the same directory as the PHP binary. Because of this, you may want to install these packages while running as the same user you used to install PHP. Also, check the execute permissions of these files; because most PEAR files aren't executable, your umask may not provide those executable files with the correct set of permissions.

See Also

Upgrading PEAR Packages

Problem

You want to upgrade a package on your system to the latest version for additional functionality and bug fixes.

Solution

Find out if any upgrades are available and then tell pear to upgrade the packages you want:

% pear list-upgrades
% pear upgradePackage_Name

Discussion

Upgrading to a new version of a package is a simple task with the PEAR Package Manager. If you know a specific package is out of date, you can upgrade it directly. However, you may also want to just periodically check to see if any new releases are available.

To do this, user the list-upgrades command, which prints out a table showing package names, the new version number, and the size of the download:

Uninstalling PEAR Packages

Problem

Solution

Discussion

Uninstalling a package removes it completely from your system. If you want to reinstall it, you must begin as if the package was never installed. PEAR doesn't warn you if you try to remove a package that's dependent on another package, so be careful when you uninstall.

There is no way to automatically roll back an upgrade to an earlier version of a package using uninstall. Also, PEAR complains if you try to install an earlier version over a later one. To force PEAR to overwrite a newer version, use install -f or install --force:

See Also

Documenting Classes with PHPDoc

Problem

Solution

Use PHPDoc. This allows PEAR to accurately list your class, and you can use the PHPDoc tools to automatically generate API documentation in HTML and XML.

PHPDoc syntax is based on Javadoc. The following tags are available for use: @access , @author, @package, @param, @return, @since, @var, and @version.

You can then use PEAR's PHPDoc utility to generate documentation.

Discussion

PHPDoc has a special inline documentation style. By formatting your comments in a particular way, the PHPDoc script can parse your code to not only generate which parameters a function take and what type of variable it returns, but also associate comments and other useful information with objects, functions, and variables.

PHPDoc comments are based on the same formatting and naming conventions as Javadoc. So, to flag a comment block to grab PHPDoc's attention, use a traditional C-style comment but use two asterisks after the opening slash:

/**
* This is a PHPDoc comment block
*/

Inside of a block, certain keywords have special meaning. These keywords all begin with an at sign. Table 21-2 lists the keywords and what they stand for.

Any text following a keyword is treated as the value assigned to it. So, in this example, the value of @package is "Example." It can be okay to have two instances of the same keyword, depending upon the situation. For instance, it's perfectly legal to have multiple @param keywords, but it's illegal to have multiple @return keywords.

PHPDoc and the PEAR web site use this information to generate hyperlinked references, so it's important to use a consistent naming scheme, or the cross-references won't work correctly.

To generate PHPDoc, first install the PHPDoc PEAR package. Inside that package is a program named phpdoc ; run it from the command line, and use the -s flag to pass in the directory of the source files. By default, documentation is generated in /usr/local/doc/pear/, so be sure the phpdoc program has write permission to that location, or use -d to alter the destination directory.

To permanently modify the default values, edit the values at the top of the script. Pass -h for a listing of all possible command-line parameters.

PHPDoc isn't very efficient, so be patient. Generating documentation may take a while, depending upon the size of your files. A faster program is currently under development.