Installing packages

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
install failed

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

$ pear config-set preferred_state alpha
config-set succeeded

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
install failed

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

We removed this section, because, today, manually installing a package requires a deeper understanding of the way how packages are organized and what happens during the installation process. You should read the section about the package.xml in the Developers Guide (package.xml and package.xml 2.0), if you really want install a package without the PEAR installer.

If you want to install PEAR on a remote host without shell access, you should look into Installation of a local PEAR copy on a shared host.

This passage will describe how to install the latest development version of a PEAR package from SVN.

It is NOT recommended to run a package from SVN in working environments! Because SVN versions are not regular releases, this means:

• You could get no kind of help from the maintainer or anybody other.
• Versions in SVN may break the upgrade mechanism of the PEAR Installer.

You should use a package from SVN 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 SVN, 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.

1. Get the package files from SVN like described in http://www.php.net/svn.php

   The name of the module to checkout is pear/<packagename>/trunk, i.e. svn checkout http://svn.php.net/repository/pear/packages/HTTP_Client/trunk HTTP_Client.

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

3. Create a valid package using the PEAR Installer pear package <path to package.xml>

4. If you have already installed the package: remove it to avoid version conflicts: pear uninstall <package>

5. Install your package archive: pear install <package-file>

   Now, you have a SVN version installed!

You should upgrade to an official release of the package as early as possible. Before you install the official release, uninstall the SVN version to avoid version conflicts.

The procedure of installing PECL packages is described in the pecl manual section on the PHP website.