Safely Install and Inspect PHP Packages with PEAR

By the end of this guide you will be able to identify the installed PEAR version, inspect packages and channels, preview an installation, and change a setting without editing a configuration file by hand. The examples target the Ubuntu package php-pear, which provides pear, pecl, and peardev. Allow about 10 minutes for inspection. A real package installation takes longer and may need a build toolchain or administrator access.

1. Confirm the local installation

Start without elevated privileges. The installed command reports its PEAR version separately from the PHP version it is running with:

$ pear -V

On the machine used for this guide, the output begins with PEAR Version: 1.10.13, followed by PHP 8.3.6. Your versions may differ. The local Debian package is php-pear, version 1:1.10.13+submodules+notgz+2022032202-2build1. The manual page still labels the documented PEAR version as 1.10.0, so use pear -V for the behaviour you actually have.

These names are related but not interchangeable:

• pear installs PEAR packages.
• pecl uses the same installer style for PECL extensions.
• peardev is a wrapper that removes the normal configured memory limit. Use it only when a build genuinely needs that headroom.

Do not use peardev as a general replacement for pear. Removing a memory limit can turn a failed build into an uncontrolled resource consumer.

2. Inspect installed packages before changing anything

List the packages already registered in the default channel:

$ pear list

Typical columns are PACKAGE, VERSION, and STATE. To see where one package put its files, pass its exact registered name:

$ pear list-files PEAR

This distinction matters when troubleshooting PHP include paths or extensions. A package can be registered successfully while the PHP process you are testing uses a different php.ini, PHP version, or include path. PEAR's configuration output shows the relevant directories, but it does not prove that every PHP runtime uses them.

You can query the channel for package metadata without installing it:

$ pear remote-info Console_Getopt

The response includes the latest and installed versions when the package is known locally and remotely. A remote query needs network access and can show a channel warning. Treat package names and channel metadata as external input; verify the package name, release, and source before allowing installation scripts to run.

3. Preview an installation

The install command accepts a package name, a local package archive, a package.xml, or a URL. It can also take a channel-qualified name such as channel/Package. First ask PEAR what it would download:

$ pear install --pretend PACKAGE_NAME

Replace PACKAGE_NAME with the package name you have checked. The pretend operation is useful for dependency review, but it is not a security approval: it may still contact the configured channel, and its result can change as the channel changes. For a fully offline check against a local archive, use:

$ pear install --pretend --offline /path/to/Package-1.0.tgz

Do not add --nodeps merely to get past a dependency error. That option tells PEAR to ignore dependencies and can leave a package that fails only when production code loads it. Similarly, --force overwrites newer installed packages. Use either option only with a documented compatibility reason and a tested rollback.

4. Install with an explicit privilege boundary

On this installation, php_dir is /usr/share/php and the executable directory is /usr/bin. Writing there normally requires administrator privileges. Do not prefix every command with sudo, because that changes which user's configuration and cache are used. Inspect first:

$ pear config-show
$ pear list

If you have approved the package and intend to modify the system PEAR tree, run the narrowest command that your local permissions require:

$ sudo pear install PACKAGE_NAME

Afterwards, check both registration and file placement:

$ pear list | grep -F PACKAGE_NAME
$ pear list-files PACKAGE_NAME

The exact package name may contain a vendor prefix or different capitalisation. Use the name printed by pear list, not an assumed filesystem directory.

To remove an installed package, use its registered name:

$ sudo pear uninstall PACKAGE_NAME

That is not a complete rollback if the package changed a PHP configuration file or created external data. Record the pre-install package list and inspect the package files before uninstalling. Never use a broad rm against /usr/share/php as a shortcut.

5. Read and change configuration safely

PEAR combines user and system configuration. The documented files are /etc/pear.conf for the system layer and $HOME/.pearrc for the user layer. On this machine the effective system filename is /etc/pear/pear.conf, as reported by config-show. Do not edit either file directly: the pear.conf(5) manual says to use PEAR's configuration commands.

Show all effective values, or limit the output to a layer:

$ pear config-show
$ pear config-show user
$ pear config-show system

Read one value before changing it:

$ pear config-get preferred_state

The local default is stable. If you need to test another release state temporarily, use a command-line override. It affects that invocation only:

$ pear -d preferred_state=beta config-get preferred_state

For a persistent user-layer change, save the old value, set the new one, and restore it when finished:

$ OLD_STATE="$(pear config-get preferred_state)" && \
  pear config-set preferred_state stable
$ pear config-get preferred_state
$ pear config-set preferred_state "$OLD_STATE"

config-set defaults to the user layer. A third argument can select a layer, but system changes should be deliberate and may require sudo. If a setting is rejected, keep the previous value and consult pear help config-set rather than editing the file.

6. Diagnose channels and confusing failures

List the configured channels, then inspect the default channel:

$ pear list-channels
$ pear channel-info pear.php.net

If PEAR reports that a channel has updated protocols, update that channel before retrying a remote operation:

$ pear channel-update pear.php.net

This changes the channel record and may download metadata, so run it in a maintenance window if your environment requires controlled network changes. If the update fails, check DNS, proxy settings, certificates, and the channel name. config-show exposes the configured HTTP proxy and cache directories without requiring a file edit.

A permissions error can mean the target directory is system-wide, or it can mean sudo has selected a different PEAR configuration. Compare pear config-show with sudo pear config-show before changing anything. If they disagree, choose the intended layer explicitly and avoid accidentally creating root's separate user configuration.