PEAR

From DreamHost

PEAR is an open-source framework and distribution system for reusable PHP components. PEAR is object-oriented and works with PHP 4+. Modules undergo a peer-review process and must adhere to strict coding standards, both in regards to coding style and implementation.

Installation

Dreamhost includes only a bare set of PEAR modules on shared hosting accounts, and does not allow users to add more to the base install. To install your own set of PEAR modules on a Dreamhost shared hosting account, SSH into your account and issue the following command):

pear config-create ${HOME} ${HOME}/.pearrc
pear install -o PEAR

Note: It is important that your .pearrc file reside in your home directory, so run the above commands exactly.

For more information on the commands available, just run pear help:

pear help

Using PEAR from the command line

It is highly suggested that you modify your ~/.bash_profile to ensure that your environment is properly configured to access your local PEAR installation before defaulting to the shared installation. PEAR also tests for the existence of the PHP_PEAR_PHP_BIN environment variable.

If your local installation of PEAR is v1.4.0 or above, you should also update your PATH variable to point to the proper PHP5 location.

For example, you can add the following lines to ~/.bash_profile to provide support for PEAR v1.4+ and PHP5 on a shared DreamHost account.

For PHP 5.2:

export PHP_PEAR_PHP_BIN=/usr/local/php5/bin/php
export PATH=${HOME}/pear:/usr/local/php5/bin:${PATH}

For PHP 5.3:

export PHP_PEAR_PHP_BIN=/usr/local/php53/bin/php
export PATH=${HOME}/pear:/usr/local/php53/bin:${PATH}

To activate the changes you've just made, run the following:

. ~/.bash_profile

To see if your environment is correctly set use the following commands in your BASH session:

To determine which PHP (local or shared) command will be used:

which php

To determine which PHP version is being used enter this command:

php -v

To determine which PEAR (local or shared) command will be used:

which pear

To determine which PEAR version is being used enter this command:

pear -V

Use this command to display all your PEAR settings, your local configuration data should be displayed.

pear config-show

Installing Packages

Pear packages can be installed right from the command line. To see a list of packages, go to http://pear.php.net. To install a package, issue the following command:

pear install pear/PackageName

Where PackageName is the name of the PEAR package (Mail, Mail_Mime, MDB2, etc.)

Some packages have additional features that can also be installed, for instance MDB2 contains features that are database specific. To add a feature to an already installed package, issue the following command:

pear install pear/PackageName#featurename

In the MDB2 exampe, the command would be:

pear install pear/MDB2#mysql

Installing All Available Packages

PEAR does not have an 'install-all' option, but you may wish to install all available packages. Using some command-line magic:

pear list-all | awk '/^pear\// {print $1}' | sed -e s@pear/@@ | xargs pear install

This will take a long time to execute. Also, if your preferred package state is 'stable':

pear config-get preferred_state

... then the PEAR will generate error messages for every beta package in the repositories. These messages resemble:

Failed to download pear/Console_ProgressBar within preferred state "stable", latest release is
version 0.5.0beta, stability "beta", use channel://pear.php.net/Console_ProgressBar-0.5.0beta"
to install
Cannot initialize 'channel://pear.php.net/Console_ProgressBar', invalid or missing package file

...but are harmless. I haven't tried this using the --alldeps or --onlyreqdeps options, but this is not recommended as it may result in the installation of deprecated packages such as DB.

Including PEAR modules in scripts

To use local PEAR modules within your PHP, you need to alter the include_path setting to include your directory. This can be done as follows. This code has to go into every php script you write. If you have a bunch of pages, you should probably put it in a configuration file, which you include on every page.

set_include_path("." . PATH_SEPARATOR . ($UserDir = dirname($_SERVER['DOCUMENT_ROOT'])) . "/pear/php" . PATH_SEPARATOR . get_include_path());

Additionally, you may need to include the configuration file that you created. The configuration file includes variables for template and data path, which are required for some PEAR modules.

$pear_user_config = $UserDir . "/.pearrc";

(where $UserDir = dirname($_SERVER['DOCUMENT_ROOT']) dynamically determines your DreamHost home directory, e.g. '/home/user')

PEAR channel server

One reason DreamHost users might want to install their own local version of PEAR on a PHP 5 enabled account is to provide themselves with the infrastructure to host a PEAR channel. For details on how to install a PEAR channel server, read the official instructions

Alternatively, consider using Pirum

I followed these steps to install a PEAR channel server on DreamHost. I installed the Chiara_PEAR_Server 0.19.0RC1 at, http://pear.qubit-toolkit.org/

1. $ /usr/local/php5/bin/pear config-create /home/example .pearrc
   

2. $ pear/pear channel-discover pear.chiaraquartet.net
   

3. $ pear/pear install chiara/Chiara_PEAR_Server-devel
   

4. $ pear/pear install MDB2_Driver_mysql-devel
   

5. Create MySQL database
6. Change default character set from utf8 to latin1, to avoid #1071 - Specified key was too long; max key length is 1000 bytes,

   mysql> alter database qubit_toolkit_org_pear character set latin1;
   

7. Drop <source lang="php">$this->checkSetup($answers);</source> from line 104 in pear/php/Chiara/PEAR/Chiara_PEAR_Server_Database.php because it fails if the database exists, but tables have not yet been created

8. $ pear/pear run-scripts chiara/Chiara_PEAR_Server
   

9. Add <source lang="php">set_include_path('/home/administrator/pear/php'.PATH_SEPARATOR.get_include_path());</source> to line 2 in admin.php

PEAR & PHPUnit

To get command line PHPUnit working on a local install of PEAR I had to add the following to the phpunit executable:

set_include_path(
	get_include_path() . 
	PATH_SEPARATOR . '/home/(username)/pear/php'
);

I'm not sure this is the best solution or if it is indicative of some other problem in my environnment, but it did the trick on my freshly installed domain.

External Links

Official Site: http://pear.php.net