Using the PEAR Package Manager
The PEAR Package Manager is not a necessary part of PEAR, but it is an important one, and it's part of what defines PEAR, as shown earlier. It streamlines the process of downloading packages from PEAR and checks for package dependencies. It places the package files in their correct locations and even helps developers make packages of their own for use in PEAR.
For the most part, the developer functionality of the PPM is not necessary for the average user of PEAR classes, so those commands and options are omitted from the following descriptions. What follows are basic commands for managing a local installation of PEAR, from listing packages to installing and removing them.
Listing Packages
To see what PEAR packages are installed, enter the following at a command prompt (assuming pear is in the PATH):
pear list
This command outputs a listing that looks similar to this:
Installed packages:
===================
Package Version State
Archive_Tar 1.1 stable
Console_Getopt 1.2 stable
PEAR 1.3.3.1 stable
XML_RPC 1.1.0 stable
If no other packages have been installed other than those included by default, the packages in the listing will be those considered current PFC packages. Another similar listing is provided by the pear list-all command, which shows all packages in PEAR and notes the current version number of those packages installed on the local system. If it's not installed, no version number is listed in the "Local" column.
Finding Packages
There are many packages in the repository, and many more in the proposal stages. Although the initial PEAR installation starts out with a small set of packages, chances are that you'll need other packages. The PPM has a useful tool for searching by package name, aptly named search.
Although a search by package name may be performed at http://pear.php.net, the PPM provides the same functionality. For example, consider a Web-based application that requires some form of page-caching mechanism. Rather than build such a mechanism from scratch, first check the PEAR repository for a cache package by entering the following at a command prompt:
pear search cache
This will return results similar to the following:
Matched packages:
=================
Package Stable/(Latest) Local
Cache 1.5.4 Framework for caching of arbitrary data.
Cache_Lite 1.3 Fast and Safe little cache system
memcache 1.1 memcached extension
According to this listing, there are three packages that deal with caching; however, not much else is given in the way of helpful information about these packages. To retrieve useful information about a package, use the remote-info command: pear remote-info Cache. This will return a detailed listing about the package, including its maintainers, release date, license type, status, and more.
|
By default, the PPM's master_server parameter is set to pear.php.net. This means that the PPM will use that server to check for and download packages. This can be changed with the pear config-set command. This chapter assumes the use of pear.php.net as the master server in all examples. |
Installing and Upgrading Packages
The PPM may be used to install PEAR packages directly from the code repository. They do not even need to be downloaded from the website; the PPM takes care of this. In addition, the pear install command checks for package dependencies before proceeding with the install. If necessary, it will fail as it does in the following example:
$> pear install Cache
downloading Cache-1.5.4.tgz ...
Starting to download Cache-1.5.4.tgz (30,690 bytes)
.........done: 30,690 bytes
requires package `HTTP_Request'
Cache: Dependencies failed
The PPM does not download and install the package's dependencies by default. You may choose to install each dependency separately, or you may add the a option to download and install all required and optional dependencies or the o option to download and install required dependencies only.
$> pear install o Cache
downloading Cache-1.5.4.tgz ...
Starting to download Cache-1.5.4.tgz (30,690 bytes)
.........done: 30,690 bytes
downloading HTTP_Request-1.2.3.tgz ...
Starting to download HTTP_Request-1.2.3.tgz (12,823 bytes)
...done: 12,823 bytes
downloading Net_URL-1.0.14.tgz ...
Starting to download Net_URL-1.0.14.tgz (5,173 bytes)
...done: 5,173 bytes
install ok: Net_URL 1.0.14
install ok: HTTP_Request 1.2.3
install ok: Cache 1.5.4
As seen in the preceding listing, not only is HTTP_Request downloaded as a required dependency of Cache, but Net_URL is downloaded as a dependency of HTTP_Request. When the install is a success, the PPM will note it with an appropriate message:
install ok: Cache 1.5.4
Similar to the install command is upgrade. PEAR packages are in a state of constant development, so there are often upgrades to packages. To check for package upgrades, type pear list-upgrades. If an upgrade exists, the PPM will show both the local version of the package and the current (upgrade) version in the repository.
Available Upgrades (stable):
============================
Package Local Remote Size
Archive_Tar 1.1 (stable) 1.2 (stable) 14.5kB
The preceding listing shows that an upgrade exists for Archive_Tar. To download and install this upgrade, type pear upgrade Archive_Tar. The process for downloading and checking dependencies is similar to that of the pear install command:
$> pear upgrade Archive_Tar
downloading Archive_Tar-1.2.tgz ...
Starting to download Archive_Tar-1.2.tgz (14,792 bytes)
.....done: 14,792 bytes
upgrade ok: Archive_Tar 1.2
As an alternative, there is also the pear upgrade-all command, which downloads and installs all available upgrades.
Uninstalling Packages
Sometimes it may be necessary to remove a package from the local PEAR installation. For this case, the PPM includes an uninstall command:
$> pear uninstall Cache
uninstall ok: Cache
If uninstall is a success, it displays a message to that effect. Otherwise, if other packages are dependent upon the one being removed, a dependency message will be displayed. If the dependency is considered optional, it will proceed with the removal. If it is a required dependency, uninstall will fail.
|
Be aware that the PPM does not know whether the code in applications on the machine uses a PEAR package. It tests only known package dependencies. If a package is an optional dependency or has no dependencies, it will remove it regardless of whether any code uses it. |
Alternative Installation Methods
The pear install command is versatile. It does not need to connect to pear.php.net to download packages. Because PEAR is a standard of coding and a system for distribution, other developers may develop packages according to the PEAR package standards and release them separately from the main repository. For the most part, these developers end up submitting a proposal to the PEAR Proposal system (PEPr), so there are few places outside of PEAR where these packages may be found, but they are therejust do a search for them.
To install any package that is not included in the PEAR database or to install packages by an alternative method, either download the gzipped file, or use the URL to install it. The install command works the same in both ways:
pear install package.tgz
pear install http://example.net/path/to/package
You may also unzip the gzipped file and install the package using its package.xml file:
pear install /path/to/package.xml
This is particularly helpful to developers for testing packages or for preparing packages for use with other package managers such as RPM Package Manager (RPM).
|
For the sake of example, the Horde project has one such package that is not part of PEAR, although it follows the package conventions, so it may be easily installed via pear install.
The file is located at http://pear.horde.org. To download and install the Horde_VFS package that is located there, either download the gzipped file and install it locally or execute the following:
pear install http://pear.horde.org/Horde_VFS
|
|
To see all available PPM actions, type pear help. To see the help file for a particular command, type pear help command_name. |
 | 
