PHP CookBook

Recipe 21.2 Using the PEAR Package Manager

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

21.2.2 Solution

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

% pear  command 

21.2.3 Discussion

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

^[3] In early versions of pear, this command was list-installed.

% pear list
Installed packages:
=  ==  ==  ==  ==  ==  ==  ==  ==  ==
+-----------------+----------+--------+
| Package         | Version  | State  |
| Archive_Tar     | 0.9      | stable |
| Console_Getopt  | 0.11     | beta   |
| DB              | 1.3      | stable |
| HTTP            | 1.2      | stable |
| Mail            | 1.0.1    | stable |
| Mail_Mime       | 1.2.1    | stable |
| Net_SMTP        | 1.0      | stable |
| Net_Socket      | 1.0.1    | stable |
| Net_URL         | 1.0.4    | stable |
| PEAR            | 0.91-dev | beta   |
| XML_Parser      | 1.0      | stable |
| XML_RPC         | 1.0.3    | stable |
+-----------------+----------+--------+

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-config  setting 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:

% pear config-show
Configuration:
=  ==  ==  ==  ==  ==  ==  =
+---------------------+-----------------+-------------------------------------+
| PEAR executables    | bin_dir         | /usr/local/bin                      |
| directory           |                 |                                     |
| PEAR documentation  | doc_dir         | /usr/local/lib/php/docs             |
| directory           |                 |                                     |
| PHP extension       | ext_dir         | /usr/local/lib/php/extensions/no-de |
| directory           |                 | bug-non-zts-20020429                |
| PEAR directory      | php_dir         | /usr/local/lib/php                  |
| PEAR data directory | data_dir        | /usr/local/lib/php/data             |
| PEAR test directory | test_dir        | /usr/local/lib/php/tests            |
| HTTP Proxy Server   | http_proxy      | <not set>                           |
| Address             |                 |                                     |
| PEAR server         | master_server   | pear.php.net                        |
| PEAR password (for  | password        | <not set>                           |
| maintainers)        |                 |                                     |
| PEAR username (for  | username        | <not set>                           |
| maintainers)        |                 |                                     |
| Preferred Package   | preferred_state | stable                              |
| State               |                 |                                     |
| Unix file mask      | umask           | 18                                  |
| Debug Log Level     | verbose         | 1                                   |
+---------------------+-----------------+-------------------------------------+

For a brief description of each configuration option, use the config-help command.