After getting PEAR working on your machine (see Installation) 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
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
If you don't care about stability and don't want to specify the -alpha or -beta suffix everytime, you can change the global stability config option:
$ pear config-set preferred_state alpha
You can switch between the following stability states (sorted by stability):
A package often requires other packages to be installed to function correctly. Such a relation is called a dependency. The PEAR installer has full support for dependencies; it can automatically install required and/or optional dependencies if you wish so.
If you try to install a package with required dependencies, you will get an error that the installation failed. Looking deeper and actually reading the messages shows you that the package needs dependencies that are not installed on your system:
$ pear install html_page2
Did not download dependencies: pear/HTML_Common,
use --alldeps or --onlyreqdeps to download automatically
pear/HTML_Page2 requires package "pear/HTML_Common" (version >= 1.2)
No valid packages found
You have several choices:
Install dependent packages by hand
Let PEAR automatically install necessary dependencies only
Let PEAR automatically install necessary and optional dependencies
The first method can be a painful and daunting process, because dependent packages itself can have dependencies.
Both other methods just require a switch to the install command, either --onlyreqdeps (install required dependencies only) or --alldeps (install all dependencies).
$ pear install --onlyreqdeps html_page2
WARNING: "pear/HTML_Common" is deprecated in favor of "pear/HTML_Common2"
downloading HTML_Page2-0.5.0beta.tgz ...
Starting to download HTML_Page2-0.5.0beta.tgz (15,467 bytes)
......done: 15,467 bytes
downloading HTML_Common-1.2.4.tgz ...
Starting to download HTML_Common-1.2.4.tgz (4,519 bytes)
...done: 4,519 bytes
install ok: channel://pear.php.net/HTML_Common-1.2.4
install ok: channel://pear.php.net/HTML_Page2-0.5.0beta
You can download individual packages for e.g. offline installation on a second machine just as you would install or upgrade a package:
$ pear download Foo
After downloading, you will have a file like Foo-1.2.3.tgz if the latest version of Foo was 1.2.3. Installing it is as easy as typing
$ pear install Foo-1.2.3.tgz
This passage will describe how to install the latest development version of a PEAR package from CVS.
It is NOT recommended to run a package from CVS in working environments! Because CVS versions are not regular releases, this means:
You could get no kind of help from the maintainer or anybody other.
Versions in CVS may break the upgrade mechanism of the PEAR Installer.
You should use a package from CVS only, if:
The maintainer recommended it for you.
You want to help in development of a package.
You really need a special patch or function, which is not currently released.
If you still want to install a package from CVS, you have to do the same steps like a package maintainer creating a new release of a package. If you have problems following the next steps, take a look into the Developers Section of the manual.
Get the package files from CVS like described in http://www.php.net/anoncvs.php
The name of the module to checkout is pear/<packagename>, i.e. cvs -d :pserver:firstname.lastname@example.org:/repository checkout pear/HTTP_Client.
Check the package.xml file, especially the dir and file entries. They must match the existing files and directory structure. If they differ, contact the package maintainer and ask for an update of the package.xml.
Create a valid package using the PEAR Installer pear package <path to package.xml>
If you have already installed the package: remove it to avoid version conflicts: pear uninstall <package>
Install your package archive: pear install <package-file>
Now, you have a CVS version installed!
You should upgrade to an official release of the package as early as possible. Before you install the official release, uninstall the CVS version to avoid version conflicts.
The procedure of installing PECL packages is described in the pecl manual section on the PHP website.