Basic CommandsThis 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 HelpTo 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 PackagesTo 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 PackagesThe 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 InformationTo 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 <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)
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 PackagesThe 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 PackagesRemoving 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 PEARYou 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 |