Basic Commands

Table of Contents

Basic Commands

This section covers the basic usage of PEAR, including how you download, install, and begin using packages. If you are interested in contributing code or classes to the PEAR libraries, you should visit http://pear.php.net and read the documentation for contributors.

Getting Help

To see a list of commands available to you via the PEAR program, use the help command, as follows:

phpsrvr#  pear help

To learn more about any given command (whether from this chapter, the web site, or any other documentation), just include the command name after the help command, as follows:

C:\PHP>pear help list
pear list [package]
If invoked without parameters, this command lists the PEAR packages
installed in your php_dir ({config php_dir)).  With a parameter, it
lists the files in that package.

Listing Packages

To view a list of all PEAR packages currently installed on your system, execute the list command as follows:

phpsrvr:~ # pear list
Installed packages:
Package        Version  State
Archive_Tar     1.1      stable
Console_Getopt  1.2      stable
DB              1.5.0RC2 stable
Date            1.4.3    stable
HTTP            1.2.1    stable
Mail            1.1.1    stable
Net_SMTP        1.2.3    stable
Net_Socket      1.0.1    stable
PEAR            1.3.5    stable
XML_Parser      1.0.1    stable
XML_RPC         1.1.0    stable

To view a list of all packages currently available through PEAR, execute the list-all command:

phpsrvr:~ # pear list-all
PACKAGE                   LATEST   LOCAL
APC                        2.0.4
Cache                      1.5.4
Cache_Lite                 1.4.0
apd                        1.0.1
memcache                   1.4
parsekit                   1.0
perl                       0.6
PHP_Compat                 1.3.1
Var_Dump                   1.0.2
Xdebug                     1.3.2
Archive_Tar                1.2       1.2
etc ...

Finally, to list all packages that require an upgrade, execute the list-upgrades command, which returns a list of out-of-date packages, including what version you have and what the latest available version on the PEAR servers is:

C:\PHP> pear list-upgrades

Downloading and Installing Packages

The simplest way to download a package is to use the install command, along with the package name, as follows:

phpsrvr:~ # pear install Date
downloading Date-1.4.3.tgz ...
Starting to download Date-1.4.3.tgz (42,048 bytes)
............done: 42,048 bytes
install ok: Date 1.4.3

For simple packages with no dependencies, this process is usually smooth and quick. However, let us now try to install the XML_RSS package, which enables us to parse Resource Description Framework (RDF) site summary documents. (These are a handy way for site authors to let people know what new content has been posted to their sitesalmost like a ticker tape that the client periodically asks for.)

phpsrvr:~ # pear install XML_RSS
downloading XML_RSS-0.9.2.tar ...
Starting to download XML_RSS-0.9.2.tar (-1 bytes)
.....done: 15,360 bytes
requires package `XML_Tree'
XML_RSS: Dependencies failed

The XML_RSS package depends on another package, called XML_Tree. We could, of course, try to install this package, as follows:

phpsrvr:~ # pear install XML_Tree
downloading XML_Tree-1.1.tgz ...
Starting to download XML_Tree-1.1.tgz (4,826 bytes)
....done: 3,388 bytes
install ok: XML_Tree 1.1

We could then go back and install the XML_RSS package:

C:\PHP>pear install XML_RSS
downloading XML_RSS-0.9.2.tgz ...
Starting to download XML_RSS-0.9.2.tgz (3,515 bytes)
....done: 2,465 bytes
install ok: XML_RSS 0.9.2

All would be well. However, for complicated packages that depend on more than one or two packages (and which, in turn, might depend on other packages), this process becomes tedious quickly. Therefore, you should use the -a switch install command; the -a switch automatically determines all dependencies and installs those, too:

phpsrvr:~ # pear install -a XML_RSS
downloading XML_RSS-0.9.2.tgz ...
Starting to download XML_RSS-0.9.2.tgz (3,515 bytes)
....done: 2,465 bytes
downloading XML_Tree-1.1.tgz ...
Starting to download XML_Tree-1.1.tgz (4,826 bytes)
...done: 3,388 bytes
install ok: XML_Tree 1.1
install ok: XML_RSS 0.9.2

If you want to install a package without worrying about dependencies, you can pass the -f or --force flag to the install command (in which case, install does not check these or worry about other downloads).

To download a package without actually installing it, you can use the download command:

C:\PHP> pear download contact_addressbook
File Contact_AddressBook-0.1.0dev1.tgz downloaded (10930 bytes)

You can then uncompress this archive and manually review its contents, doing what you want with the contents (within the confines of the appropriate license, of course).

Finally, if you have a package that you have downloaded and now want to install, you can use the install command again, but provide the name of the file you downloaded:

C:\PHP> pear download date
File Date-1.4.3.tgz downloaded (28972 bytes)

C:\PHP> pear install Date-1.4.3.tgz
install ok: Date 1.4.3

Getting Information

To learn more about a package that has been downloaded to your machine, execute the info command:

C:\PHP>pear info Date
Provides        Classes:
Package         Date
Summary         Date and Time Zone Classes
Description     Generic classes for representation and
                manipulation of
                dates, times and time zones without the need of
                which is a huge limitation for php programs.
                Includes time zone data,
                time zone conversions and many date/time
                It does not rely on 32-bit system date stamps,
                you can display calendars and compare dates
                that date
                pre 1970 and post 2038. This package also
                provides a class
                to convert date strings between Gregorian and
                Human calendar formats.
Maintainers     Baba Buehler <baba@babaz.com> (lead)
                Monte Ohrt <mohrt@php.net> (lead)
                Pierre-Alain Joye <pajoye@pearfr.org> (lead)
                Alan Knowles <alan@akbkhome.com> (developer)
Version         1.4.3
Release Date    2004-05-16
Release License PHP License
Release State   stable
Release Notes   - Fix #1250 Wrong name for Bangladesh TZ
                - Fix #1390, add XML Schema datetime support
                  (aashley at optimiser dot com)
Release Deps    PHP >= 4.2
Last Modified   2005-02-19

Although the information that the info command output is also available on the PEAR web site, it is much easier to find here!

Upgrading Existing Packages

The section, "Listing Packages," showed you how to list all packages that require upgrading by using the list-upgrades command. After determining that a package needs updating, you use the upgrade command:

C:\PHP> pear upgrade Date

When you do this, the latest version downloads and is made ready to work for you. Note that although one of the requirements for entering classes into PEAR is that they be backward (and forward) compatible with other versions, you should always test new versions as much as possible to ensure that nothing subtle has changed that might break your web application.

To upgrade all out-of-date packages on your machine, just execute the following:

phpsrvr:~ # pear upgrade-all

Uninstalling Packages

Removing packages from your system is as easy as pear uninstall:

C:\PHP> pear uninstall date
uninstall ok: Date

If a package has other packages that depend on it, PEAR does not uninstall the package unless you specify the -n or --nodeps flag, which tells it to ignore dependencies (and let them break).

Configuration Options for PEAR

You can also use the pear command to configure PEAR. To see your current settings, execute pear config-show, as follows:

phpsrvr:~ # pear config-show
PEAR executables directory     bin_dir         /usr/local/bin
PEAR documentation directory   doc_dir         /usr/local/lib/php/doc
PHP extension directory        ext_dir         /usr/local/lib/php/...
PEAR directory                 php_dir         /usr/local/lib/php
PEAR Installer cache directory cache_dir       /tmp/pear/cache
PEAR data directory            data_dir        /usr/local/lib/php/data
PHP CLI/CGI binary             php_bin         /usr/local/bin/php
PEAR test directory            test_dir        /usr/local/lib/php/test
Cache TimeToLive               cache_ttl       3600
Preferred Package State        preferred_state stable
Unix file mask                 umask           22
Debug Log Level                verbose         1
HTTP Proxy Server Address      http_proxy      <not set>
PEAR server                    master_server   pear.php.net
PEAR password (for             password        <not set>
Signature Handling Program     sig_bin         /usr/local/bin/gpg
Signature Key Directory        sig_keydir      /usr/local/etc/pearkeys
Signature Key Id               sig_keyid       <not set>
Package Signature Type         sig_type        gpg
PEAR username (for             username        <not set>

To inspect any of these values individually, use the config-get command:

phpsrvr:~ # pear config-get preferred_state

The previous line shows that PEAR is configured to prefer packages marked as stable when you ask to download and install them. If you choose another value, such as beta, then only releases with that quality level or better are downloaded. You can set any individual setting by using the config-set command, as follows:

phpsrvr:~ # pear config-set preferred_state beta

Table of Contents
© 2000- NIV