10.4. Installing Packages

This section covers how to maintain your collection of installed packages. The following examples all assume that you have the PEAR Installer installed and configured.

The PEAR Installer comes with different user interfaces, called front-ends. The default front-end that is installed by go-pear along with PHP is the command-line (CLI) front-end. You will see a presentation of two graphical front-ends too, one that is browser-based and one that is Gtk-based.

10.4.1. Using the pear Command

The pear command is the main installation tool for PEAR. It has several sub-commands, such as install and upgrade, and runs on all platforms PEAR supports: UNIX, Windows, and Darwin.

The first subcommand you should be familiar with is help. pear help sub-command will display a short help text and lists all the command-line options for that subcommand. pear help displays a list of subcommands. This is what the output looks like:

$ pear help
Usage: pear [options] command [command-options] <parameters>
Type "pear help options" to list all options.
Type "pear help <command>" to get the help for the specified command.
Commands:
build                  Build an Extension From C Source 
bundle                 Unpacks a PECL package
clear-cache            Clear XML-RPC Cache
config-get             Show One Setting
config-help            Show Information About Setting
config-set             Change Setting
config-show            Show All Settings
cvsdiff                Run a "cvs diff" for all files in a package
cvstag                 Set CVS Release Tag
download               Download Package
download-all           Downloads every package from {config master_server}
info                   Display information about a package
install                Install Package
list                   List Installed Packages
list-all               List All Packages
list-upgrades          List Available Upgrades
login                  Connects and authenticates to remote server
logout                 Logs out from the remote server
makerpm                Builds an RPM package from a PEAR package
package                Build Package
package-dependencies   Show package dependencies
package-validate       Validate Package Consistency
remote-info            Information About Remote Packages
remote-list            List Remote Packages
run-tests              Run Regression Tests
search                 Search remote package database
shell-test             Shell Script Test
sign                   Sign a package distribution file
uninstall              Un-install Package
upgrade                Upgrade Package
upgrade-all            Upgrade All Packages

10.4.1.1 Options

Command-line options (such as n or --nodeps) may be specified to both the pear command itself, and to the subcommand. The syntax is like this:

pear [options] sub-command [sub-command options] [sub-command arguments]

To list the options for the pear command itself ([options] as shown earlier), type pear help options:

$ pear help options
Options:
     -v         increase verbosity level (default 1)
     -q         be quiet, decrease verbosity level
     -c file    find user configuration in 'file'
     -C file    find system configuration in 'file'
     -d foo=bar set user config variable 'foo' to 'bar'
     -D foo=bar set system config variable 'foo' to 'bar'
     -G         start in graphical (Gtk) mode
     -s         store user configuration
     -S         store system configuration
     -u foo     unset 'foo' in the user configuration
     -h, -?     display help/usage (this message)
     -V         version information

All these options are optional and may always be specified regardless of what subcommand is used. Let's go through them one by one.

Option: -V

"V" is for "verbose." This option increases the installer's verbosity level for this command. The verbosity level is stored in the verbose configuration parameter, so unless you specify the s option, the verbosity is increased only for this execution. The PEAR Installer has four verbosity levels:

• 0. Really silent.

• 1. Informational messages.

• 2. Trace messages.

• 3. Debug output.

Here's an example:

$ pear v install Auth
+ tmp dir created at /tmp/tmpAR6ABu
downloading Auth-1.1.1.tgz ...
...done: 11,005 bytes
+ tmp dir created at /tmp/tmp4BPB6x
installed: /usr/share/pear/Auth/Auth.php
installed: /usr/share/pear/Auth/Container.php
+ create dir /usr/share/pear/docs/Auth
installed: /usr/share/pear/docs/Auth/README.Auth
+ create dir /usr/share/pear/Auth/Container
installed: /usr/share/pear/Auth/Container/DB.php
installed: /usr/share/pear/Auth/Container/File.php
installed: /usr/share/pear/Auth/Container/LDAP.php
install ok: Auth 1.1.1

This option may be repeated to increase the verbosity even more.

Option: -q

"Q" is for "quiet." This option is just like the v option except that it reduces the verbosity level.

Option: -c / -C

"C" is for "configuration file." This option is used to specify the configuration file to use for the user configuration layer. Configuration layers are described in the "Configuration Parameters" section. The C option does the same thing for the system configuration layer.

This option can be useful, for example, if you want to maintain a test area for PEAR packages by having separate directories for php_dir & company, and simply switching configurations by using the c option.

Here's an example:

$ pear c ~/.pearrc.test list

If combined with the s or S options, the configuration will be saved to the file specified with the c or C option.

Option: -d / -D

"D" is for "define." The d option sets a configuration parameter for this command. This is a volatile configuration change; the change only applies to the current command. The D variation does the same thing, except it changes the system configuration layer (more on layers in the next section). Here's an example:

$ pear d http_proxy=proxy.example.com:3128 remote-list

Again, combined with the s option, the configuration parameter changed with the d option is stored and becomes permanent, as will the S option for configuration parameters changed with the D option.

Option: -G

"G" is for "Gtk" or "graphical," if you prefer. This option starts the PEAR Installer with the Gtk front-end. You need to have php-gtk and the PEAR_Frontend_Gtk packages installed. You can try that out later in this chapter.

Option: -s / -S

"S" is for "store configuration," and causes the pear command to store any volatile configuration changes you made with the d option. The uppercase and lowercase versions of this option have the same function but for different configuration layers. You learn about configuration layers in the next section; until then, keep in mind that the s option is for the user layer, and the S option is for the system layer. All configuration changes are stored, including verbosity level if you changed that with the v or q option.

Option: -u

"U" is for "unset." This option is for removing the definition of a configuration parameter from the user configuration layer. The purpose of this is to revert that parameter to the system-specified value easily. You do not have to worry about what the old value was, unless the system layer has changed in the meantime; it will still be there, and will be used when the user configuration is unset.

By default, the effect of this option lasts only for one execution; combine it with the s option to make it permanent.

Option: -h

"H" is for "help." It does the same thing as both pear help or just pear.

Option: -V

"V" is for "version." This option makes the pear command just display version information and exit.