PEAR is short for “PHP Extension and Application Repository” and is pronounced just like the fruit. The purpose of PEAR is to provide:
- A structured library of open-source code for PHP users
- A system for code distribution and package maintenance
- A standard style for code written in PHP, specified here
- The PHP Extension Community Library (PECL), see more below
- A web site, mailing lists and download mirrors to support the PHP/PEAR community
There is not important what it is your OS: you could download http://pear.php.net/go-pear to begin installation.
mv go-pear go-pear.php
aptitude install php-pear (Debian / Ubuntu)
yum install php-pear (Fedora / Centos)
Verifying the include path
To use PEAR and PEAR compatible packages in your applications, you normally include them into your PHP scripts using require_once(). For this to work, PEAR’s php_dir must be a part of PHP’s include path.
1. First, check where PEAR installs .php files:
pear config-get php_dir
mine output is:
This directory will contain System.php.
2. Now it’s time to find which configuration file is used by your PHP installation. On command line, execute:
php --ini | grep Loaded
mine output is:
Loaded Configuration File: /etc/php.ini
To see which php.ini is used by PHP on your web server, create a file with only as the contents, and save it in your local web root as check_php.php. Open the file in your browser as http://localhost/check_php.php, to find the path to the php.ini file your web server is using.
3. include_path about php.ini must include php pear directory:
grep include_path /etc/php.ini | egrep "^[^;]"
mine output is:
include_path = ".:/usr/local/php/pear/"
If your include_path does not contain php pear directory, then you must add it modifying php.ini.
To get PEAR working properly, you need to adjust PHP’s include_path. After you found php.ini, open it in an editor.
Search for the line include_path.
Now that you found it, you probably will see a semicolon ; at the beginning. This means the line is a comment. Add a new line below it.
In this line, write:
Depending on your operating system, add a : (Unix/Linux/FreeBSD/Mac OS X) or a ; (Windows) after the dot. Add PEAR’s php_dir after it. (The directory System.php is located in!)
The result should look like that:
Checking if PEAR works
Now that this is done, try including a file. Create a new check_pear.php file with the following contents:
System.php is shipped with every PEAR installation and thus should be on your computer, too. Open the file with the browser from your web server, and also try it on command line:
The only output should be
A message like:
Warning: require_once(System.php): failed to open stream:
No such file or directory in /path/to/check_pear.php on line 2
means that your include path is not correct. (So go and fix it!)
After getting PEAR working on your machine you most likely want to install some packages. This guide shows people new to the PEAR command line installer how to get started. The general command to install a PEAR package named “foo” is
pear install foo
Typing this and pressing return, the package will be downloaded and installed on your computer. It does not matter if you write the package name in lowercase, UPPERCASE or MixedCase – the installer will find the package by lowercasing the name.
When a package is already installed, you will get the following message:
pear install foo
Ignoring installed package pear/foo
Nothing to install
This happens even if there is a newer version of the package! The correct command to upgrade to the lastest version is
pear upgrade foo
upgrade ok: channel://pear.php.net/Foo-1.2.3
If the package already has the lastest version, you will get a message similar to the following:
Ignoring installed package pear/Foo
Nothing to upgrade
In the case you deleted some file and really really want to re-install the package, you have two choices:
- Uninstall the package, and reinstall it afterwards
- Force the installation
Forcing an command should only be done when you absolutely know what you are doing – you might in some circumstances break PEAR otherwise. Forcing something should always be the last option.
pear install -f foo
pear upgrade -f foo
Unstable alpha/beta packages
Now and then, you will get error messages like
Failed to download pear/foo within preferred state "stable",
latest release is version 0.1.2, stability "beta",
use "channel://pear.php.net/foo-0.1.2" to install
Cannot initialize 'channel://pear.php.net/foo', invalid or missing package file
Package "channel://pear.php.net/foo" is not valid
Reason for this is that PEAR by default installs stable packages only. When a package is in state devel, alpha or beta it will refuse to install them. You can easily persuade it by adding either the version number or the stability you are willing to accept:
pear install Foo-beta
pear install Foo-alpha
You can also install a specific version, or upgrade to a specific version regardless of the state:
pear install Foo-1.2.3
pear upgrade Foo-1.2.3
Verifying the open basedir
It may happen that from the command line php pear works and via browser no. In the apache configuration file of domain may need to add:
php_admin_value open_basedir "/var/www/domain.my/httpdocs:/usr/local/php/pear/:/tmp"
php_admin_value include_path ".:/usr/local/php/pear/"
Reference: about PEAR, getting started, installing packages, checking if PEAR works, mediatemple.net.