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 ALL PACKAGES: ============= 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 ABOUT DATE-1.4.3 ================ 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                 timestamps,                 which is a huge limitation for php programs.                 Includes time zone data,                 time zone conversions and many date/time                 conversions.                 It does not rely on 32-bit system date stamps,                 so                 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 <[e-mail]> (lead)                 Monte Ohrt <[e-mail]> (lead)                 Pierre-Alain Joye <[e-mail]> (lead)                 Alan Knowles <[e-mail]> (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)                   See                 http://www.w3.org/TR/2004/PER-xmlschema-2-20040318/#dateTime 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 CONFIGURATION: ============== 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> maintainers) 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> maintainers) 

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

 phpsrvr:~ # pear config-get preferred_state stable 

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