Section 26.0. Introduction

26.0. Introduction

PEAR is the PHP Extension and Application Repository, a collection of open source classes that work together. Developers can use PEAR classes to parse XML, implement authentication systems, make SOAP requests, send MIME mail with attachments, and a wide variety of other common (and not so common) tasks. A pear is also a tasty fruit.

PECL is the PHP Extension Community Library. PECL, pronounced "pickle," is a series of extensions to PHP written in C. These extensions are just like the ones distributed with the main PHP release, but they're of more specialized interest'such as an interface to the libssh2 library or the ImageMagick graphics library.

To find general information on PEAR, read the PEAR manual; to discover the latest PEAR packages, go to http://pear.php.net. The PEAR web site also provides links to mailing list archives, as well as RSS feeds that allow easy monitoring of new package releases.

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 simply as the PEAR installer. Recipe 26.1 shows how to use the PEAR installer.

Additionally, the PEAR installer 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. If you distribute more than a handful of packages this way, you'll want to consider operating a formal PEAR channel server. The PEAR installer supports a wide variety of channel-specific features that are covered in recipes throughout this chapter.

PEAR requires PHP 4.2.0 or later, preferably with PHP built using the --with-zlib configuration flag. PEAR packages are available as gzipped tar archives, and are also available as uncompressed tar archives. The package installation process is more convenient in PHP environments with zlib capability.

This chapter explains how to find a PEAR package that you may want to use and how to install it on your machine. Because PEAR and PEAR channels offer many packages, you need an easy way to browse them. Recipe 26.2 covers different ways to find PEAR packages. Once you've found a package's name and determined which channel server it is on, Recipe 26.3 shows how to view package details and information.

Once you locate a package you want to use, you need to run pear to transfer the package to your machine and install it in the correct location on your server. Installing PEAR packages and PECL extensions are the subjects of Recipes 13.12 and 26.7, respectively. Recipe 26.5 shows how to 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 26.6.

PHP has installed PEAR by default since PHP 4.3.0, so if you're running a version of PHP more recent than that, odds are that you can use PEAR without any additional setup.^[] PEAR has changed significantly since its initial inclusion with PHP 4.3.0, so it is strongly recommended that you upgrade to PEAR 1.4.9 or later. See Recipe 26.5 for details on upgrading PEAR. If you would prefer a clean PEAR install, refer to Recipe 26.1.

^[] If you disable building the command-line version of PHP with --disable-cli, PHP doesn't install PEAR.

When installed during a PHP installation, PEAR installs pear in the same directory as php and places PEAR packages in prefix/lib/php.^[] To install PEAR in another directory, add --with-pear=DIR when configuring PHP. You may also install multiple instances of PEAR, which can come in handy in a shared server environment. Refer to Recipe 26.1 for details on installing multiple instances of PEAR.

^[] This is probably in one of /usr/local/lib/php, /usr/lib/php, or, in some Linux distributions, /usr/share/php.

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

require_once 'Net/Dig.php';

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

Some packages may provide multiple class files, some of which should be used in certain scenarios, and not in others. The SOAP package is a good example of this; instead of requiring SOAP.php, you include SOAP/Client.php or SOAP/Server.php, depending on the needs of your script. Read the package documentation to determine if a particular package requires a specific inclusion approach depending on the usage scenario.

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

To view instructions and examples of how to use a particular PEAR package, check the PEAR web site at http://pear.php.net/packages.php. Many packages have end-user documentation complete with examples. The rest typically include at least a set of generated API documentation that provides examples of usage. If all else fails, read the top section of the package's PHP files; most contain an example of usage there as well.

Documentation for PECL extensions is not always as easy to find. Some PECL extensions are very well documented within the main PHP manual; the ClibPDF extension (available at http://www.php.net/cpdf) is an excellent example. Other PECL extensions are not documented at all, and usage must be gleaned by reading PHP test scripts included with the source bundles from the PECL web site. In extreme cases, you can only get the full idea of what an extension does by reading the extension source code.

The combination of PEAR and PHP provides a vast collection of high-quality reusable code that make both projects tremendous assets to the PHP community at large.