Recipe 26.1. Using the PEAR Installer

26.1.1. Problem

You want to use the PEAR installer, pear. This allows you to install new packages, upgrade, and get information about your existing PEAR packages.

26.1.2. Solution

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

% pear  command 

26.1.3. Discussion

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

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

% pear list Installed packages, channel ========================================= Package                   Version State Archive_Tar               1.3.1   stable Console_Getopt            1.2     stable DB                        1.7.6   stable DB_DataObject             1.8.4   stable Date                      1.4.6   stable File_Passwd               1.1.6   stable HTML_Common               1.2.2   stable HTML_QuickForm            3.2.5   stable HTML_QuickForm_Controller 1.0.5   stable HTML_Template_IT          1.1     stable HTTP_Request              1.3.0   stable HTTP_Session              0.5.1   beta MDB2                      2.0.0   stable Mail_Mime                 1.3.1   stable Net_Socket                1.0.6   stable Net_URL                   1.0.14  stable Net_UserAgent_Detect      2.0.1   stable PEAR                      1.4.9   stable PHP_Compat                1.5.0   stable Pager                     2.4.0   stable XML_Parser                1.2.7   stable XML_RPC                   1.4.0   stable XML_RSS                   0.9.9   beta XML_Serializer            0.18.0  beta XML_Util                  1.1.1   stable

For a list of all valid PEAR commands, use help. Many commands also have abbreviated names; for example, list is also just l. These names are often just the first few letters of the command name. However, the PEAR installer now offers so many commands that it's safer to double-check the list of shortcuts until you get them memorized. You can review the list of pear shortcuts with:

% pear help shortcuts

pear has commands for both using and developing PEAR packages; as a result, there are many commands that you may not need. The package command, for example, creates a new PEAR package. If you only run other peoples' packages, you can safely ignore this command. See Table 26-1 for a list of frequently used commands.

Table 26-1. Common PEAR installer commands

Command name





Download and install packages.



Upgrade installed packages.



Remove installed packages.



List installed packages.



List all available upgrades for installed packages.



Initialize an alternate PEAR Channel from its server.



List all locally configured PEAR Channels.



Search for packages.

Like all shell 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 pear 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 any PEAR files. See Recipe 20.5 for more on setting configuration variables from within PHP.

If you're behind an HTTP proxy server, configure PEAR to use it with this command:

% pear config-set http_proxy

You can configure PEAR installer 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 (channel ===================================== Auto-discover new Channels     auto_discover    <not set> Default Channel                default_channel HTTP Proxy Server Address      http_proxy       <not set> PEAR server [DEPRECATED]       master_server Default Channel Mirror         preferred_mirror Remote Configuration File      remote_config    <not set> PEAR executables directory     bin_dir          /usr/local/bin PEAR documentation directory   doc_dir          /usr/local/lib/php/doc PHP extension directory        ext_dir          /usr/lib/php/extensions/

no-debug-non-zts-20020429 PEAR directory php_dir /usr/local/lib/php PEAR Installer cache directory cache_dir /tmp/pear/cache PEAR data directory data_dir /usr/local/lib/php/data PHP CLI/CGI binary php_bin /usr/local/bin/php PEAR test directory test_dir /usr/local/lib/php/test Cache TimeToLive cache_ttl 3600 Preferred Package State preferred_state beta Unix file mask umask 22 Debug Log Level verbose 1 PEAR password (for password <not set> maintainers) Signature Handling Program sig_bin /usr/local/bin/gpg Signature Key Directory sig_keydir /etc/pearkeys Signature Key Id sig_keyid <not set> Package Signature Type sig_type gpg PEAR username (for username <not set> maintainers) User Configuration File Filename /home/foo/.pearrc System Configuration File Filename /etc/pear.conf

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

If you don't have PEAR installed, or if you're in a shared-hosting environment and you're not able to upgrade or otherwise alter the system-wide PEAR installation, you need to bootstrap a fresh copy of PEAR. There's generally nothing wrong with doing a fresh PEAR installation on a shared host so long as you configure your copy to work within your shared environment. You may wind up with a PEAR package directory of /home/exampleuser/pear/php instead of a more traditional installation location, but as long as your include_path values are set correctly to reflect that, there should be no problem with that approach.

To bootstrap a fresh copy of PEAR from the command line, run the following:

% lynx -source | 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, you may remove the -q flag to PHP; the CLI version automatically suppresses HTTP headers. If go-pear seems to hang, add -d output buffering=off to the piped php command.

Installation on Windows is a two-step process:

C:\> php-cli -r 'readfile("");' > go-pear C:\> php-cli go-pear

The go-pear script requires PHP 4.2 or greater. For the Windows installation, php-cli is the command-line version of PHP.

26.1.4. See Also

PEAR online documentation relating to installation procedures at

PHP Cookbook, 2nd Edition
PHP Cookbook: Solutions and Examples for PHP Programmers
ISBN: 0596101015
EAN: 2147483647
Year: 2006
Pages: 445

Similar book on Amazon © 2008-2017.
If you may any questions please contact us: