Manual :: Pyrus user configuration variables

Introduction

The user configuration file is always stored in the user's personal directory, the home directory on unix, and My Documents on Windows. For a unix user with username user, the user configuration file is stored in /home/user/.pear/pearconfig.xml. For a Windows user, the configuration is stored in My Documents\pear\pearconfig.xml. The file is saved in XML format and can be hand-edited if necessary.

Unlike the system configuration file, the user configuration file is always saved when an operation that writes to disk is called, such as installing a package. On startup, Pyrus uses the configuration file's existence to determine whether it is being executed for the first time, and if so, prompts the user to initialize a few default settings such as the PEAR path.

There are two kinds of user configuration variables, installation-wide variables such as verbose, and channel-specific variables such as openssl_cert. Channel-specific variables can have different values for different channels. This allows setting a different certificate for each channel, for instance. The channel name is used as a tag, with non-XML friendly characters translated into simple mnemonics (such as . becoming DOT).

Here is a sample user configuration file (with line breaks added for readability):

<?xml version="1.0"?>
<pearconfig version="1.0">
 <default_channel>pear2.php.net</default_channel>
 <auto_discover>0</auto_discover>
 <http_proxy></http_proxy>
 <cache_dir>/home/user/testpear/cache</cache_dir>
 <temp_dir>/home/user/testpear/temp</temp_dir>
 <verbose>1</verbose>
 <paranoia>2</paranoia>
 <preferred_state>stable</preferred_state>
 <umask>0022</umask>
 <cache_ttl>3600</cache_ttl>
 <my_pear_path>/home/user/testpear:/usr/local/lib/php</my_pear_path>
 <plugins_dir>/home/user/.pear</plugins_dir>
 <openssl_cert>
  <pear2DOTphpDOTnet>/home/user/mykey.p12</pear2DOTphpDOTnet>
 </openssl_cert>
 <handle>
  <pear2DOTphpDOTnet>cellog</pear2DOTphpDOTnet>
 </handle>
</pearconfig>

auto_discover

Introduction

auto_discover is a flag (boolean), defaulting to 0 or off. If on, this flag instructs Pyrus to automatically discover channels of dependencies (see channel-discover for a more in-depth description of what channel discovery means).

For example, let's say we are installing Package foo from channel pear2.php.net, and that foo depends on package bar from channel pear.example.com. If Pyrus does not know the pear.example.com channel, and auto_discover is set to 1, it will attempt to discover information on the channel, and after successfully adding its information to the registry, will then successfully download and install the dependency bar. However, if auto_discover is disabled, Pyrus will simply fail with an error explaining that nothing is known about the pear.example.com channel, and that it must be added prior to installation.

cache_dir

Introduction

cache_dir is the location where HTTP caching of PEAR channel REST files is cached.

cache_ttl

Introduction

the cache_ttl configuration variable is used to determine when to consider the PEAR Channel REST cache to have been invalidated. It is measured in seconds, and by default is 3600, or 1 hour.

default_channel

Introduction

The default channel is the channel that should be implied when an Abstract Package is ambiguous. By default, it is pear2.php.net.

As an example, when executing:

php pyrus.phar install PEAR2_HTTP_Request

The abstract package PEAR2_HTTP_Request is ambiguous - it does not specify a channel. Pyrus assumes, therefore, that the requested package is from the default channel, and acts as if the user had in fact typed:

php pyrus.phar install pear2.php.net/PEAR2_HTTP_Request

The default_channel value is also used for all channel-specific configuration values.

download_dir

Introduction

This is a channel-specific configuration value

The download_dir is where downloaded packages are kept. This can allow later repairing or easy cloning of an installation. There is no penalty if the files are removed, and they may be easily removed to conserve space.

handle

Introduction

This is a channel-specific configuration value

The handle variable should be set to the handle you use to identify yourself in the <maintainers> section of package.xml for packages in a specific channel.

For example, if your <maintainer> entry in package.xml is:

 <lead>
  <name>Greg Beaver</name>
  <user>cellog</user>
  <email>cellog@php.net</email>
  <active>no</active>
 </lead>

Your handle is cellog.

This configuration variable is used in conjunction with the openssl_cert configuration variable to implement package signing.

http_proxy

Introduction

The http_proxy configuration variable should be set to the full URI of your local HTTP proxy, or left blank for none.

my_pear_path

Introduction

The my_pear_path configuration value controls the order in which Pyrus cascades PEAR installations. The path should have the same syntax as include_path, a PATH_SEPARATOR-separated list of full paths to PEAR installations. The my_pear_path configuration variable can be easily set with the mypear command.

Only the first path is considered to be read/write, the others are only used to validate package dependencies on download.

For instance, the my_pear_path /home/user/testpear:/usr/local/lib/php instructs Pyrus to install all packages into the PEAR installation at /home/user/testpear, and to also use the PEAR installation in /usr/local/lib/php to validate dependencies.

On Windows, an example my_pear_path is D:\customPear;C:\php5.

openssl_cert

Introduction

This is a channel-specific configuration value

The openssl_cert configuration variable should be set to the full path to your personal PKCS#12 certificate, as signed by a recognized certificate authority such as CACert. Pyrus uses this certificate along with your handle to implement package signing.

Your certificate must have the email address you use in package.xml as its alternate name, otherwise Pyrus will refuse to use it. Pyrus uses the email address as stated in package.xml of the releasing maintainer of a package to verify that the package was actually created by the maintainer. This makes a man-in-the-middle attack far more difficult to execute, as well as verifying package integrity.

password

Introduction

This is a channel-specific configuration value

This configuration variable is a legacy variable from PEAR, is not yet used in Pyrus, and may be removed before the stable release.

plugins_dir

Introduction

The plugins_dir directory is where all Pyrus plugins are installed. By default, it is the directory in which the user configuration file is stored.

preferred_mirror

Introduction

This is a channel-specific configuration value

This variable controls which mirror of a channel should be used to retrieve package releases and PEAR Channel REST information. By default, it is set to the main channel path.

preferred_state

Introduction

The preferred_state configuration variable controls the release stability level of packages that will be installed. By default it is stable, which instructs Pyrus to ignore any releases with lesser stabilities beta, alpha or devel unless explicitly requested by the user.

This can be changed to allow riskier installation of newer, less-tested releases that are on the cutting edge of development.

temp_dir

Introduction

The temp_dir configuration directive is where all temporary files are extracted by Pyrus.

umask

Introduction

The umask configuration value is used to control the default file mask used when setting file permissions. By default it is octal value 0022. The value is a bitmask that is used to clear any bits. Thus, a umask of 0000 will cause files to be installed with 0666 permissions. A umask of 0022 causes files to be installed with 0644 permissions.

username

Introduction

This is a channel-specific configuration value

This configuration variable is a legacy variable from PEAR, is not yet used in Pyrus, and may be removed before the stable release.

verbose

Introduction

The verbose setting controls how much information Pyrus echoes as it performs its task. The higher the setting, the more information Pyrus will spew. By default, it is set to 1.

verbose

Introduction

The paranoia setting controls how Pyrus handles automatic upgrades to new versions of packages. The API version of the installed package is compared against the API version of remote packages, and chooses a release that is compatible with the current version based on the paranoia level. This setting does not affect upgrades of local packages, only those retrieved from a remote PEAR channel server.

The paranoia setting is a numeric setting with levels 1 to 4 supported, anything above 4 is automatically converted to 4. The levels work as follows:

API version is ignored, only package stability and PHP version compatibility is used to determine which package to download for installation.
This is the default setting, and specifies that backwards compatibility must be maintained.

This is performed by checking that the API version first digit does not change. Thus a package with API version of 1.2.3 cannot upgrade to a new package with API version 2.0.0. Upgrades are allowed to versions such as 1.2.4 or 1.3.0.
This is a strict setting, only allowing security and other API bugfixes.

This is performed by checking that the API version's first and second digits do not change. Thus a package with API version of 1.2.3 cannot upgrade to a new package with API version 2.0.0. Upgrades are allowed to versions such as 1.2.4, but not to 1.3.0.
Do not allow any API changes

This is the most paranoid setting, and prevents upgrading to any package that changes API version whatsoever.

If using pyrus.phar, the setting can also be changed with the -p command-line option. This example sets paranoia temporarily to 1:

php pyrus.phar -p install PackageName

This example sets paranoia temporarily to 4:

php pyrus.phar -pppp install PackageName

Pyrus user configuration variables

Introduction

auto_discover

Introduction

cache_dir

Introduction

cache_ttl

Introduction

default_channel

Introduction

download_dir

Introduction

handle

Introduction

http_proxy

Introduction

my_pear_path

Introduction

openssl_cert

Introduction

password

Introduction

plugins_dir

Introduction

preferred_mirror

Introduction

preferred_state

Introduction

temp_dir

Introduction

umask

Introduction

username

Introduction

verbose

Introduction

verbose

Introduction

User Notes: