PEAR

From DreamHost
Revision as of 01:15, 17 April 2010 by Rlparker (Talk | contribs)

Jump to: navigation, search
The instructions provided in this article or section are considered advanced.

You are expected to be knowledgeable in the UNIX shell.
Support for these instructions is not available from DreamHost tech support.
Server changes may cause this to break. Be prepared to troubleshoot this yourself if this happens.
We seriously aren't kidding about this.

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

Note: It is important that your .pearrc file reside in your $HOME directory.

You may also need to run the following commands if you get a message like Error: cannot download "pear/Console_Getopt" Replace <username> with your DH account name

$ pear config-set download_dir /home/<username>/tmp/pear/cache
$ pear config-set cache_dir /home/<username>/tmp/pear/cache
$ pear config-set temp_dir /home/<username>/tmp/pear/temp

Then:

$ pear install --installroot ~/.pear -o PEAR

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.

Here is an example bash_profile that provides support for PEAR v1.4+ and PHP5 on a shared DreamHost account. It is important that you use export to have the paths stick when using PEAR from the command line.

export PHP_PEAR_PHP_BIN=/usr/local/php5/bin/php
export PATH=/home/username/.pear:/usr/local/php5/bin:$PATH

Note that the changes become effective upon the next login!

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: Note: This returns v4.4, but when I use phpinfo() it returns 5.1

 $ 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 --installroot ~/.pear 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  --installroot ~/.pear pear/PackageName#featurename

In the MDB2 exampe, the command would be:

$ pear install  --installroot ~/.pear 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 --installroot ~/.pear

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

$ pear config-get preferred_state
stable

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

ini_set( 
  'include_path', 
  ini_get( 'include_path' ) . PATH_SEPARATOR . "/home/(youruser)/pear/php"
);                                                                       

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 = '/home/(youruser)/.pearrc';

(where (youruser) is your Dreamhost home directory, e.g. '/home/user')


Note: home directories

For me on pretzel.dreamhost.com only referrers like '/home/.cyndar/user/' worked even if on a console the following result was shown:

[pretzel]$ pwd
/home/user/

You can get the correct include_path resp. home directory information via a PHP phpinfo();-script phpinfo-script.

Note: PHP 5 & PEAR

As pointed out here, if you are using PHP 5, it was installed to different directory, so you will need to use the following code block instead:

set_include_path(
	get_include_path() . 
	PATH_SEPARATOR . '/usr/local/lib/php'
);

(The <pre> tag strips the underscores from set_include_path and get_include_path. Be sure to add those.)

It's unclear where to use this code block. What file do we modify? Is it one of the PEAR files?

set_include_path (as is ini_set above) is a PHP function. You use it in any php files you want to make use of your local PEAR.

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