Section 10.6. PEAR Commands


10.6. PEAR Commands

In this section, you learn all the PEAR Installer commands for installation and maintenance of packages on your system. For each of the commands, you will have the output of pear help command, and a thorough explanation of every option the command offers. If you notice commands mentioned in some of the help text that you do not find covered here, those commands are used by PEAR package maintaners during development. The development commands are covered in Chapter 12.

10.6.1. pear install

This command takes the content of a package file and installs files in your designated PEAR directories. You may specify the package to install as a local file, just the package name or as a full HTTP URL. Here's the help text for pear install:

 $ pear help install pear install [options] <package> ... Installs one or more PEAR packages.  You can specify a package to install in four ways: "Package-1.0.tgz" : installs from a local file "http://example.com/Package-1.0.tgz" : installs from anywhere on the net. "package.xml" : installs the package described in package.xml.  Useful for testing, or for wrapping a PEAR package in another package manager such as RPM. "Package" : queries your configured server (pear.php.net) and downloads the newest package with the preferred quality/state (stable). More than one package may be specified at once.  It is ok to mix  these four ways of specifying packages. Options:   -f, --force     will overwrite newer installed packages 

The -force option lets you install the package even if the same release or a newer release is already installed. This is useful for repairing broken installs, or during testing.

 -n, --nodeps   ignore dependencies, install anyway 

Use this option to ignore dependencies and pretend that they are already installed. Use it only if you understand the consequences, the installed package may not work at all.

 -r, --register-only   do not install files, only register the package as installed 

The -register-only option makes the installer list your package as installed, but it does not actually install any files. The purpose of this is to make it possible for non-PEAR package managers to also register packages as installed in the PEAR package registry. For example, if you install DB (the PEAR database layer) with an RPM, all the files are installed and you can use it, but the pear list command does not show that it is installed because RPM does not (by default) update the PEAR package registry. But, if the RPM package has a post-install command that runs pear -register-only package.xm, the package will be registered, both from RPM's and PEAR's point of view.

 -s, --soft   soft install, fail silently, or upgrade if already installed 

This option is another way of saying, "Please give me the latest version of this package." If the package is not installed already, it will be installed. If the package is installed but you are specifying a package tarball with a newer package, or the latest online version is newer, the package will be upgraded. The difference between pear install -s and pear upgrade is that upgrade upgrades only if the package is already installed.

 -B, --nobuild   don't build C extensions 

If you are installing a package that is a mix of PHP and C code and don't want to build and install the C code, or you simply want to test-install a package with C code, use -nobuild.

 -Z, --nocompress   request uncompressed files when downloading 

If your PHP build does not include the zlib extension, PHP cannot uncompress gzipped package files. The installer detects this automatically, and will download non-gzipped packages when necessary. But, if this detection doesn't work, you can override it with the -nocompres option.

 -R DIR, --installroot=DIR   root directory used when installing files (ala PHP's INSTALL_ROOT) 

This option is useful when you are installing PEAR packages from a script or using another package manager. All file names created by the installer will have DIR prepended.

 --ignore-errors   force install even if there were errors 

If there are errors in a package and the installer refuses to go ahead and install it, you can use the ignore-errors option to force installation. There is a risk of an inconsistent install when using this option, so use it with care!

 -a, --alldeps   install all required and optional dependencies 

Use this option to automatically download and install any dependencies.

 -o, --onlyreqdeps   install all required dependencies 

Some packages have optional dependencies, which means a dependency that exists to use optional features of the package. If you want to satisfy all the dependencies, but don't need the optional features, use this option.

Here are some examples of typical use. First, a plain example installing a package with no dependencies:

 $ pear install Console_Table downloading Console_Table-1.0.1.tgz ... Starting to download Console_Table-1.0.1.tgz (3,319 bytes) ....done: 3,319 bytes install ok: Console_Table 1.0.1 

Here is an example of installing a package with many optional dependencies, but pulling only the packages that are required:

 $ pear install o HTML_QuickForm downloading HTML_Progress-1.1.tgz ... Starting to download HTML_Progress-1.1.tgz (163,298 bytes) ...................................done: 163,298 bytes skipping Package 'html_progress' optional dependency 'HTML_CSS' skipping Package 'html_progress' optional dependency 'HTML_Page' skipping Package 'html_progress' optional dependency 'HTML_QuickForm' skipping Package 'html_progress' optional dependency  'HTML_QuickForm_Controller'skipping Package 'html_progress' optional  dependency 'Config' downloading HTML_Common-1.2.1.tgz ... Starting to download HTML_Common-1.2.1.tgz (3,637 bytes) ...done: 3,637 bytes install ok: HTML_Common 1.2.1 Optional dependencies: package 'HTML_CSS' version >= 0.3.1 is recommended to utilize some  features. package 'HTML_Page' version >= 2.0.0RC2 is recommended to utilize  some features.package 'HTML_QuickForm' version >= 3.1.1 is  recommended to utilize some features. package 'HTML_QuickForm_Controller' version >= 0.9.3 is recommended  to utilize some features. package 'Config' version >= 1.9 is recommended to utilize some  features. install ok: HTML_Progress 1.1 

Finally, this example installs a package and all dependencies, looking for releases of beta or better quality:

 $ pear d preferred_state=beta install a Services_Weather downloading Services_Weather-1.2.2.tgz ... Starting to download Services_Weather-1.2.2.tgz (29,205 bytes) .........done: 29,205 bytes 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.1.tgz ... Starting to download HTTP_Request-1.2.1.tgz (12,021 bytes) ...done: 12,021 bytes downloading SOAP-0.8RC3.tgz ... Starting to download SOAP-0.8RC3.tgz (67,608 bytes) ...done: 67,608 bytes downloading XML_Serializer-0.9.2.tgz ... Starting to download XML_Serializer-0.9.2.tgz (12,340 bytes) ...done: 12,340 bytes downloading Net_URL-1.0.11.tgz ... Starting to download Net_URL-1.0.11.tgz (4,474 bytes) ...done: 4,474 bytes downloading Mail_Mime-1.2.1.tgz ... Starting to download Mail_Mime-1.2.1.tgz (15,268 bytes) ...done: 15,268 bytes downloading Net_DIME-0.3.tgz ... Starting to download Net_DIME-0.3.tgz (6,740 bytes) ...done: 6,740 bytes downloading XML_Util-0.5.2.tgz ... Starting to download XML_Util-0.5.2.tgz (6,540 bytes) ...done: 6,540 bytes install ok: Mail_Mime 1.2.1 install ok: Net_DIME 0.3 install ok: XML_Util 0.5.2 install ok: Net_URL 1.0.11 install ok: XML_Serializer 0.9.2 install ok: HTTP_Request 1.2.1 install ok: Cache 1.5.4 install ok: SOAP 0.8RC3 install ok: Services_Weather 1.2.2 

10.6.2. pear list

The pear list command lists the contents of either your package registry or a single package. First, let's list the currently installed packages to see how the Date package is doing:

 INSTALLED PACKAGES: =================== PACKAGE          VERSION    STATE Archive_Tar      1.1        stable Cache            1.4        stable Console_Getopt   1.2        stable Console_Table    1.0.1      stable DB               1.6.3      stable Date             1.4.2      stable HTTP_Request     1.2.1      stable Log              1.2        stable Mail             1.1.2      stable Mail_Mime        1.2.1      stable Net_DIME         0.3        beta Net_SMTP         1.2.6      stable Net_Socket       1.0.2      stable Net_URL          1.0.11     stable PEAR             1.3.1      stable PHPUnit2         2.0.0beta1 beta SOAP             0.8RC3     beta XML_Parser       1.1.0      stable XML_RPC          1.1.0      stable XML_Serializer   0.9.2      beta XML_Util         0.5.2      stable 

To inspect the contents of the recently installed Date package, use the list command:

 $ pear list Net_Socket INSTALLED FILES FOR NET_SOCKET ============================== TYPE INSTALL PATH php  /usr/local/lib/php/Net/Socket.php 

This package contains only php files. The PEAR package contains different types of files. The following example also illustrates how "data" files are installed with the package name as part of the file path:

 $ pear list PEAR INSTALLED FILES FOR PEAR ======================== TYPE   INSTALL PATH data   /usr/local/lib/php/data/PEAR/package.dtd data   /usr/local/lib/php/data/PEAR/template.spec php    /usr/local/lib/php/PEAR.php php    /usr/local/lib/php/System.php php    /usr/local/lib/php/PEAR/Autoloader.php php    /usr/local/lib/php/PEAR/Command.php php    /usr/local/lib/php/PEAR/Command/Auth.php php    /usr/local/lib/php/PEAR/Command/Build.php php    /usr/local/lib/php/PEAR/Command/Common.php php    /usr/local/lib/php/PEAR/Command/Config.php php    /usr/local/lib/php/PEAR/Command/Install.php php    /usr/local/lib/php/PEAR/Command/Package.php php    /usr/local/lib/php/PEAR/Command/Registry.php php    /usr/local/lib/php/PEAR/Command/Remote.php php    /usr/local/lib/php/PEAR/Command/Mirror.php php    /usr/local/lib/php/PEAR/Common.php php    /usr/local/lib/php/PEAR/Config.php php    /usr/local/lib/php/PEAR/Dependency.php php    /usr/local/lib/php/PEAR/Downloader.php php    /usr/local/lib/php/PEAR/ErrorStack.php php    /usr/local/lib/php/PEAR/Frontend/CLI.php php    /usr/local/lib/php/PEAR/Builder.php php    /usr/local/lib/php/PEAR/Installer.php php    /usr/local/lib/php/PEAR/Packager.php php    /usr/local/lib/php/PEAR/Registry.php php    /usr/local/lib/php/PEAR/Remote.php php    /usr/local/lib/php/OS/Guess.php script /usr/local/bin/pear php    /usr/local/lib/php/pearcmd.php 

10.6.3. pear info

The pear info command displays information about an installed package, a package tarball, or a package definition (XML) file. This example shows the information about the XML-RPC package:

 $ pear info XML_RPC About XML_RPC-1.1.0 =================== Provides       Classes: Package         XML_RPC Summary         PHP implementation of the XML-RPC protocol Description     This is a PEAR-ified version of Useful inc's                 XML-RPC                 for PHP. It has support for HTTP transport,                 proxies and authentication. Maintainers     Stig S?ther Bakken <stig@php.net> (lead) Version         1.1.0 Release Date    2003-03-15 Release License PHP License Release State   stable Release Notes   - Added support for sequential arrays to                 XML_RPC_encode() (mroch)                 - Cleaned up new XML_RPC_encode() changes a bit                 (mroch, pierre)                 - Remove "require_once 'PEAR.php'", include                 only when needed to raise an error                 - Replace echo and error_log() with                 raiseError() (mroch)                 - Make all classes extend XML_RPC_Base, which                 will handle common functions  (mroch)                 - be tolerant of junk after methodResponse                 (Luca Mariano, mroch)                 - Silent notice even in the error log (pierre)                 - fix include of shared xml extension on win32                 (pierre) Last Modified   2004-05-03 

If you have downloaded a package file (.tgz file), you may also run pear info on it to display information about the contents without installing the package first; for example:

 $ pear info XML-RPC-1.1.0.tgz 

You can even specify a full URL to a package you want to view:

 $ pear info http://www.example.com/packages/Foo_Bar-4.2.tgz 

See also the remote-info command.

10.6.4. pear list-all

While pear list displays all the packages installed on your system, pear list-all displays an alphabetically sorted list of all packages with the latest stable version, and which version you have installed, if any. The full output of this command is long because it lists every package that has a stable release.

 ALL PACKAGES: ============= PACKAGE                   LATEST   LOCAL APC                       2.0.3 Cache                     1.5.4    1.4 Cache_Lite                1.3 apd                       0.4p2              ...truncated...      XML_Transformer           1.0.1 XML_Tree                  1.1 XML_Util                  0.5.2    0.5.2 PHPUnit2                           2.0.0beta1 Net_DIME                           0.3 XML_Serializer                     0.9.2 SOAP                               0.8RC3 

10.6.5. pear list-upgrades

The pear list-upgrades command compares the version you have installed containing the newest version with the release state you have configured (see the preferred_state configuration parameter). Here's an example:

 $ pear list-upgrades AVAILABLE UPGRADES (STABLE): ============================ PACKAGE LOCAL          REMOTE         SIZE Cache   1.4 (stable)   1.5.4 (stable) 30kB DB      1.6.3 (stable) 1.6.4 (stable) 90kB Log     1.2 (stable)   1.8.4 (stable) 29kB Mail    1.1.2 (stable) 1.1.3 (stable) 13.2kB 

The version listed here is not the one you have installed, but the one you will upgrade to if you use the upgrade command.

10.6.6. pear upgrade

The pear upgrade command replaces one or more installed packages with a newer release, if a newer release can be found. As with many other commands taking a package argument, you may refer to the package just by name, the URL or name of a tarball, or the URL or name of a package description (XML) file. This section only demonstrates specifying the package by name because that is by far the most common usage.

In the list-upgrades example, you saw a few packages where newer releases were available. Upgrade the Log package:

 $ pear upgrade Log downloading Log-1.8.4.tgz ... Starting to download Log-1.8.4.tgz (29,453 bytes) .........done: 29,453 bytes Optional dependencies: 'sqlite' PHP extension is recommended to utilize some features upgrade ok: Log 1.8.4 

The upgrade command has the same options as the install command, with the exception that the S / --soft option is missing. The options are listed here; refer to the install command, shown previously, for a more detailed description.

 $ pear help upgrade pear upgrade [options] <package> ... Upgrades one or more PEAR packages.  See documentation for the "install" command for ways to specify a package. When upgrading, your package will be updated if the provided new package has a higher version number (use the -f option if you need to upgrade anyway). More than one package may be specified at once. Options:   -f, --force         overwrite newer installed packages   -n, --nodeps         ignore dependencies, upgrade anyway   -r, --register-only         do not install files, only register the package as upgraded   -B, --nobuild         don't build C extensions   -Z, --nocompress         request uncompressed files when downloading   -R DIR, --installroot=DIR         root directory used when installing files (ala PHP's INSTALL_ROOT)   --ignore-errors         force install even if there were errors   -a, --alldeps         install all required and optional dependencies   -o, --onlyreqdeps         install all required dependencies 

10.6.7. pear upgrade-all

For your convenience, the upgrade-all command provides a combination of the list-upgrades and upgrade commands, upgrading every package that has a newer release available.

The command-line options available are

 -n, --nodeps       ignore dependencies, upgrade anyway -r, --register-only       do not install files, only register the package as upgraded -B, --nobuild       don't build C extensions -Z, --nocompress       request uncompressed files when downloading -R DIR, --installroot=DIR       root directory used when installing files (ala PHP's INSTALL_ROOT) --ignore-errors       force install even if there were errors 

See the install command for a description of each of these options.

If you have followed the examples in this chapter, you have still not upgraded three out of the four packages that list-upgrades reported as having newer releases. Upgrade them all at once like this:

 $ pear upgrade-all Will upgrade cache Will upgrade db Will upgrade mail downloading Cache-1.5.4.tgz ... Starting to download Cache-1.5.4.tgz (30,690 bytes) .........done: 30,690 bytes downloading DB-1.6.4.tgz ... Starting to download DB-1.6.4.tgz (91,722 bytes) ...done: 91,722 bytes downloading Mail-1.1.3.tgz ... Starting to download Mail-1.1.3.tgz (13,415 bytes) ...done: 13,415 bytes upgrade-all ok: Mail 1.1.3 upgrade-all ok: DB 1.6.4 upgrade-all ok: Cache 1.5.4 Optional dependencies: 'sqlite' PHP extension is recommended to utilize some features upgrade-all ok: Log 1.8.4 

10.6.8. pear uninstall

To delete a package, you must uninstall it. Here's an example:

 $ pear uninstall Cache Warning: Package 'services_weather' optionally depends on 'Cache' uninstall ok: Cache 

The uninstall command has three options:

 pear uninstall [options] <package> ... Uninstalls one or more PEAR packages.  More than one package may be specified at once. Options:   -n, --nodeps         ignore dependencies, uninstall anyway   -r, --register-only         do not remove files, only register the packages as not installed   -R DIR, --installroot=DIR         root directory used when installing files (ala PHP's INSTALL_ROOT)           --ignore-errors         force install even if there were errors 

These options all correspond to the same options to the install command.

10.6.9. pear search

If you want to install a package but don't remember what it was called, or just wonder if there is a package that does X, you can search for it with the pear search command, which does a substring search in package names. Here's an example:

 $ pear search xml MATCHED PACKAGES: ================= PACKAGE         LATEST LOCAL XML_Beautifier  1.1          Class to format XML documents. XML_CSSML       1.1          The PEAR::XML_CSSML package provides                              methods for creating cascading style                               sheets (CSS) from an XML standard                               called CSSML. XML_fo2pdf      0.98         Converts a xsl-fo file to pdf/ps/pcl                               text/etc with the help of apache-fop XML_HTMLSax     2.1.2        A SAX based parser for HTML and other                               badly formed XML documents XML_image2svg   0.1          Image to SVG conversion XML_NITF        1.0.0        Parse NITF documents. XML_Parser      1.1.0  1.1.0 XML parsing class based on PHP's bundled                               expat XML_RSS         0.9.2        RSS parser XML_SVG         0.0.3        XML_SVG API XML_Transformer 1.0.1        XML Transformations in PHP XML_Tree        1.1          Represent XML data in a tree structure XML_Util        0.5.2  0.5.2 XML utility class. XML_RPC         1.1.0  1.1.0 PHP implementation of the XML-RPC                               protocol 

The output is displayed in four columns: package name, latest version available online, locally installed version (or blank if you do not have that package installed), and a short description.

10.6.10. pear remote-list

This command displays a list of all packages and stable releases that are available in the package repository:

 $ pear remote-list AVAILABLE PACKAGES: =================== PACKAGE                   VERSION APC                       2.0.3 apd                       0.4p2 Archive_Tar               1.1 Auth                      1.2.3 Auth_HTTP                 2.0 Auth_PrefManager          1.1.2 Auth_RADIUS               1.0.4 Auth_SASL                 1.0.1 Benchmark                 1.2.1 bz2                       1.0 Cache                     1.5.4 ... 

The difference from list-all is that remote-list only shows the last available version, while list-all also shows which releases you have installed.

This command obeys your preferred_state configuration setting, which defaults to stable. All the packages and releases in the output of the previous example are tagged as stable.

You may temporarily set preferred_state for just one command. The following example shows all packages that are of alpha quality or better:

 $ pear d preferred_state=alpha remote-list AVAILABLE PACKAGES: =================== PACKAGE                    VERSION APC                        2.0.3 apd                        0.4p2 Archive_Tar                1.1 Archive_Zip                0 Auth                       1.2.3 Auth_Enterprise            0 Auth_HTTP                  2.1.0RC2 Auth_PrefManager           1.1.2 Auth_RADIUS                1.0.4 Auth_SASL                  1.0.1 bcompiler                  0.5 Benchmark                  1.2.1 bz2                        1.0 ... 

As you can see, some new packages showed up: Archive_Zip, and Auth_Enterprise (which did not have any releases at all at this point), and bcompiler 0.5.

10.6.11. pear remote-info

To display detailed information about a package you have not installed, use the pear remote-info command.

 $ pear remote-info apc PACKAGE DETAILS: ================ Latest      2.0 Installed   - no - ackage     APC License     PHP Category    Caching Summary     Alternative PHP Cache Description APC is the Alternative PHP Cache. It was             conceived of to provide a free, open, and             robust framework for caching and optimizing PHP             intermediate code. 

The package description shown by the remote-info command is taken from the newest release of the package.

10.6.12. pear download

The pear install command does not store the package file it downloads anywhere. If all you want is the package tarball (for installing later or something else), you can use the pear download command:

 $ pear download DB File DB-1.3.tgz downloaded (59332 bytes) 

By default, you will receive the latest release matching your preferred_state configuration parameter. If you want to download a specific release, give the full file name instead:

 $ pear download DB-1.2.tgz File DB-1.2.tgz downloaded (58090 bytes) 

Tip

If you don't have the zlib PHP extension built in, use the -Z or --nocompress option to download .tar files.


10.6.13. pear config-get

As you have already seen, the pear config-get command is used to display a configuration parameter:

 $ pear config-get php_dir php_dir=/usr/share/pear 

If you do not specify a layer, the value is read from the first layer that defines it (in the order user, system, default). You may also specify a specific configuration layer from where you want to get the value:

 $ pear config-get http_proxy system system.http_proxy=proxy.example.com:3128 

10.6.14. pear config-set

The pear config-set command changes a configuration parameter:

 $ pear config-set preferred_state beta 

By default, the change is performed in the user configuration layer. You may specify the configuration layer with an additional parameter:

 $ pear config-set preferred_state beta system 

(You need write access to the system configuration file for this to have any effect.)

10.6.15. pear config-show

The pear config-show command is used to display all configuration settings, treating layers just like the config-get command.

 $ 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/   extensions/no-debug-non-zts-20040316 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/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) 

Tip

By adding an extra parameter (user or system), you can view the contents of a specific configuration layer.


10.6.16. Shortcuts

Every command in the PEAR Installer may specify a command-line shortcut, just to save people from typing. Type pear help shortcuts to see them:

 $ pear help shortcuts Shortcuts:      li       login      lo       logout      b        build      csh      config-show      cg       config-get      cs       config-set      ch       config-help      i        install      up       upgrade      ua       upgrade-all      un       uninstall      bun      bundle      p        package      pv       package-validate      cd       cvsdiff      ct       cvstag      rt       run-tests      pd       package-dependencies      si       sign      rpm      makerpm      l        list      st       shell-test      in       info      ri       remote-info      lu       list-upgrades      rl       remote-list      sp       search      la       list-all      d        download      cc       clear-cache      da       download-all 

Instead of pear config-set foo=bar, you may type pear cs foo=bar, or pear pd instead of pear package-dependencies.



    PHP 5 Power Programming
    PHP 5 Power Programming
    ISBN: 013147149X
    EAN: 2147483647
    Year: 2003
    Pages: 240

    Similar book on Amazon

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net