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.
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:
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.
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.
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.