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.3cannot upgrade to a new package with API version2.0.0. Upgrades are allowed to versions such as1.2.4or1.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.3cannot upgrade to a new package with API version2.0.0. Upgrades are allowed to versions such as1.2.4, but not to1.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