Section 10.5. Configuration Parameters

10.5. Configuration Parameters

The different installer front-ends differ only in their user-interface specific parts; the core, executing part of each command, is shared between all front-ends. Their configuration parameters are also common; the documentation base directory used in the command-line installation is the same one used by the Gtk installer, and so on.

The PEAR Installer has many configuration parameters, only some of which you need to worry about right now. Look at the PEAR main directory parameter and the other directory parameters first.

Next is the complete list of configuration parameters in the PEAR Installer (see Table 10.4). This is close to what you see when running the pear config-show command.

Table 10.4. PEAR Configuration Parameters

Configuration Parameter	Variable Name	Example Value
PEAR main directory	php_dir	/usr/share/pear
PEAR executables directory	bin_dir	/usr/bin
PEAR documentation directory	doc_dir	/usr/share/pear/docs
PHP extension directory	ext_dir	/usr/lib/php/20010901
PEAR Installer cache directory	cache_dir	/tmp/pear/cache
PEAR data directory	data_dir	/usr/share/pear/data
PEAR test directory	test_dir	/usr/share/pear/tests
Cache TimeToLive	cache_ttl	not set
Preferred Package State	preferred_state	alpha
UNIX file mask	umask	022
Debug Log Level	verbose	1
HTTP Proxy Server Address	http_proxy	not set
PEAR server	master_server	pear.php.net
PEAR password (for maintainers)	password	not set
PEAR user name (for maintainers)	username	not set
Package Signature Type	sig_type	gpg
Signature Handling Program	sig_bin	/usr/bin/gpg
Signature Key Directory	sig_keydir	/usr/etc/pearkeys
Signature Key Id	sig_keyid	not set

The various directory parameters are base directories for installation of different file types, such as PHP code, dynamically loadable extensions, documentation, scripts, programs, and regression tests. Some of these were mentioned in the previous go-pear section, but here is the full list:

• PEAR main directory (php_dir). Directory where the PHP include files are stored, as well as PEAR's internal administration files to keep track of installed packages. If you change this configuration parameter, the installer will no longer "find" the packages you installed there. This feature makes it possible to maintain several PEAR installations on the same machine. The default value for this parameter is /usr/local/lib/php.

• PEAR executables directory (bin_dir). Directory where, executable scripts and programs are installed. For example, the pear command itself is installed here. The default value for this parameter is /usr/local/bin.

• PEAR documentation directory (doc_dir). Directory where documentation files are installed. Directly beneath the doc_dir is a directory named after the package, containing all the documentation files installed with the package. The default value of this parameter is /usr/local/lib/php/docs.

• PHP extension directory (ext_dir). Directory where all PHP extensions that are built during install end up. Make sure you set extension_dir to this directory in your php.ini file. The default value for this parameter is /usr/local/lib/php/extensions/BUILDSPEC, where BUILDSPEC is comprised of Zend's module API version and whether PHP was built with ZTS (Zend thread safety) and debugging. For example, BUILDSPEC would be 20020429 for the API released April 29, 2002, without ZTS and debug.

• PEAR installer cache directory (cache_dir). Directory where the installer may store caching data. This local caching is used to speed up repeated XML-RPC calls to the central server.

• PEAR data directory (data_dir). Directory that stores files that are neither code, regression tests, executables, nor documentation. Typical candidates for "data files" are DTD files, XSL stylesheets, offline template files, and so on.

• Cache TimeToLive (cache_ttl). The number of seconds cached XML-RPC calls should be stored before invalidated. Set this to a value larger than 0 to enable caching of XML-RPC method calls; this speeds up remote operations.

• Preferred Package Stage (preferred_state). Parameter that enables you to set the quality you expect from a package release before you even see it. There are five states to choose from: stable (production code), beta, alpha, snapshot, and devel. The installer perceives the quality of a release as highest with "stable" and lowest with "devel," and shows you releases of the preferred state or better. This means that if you set your preferred state to "stable," you only see stable releases when browsing the package database. However, if you set preferred state to "alpha," you see alpha as well as beta and stable-state releases.

• Unix file mask (umask). Parameter used to determine the default file permissions for new files on UNIX-style systems. The umask tells which file permission bits will be masked away.

• Debug Log Level (verbose). The default debug log level that says how many -v command-line options are used by default. The recommended value is 1, which is informational. A value of 2 shows some details about what the installer is doing. A value of 3 or greater is for debugging the installer.

• HTTP Proxy Server (http_proxy). You can set this configuration parameter to make the PEAR Installer always use a web proxy. You specify the proxy as host:port or http://host:port. If your proxy requires authorization, specify it as http://user:pw@host:port.

• PEAR Server (master_server). The hostname of the package registry server. Registry queries and downloads are all proxied through this server.

• PEAR username / PEAR password (username / password). For commands that require authorization, you must log in first with the login command. When you log in, your username and password are stored in these two configuration parameters (maintainers only).

• Signature Type (sig_type). What type of signature tool to use when adding signing packages (maintainers only).

• Signature Handling Program (sig_bin). The path of the executable used to handle signatures (maintainers only).

• Signature Key Directory (sig_keydir). The directory where PHP/PEAR-specific public and private keys are stored (maintainers only).

• Signature Key Id (sig_keyid). The key id that is used when signing packages. If this configuration parameter is not set, the default is left to the Signature Handling Program (maintainers only).

Configuration Layers

Each configuration parameter may be defined in three locations, called layers: a user's private configuration file (the user layer), the system-wide configuration file (the system layer), and built-in defaults (the default layer). When you run the installer and it needs to look up some configuration parameter, it will check the user layer first. If the parameter is not user-defined, it checks the system layer. If it was not found in the system configuration either, the default layer is used. The default layer has a built-in default value for every configuration parameter.

To see the value of a single configuration parameter, use the pear config-get command. Here is the built-in help text and some usage examples:

 $ pear help config-get pear config-get <parameter> [layer] Displays the value of one configuration parameter.  The first  argument is the name of the parameter, an otional second argument may  be used to tell which configuration layer to look in.  Valid  configuration layers are "user", "system" and "default".  If no layer  is specified, a value will be picked from the first layer that defines the parameter, in the order just specified. 

(When reading the first line of the pear help output, it's useful to know that <foo> means that foo is a required argument, while [bar] means bar is optional.)

So, with config-get you may specify the layer. If you don't, it will pick the value from the highest-precedence layer that defines it. Now, for some examples:

 $ pear config-get verbose verbose=1 $ pear config-get verbose user user.verbose=1 $ pear config-get verbose system system.verbose= $ pear config-get verbose default default.verbose=1 

As you can see, the verbose configuration parameter is set both in the user and default layer. That means it is the user-specified parameter that takes effect. It is possible to clear a user- or system-specified value with the -u option to the installer:

 $ pear u verbose -s $ pear config-get verbose verbose=1 $ pear config-get verbose user user.verbose= $ pear config-get verbose system system.verbose= $ pear config-get verbose default default.verbose=1 

Changing the Configuration

To change a configuration parameter, you can use either pear config-set or pear d. Here's the help text for config-set:

 $ pear help config-set pear config-set <parameter> <value> [layer] Sets the value of one configuration parameter.  The first argument is the name of the parameter, the second argument is the new value. Some parameters are subject to validation, and the command will fail  with an error message if the new value does not make sense.  An  optional third argument may be used to specify which layer to set the  configuration parameter in.  The default layer is "user". 

Actually, this command

 $ pear config-set foo bar 

is equivalent to

 $ pear d foo=bar -s 

The difference between pear config-set and pear d is that the effect of config-set applies permanently from the next command, while d applies only to the current command.

Tip

If you want to have parallel PEAR installations, (for instance, one in which to test-install your own packages), define a shell alias to something like pear c test-pear.conf, and set the different directory parameters in this configuration only.

Before you change everything, you should be aware that the PEAR main directory configuration parameter (php_dir) has a special function. The list of installed packages database lives there in a subdirectory called .registry. If you change php_dir, you will not see the packages installed in the old php_dir anymore. Here's an example:

 $ pear config-get php_dir php_dir=/usr/local/lib/php $ pear list Installed packages: =============== Package           Version    State Archive_Tar       0.9        stable Console_Getopt    1.0        stable DB                1.3        stable Mail              1.0.1      stable Net_SMTP          1.0        stable Net_Socket        1.0.1      stable PEAR              1.0b2      stable XML_Parser        1.0        stable XML_RPC           1.0.4      stable 

So, PEAR PHP files are installed in /usr/local/lib/php, and you have just the core packages provided by the go-pear install. Now, try changing php_dir:

 $ pear config-set php_dir /usr/share/pear $ pear list (no packages installed) 

There's no reason to panicyour packages are still in /usr/local/lib/php, but the installer doesn't see them now. How do you get the old php_dir setting back? In addition to the pear config-set command, the pear command has some options where you can set individual configuration parameters only for one run, permanently, or unset a parameter in a specific layer.

You may return to the old setting by setting it explicitly like this:

 $ pear config-set php_dir /usr/local/lib/php 

But to demonstrate the flexibility of configuration layers, you can simply unset php_dir from the user configuration layer instead:

 $ pear u php_dir s $ pear list Installed packages: =============== Package           Version    State Archive_Tar       0.9        stable Console_Getopt    1.0        stable DB                1.3        stable Mail              1.0.1      stable Net_SMTP          1.0        stable Net_Socket        1.0.1      stable PEAR              1.0b2      stable XML_Parser        1.0        stable XML_RPC           1.0.4      stable 

Your packages are back! The -u php_dir option makes pear delete php_dir from the (u)ser layer for this run, while the -s option makes configuration changes to the user layer permanent. Effectively, this reverts php_dir to the value it has in the "system" layer.

If you would just like to set a configuration value for a single run of the pear command, here is how:

 $ pear d preferred_state=alpha remote-list 

This sets the preferred_state configuration parameter to alpha (in the user layer, if you care to know) for this command. What this command does is show you package and releases of stable, beta, and alpha quality from pear.php.net. By default, you will only see stable releases.

There are three places where each configuration parameter may be defined. First, the installer looks at the user's local configuration (~/.pearrc on UNIX, pear.ini in the System directory on Windows). If the requested parameter was found in the user configuration, that value is returned. If not, the installer proceeds to the system-wide configuration file (/etc/pear.conf on UNIX, pearsys.ini in the System directory on Windows). If that fails as well, a default built-in value is used.

For the two example settings in Table 10.5, php_dir and preferred_state, PEAR looks for a value starting on the first row (the user layer) going down until a value exists. In this example, the php_dir setting resolves to /usr/local/lib/php, which is the default. The preferred_state setting resolves to beta, because this is the value set in the user layer.

Table 10.5.

Config Layer	php_dir setting	preferred_state setting
User	(not set)	beta
System	(not set)	(not set)
Default	/usr/local/lib/php	stable

The content of the configuration files is serialized PHP data, which is not for the faint of heart to read or edit. If you edit it directly and make a mistake, you lose the entire layer upon saving it again, so stick to the pear command.