Hack2.Install PEAR Modules

Hack 2. Install PEAR Modules

Access the vast PEAR source code repository to find cool functionality to add to your PHP applications.

The PEAR library is a set of user-contributed PHP modules that are structured in a common way so that they can be downloaded, installed, and versioned consistently. PEAR is so fundamental to PHP that it now comes as a standard part of the PHP installation.

To find out what is available in the PEAR library, surf on over to the PEAR site (http://pear.php.net/). There you can find the list of modules or search by module name. When you find a module you want to install, simply run the pear program on your command line.

On Windows, the invocation looks like this:

 C:\> pear install DB downloading DB-1.7.6.tgz … Starting to download DB-1.7.6.tgz (124,807 bytes) ............................done: 124,807 bytes install ok: DB 1.7.6 

In this case, I am installing the PEAR module named DB [Hack #35], an object-oriented database wrapper that is used extensively in this book.

On Windows, you might need to make sure that the pear.bat batch file, located in the bin directory of your PHP installation directory, is on the path. In addition, the directory where the PEAR modules are installed is often not created by default. In that case, you need to use Windows Explorer or the command line to create the PEAR directory. If you installed PHP in c:\php5, the PEAR directory is c:\php5\pear. You might also need to add this directory to the modules path in the c:\windows\php.ini file.

On Unix systems, including Mac OS X, running the pear program is just as easy:

 % sudo pear install HTTP_Client downloading HTTP_Client-1.0.0.tgz … Starting to download HTTP_Client-1.0.0.tgz (6,396 bytes) .....done: 6,396 bytes install ok: HTTP_Client 1.0.0 % 

Here I am installing the HTTP_Client PEAR module [Hack #84]. You'll have to use the sudo command because the PEAR module will be installed system-wide.

To get a list of available PEAR modules, run the list-all command:

 % pear list-all All packages: ============= Package Latest Local     APC 3.0.3 Cache 1.5.4 1.5.4 Cache_Lite 1.4.1 apd 1.0.1 memcache 1.4 parsekit 1.0 … 

Because this is not making any changes to system-wide files, super-user access is not required.

Some PEAR modules are listed as unstable. This means that they are currently in development. Asking PEAR to install them will result in an error message:

 % sudo pear install Services_Amazon  No release with state equal to: 'stable' found for 'Services_Amazon' 

Here, the Amazon Web Services module is so newand possibly unstablethat it's marked as alpha or beta. So you need to force PEAR to install the module using the -f directive:

 % sudo pear install -f Services_Amazon  Warning: Services_Amazon is state 'beta' which is less stable than state     'stable' downloading Services_Amazon-0.2.0.tgz … Starting to download Services_Amazon-0.2.0.tgz (8,086 bytes) .....done: 8,086 bytes install ok: Services_Amazon 0.2.0 

Another option is to request a specific version of the module:

 % sudo pear install Services_Amazon-0.2.0 downloading Services_Amazon-0.2.0.tgz … Starting to download Services_Amazon-0.2.0.tgz (8,086 bytes) .....done: 8,086 bytes install ok: Services_Amazon 0.2.0 

This will bypass any stability check and is handy when you want to revert to an earlier version of a module when a later version fails to work.

You can find out which PEAR modules are already installed on your system by using the list command:

 % pear list Installed packages: =================== Package              Version State Archive_Tar  1.1     stable Benchmark            1.2.3   stable     Cache                1.5.4   stable Console_Getopt       1.2     stable DB                   1.7.6   stable     HTML_Template_IT     1.1     stable HTTP                 1.3.6   stable     HTTP_Client          1.0.0   stable     HTTP_Request         1.2.4   stable     Image_Barcode        1.0.4   stable     Log                  1.8.7   stable     Net_Curl             0.2     stable     Net_SmartIRC         1.0.0   stable     Net_Socket           1.0.6   stable     Net_URL              1.0.14  stable     Net_UserAgent_Detect 2.0.1   stable     PEAR                 1.3.5   stable     PHPUnit              1.2.3   stable     PHPUnit2             2.2.1   stable SOAP                 0.9.1   beta Services_Amazon      0.2.0   beta     Services_Google      0.1.1   alpha     Services_Weather     1.3.1   stable     Services_Yahoo       0.1.0   alpha     XML_Parser           1.2.6   stable     XML_RPC              1.2.2   stable     XML_RSS              0.9.2   stable     XML_Serializer       0.16.0  beta     XML_Tree             1.1     stable     XML_Util             1.1.1   stable 

Don't confuse list with list-all; the first lists installed modules, and the second lists available modules.

Becoming fluent with PEAR is critical to making the best use of PHP. The libraries built into PHP are fine, but the additional PEAR modules make PHP a true rapid application development environment.

1.3.1. Installing PEAR Modules on Your ISP

Because you don't have super-user access on an ISP machine, you will need to be a little cleverer about how you install PEAR modules. The first step is to establish a library directory where the PEAR modules will go. You do this by creating the directory on your ISP machine. Then you use the ini_set command to add the directory onto the include path, as shown in the following code fragment:

 <?php  ini_set( 'include_path',  ini_get( 'include_path' ).PATH_SEPARATOR."/users/jherr/mylibs" );  ?> 

This code should go into your PHP page or into a common PHP header that is included on every page.

This adds the directory /users/jherr/mylibs to the list of paths that the include and require directives will search. You must do this before attempting to require or include any installed PEAR modules.

After creating the library directory and tweaking the include path, you can download the PEAR module you want to install from the PEAR site (http://pear.php.net/). Unpack it and place the source files in the library directory you just specified (/users/jherr/mylibs in this example).