Hack 2. 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).