PHP CookBook

21.1 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.

To find general information on PEAR, read the PEAR manual; to discover the latest PEAR packages, go to http://pear.php.net. A summary of each week's happenings can be found at http://pear.php.net/weeklynews.php.

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.

Installation on Windows is a two-step process:

C:\> php-cli -r 'readfile("http://go-pear.org");' > go-pear
c:\> php-cli go-pear

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.

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

^[2] This is probably /usr/local/lib/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.