You want to use the PEAR installer, pear. This allows you to install new packages, upgrade, and get information about your existing PEAR packages.
To execute a command with the PEAR installer, type the command name as the first argument on the command line:
% pear command
Here's how to list all installed PEAR packages with the list command:
% pear list Installed packages, channel pear.php.net: ========================================= 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.
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 proxy.example.com:8080
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 pear.php.net): ===================================== Auto-discover new Channels auto_discover <not set> Default Channel default_channel pear.php.net HTTP Proxy Server Address http_proxy <not set> PEAR server [DEPRECATED] master_server pear.php.net Default Channel Mirror preferred_mirror pear.php.net 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/
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 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, 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("http://go-pear.org");' > 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 http://pear.php.net/manual/en/installation.php