PEAR Installation per PHP PEAR Manual and PEAR Image_GraphViz package Installation

Submitted by Primary Web Sit... on 2008, November 1 - 8:35pm

PEAR Installation per PEAR Manual plus PEAR Graphviz package Installation

Original Source File: pear_manual_en.html.gz, "PEAR Manual 28-09-2008"

This section is taken directly from the current release of the PHP PEAR documentation as additional help with Windows-based PEAR installation, configuration and troubleshooting.

It includes as a direct example of PEAR package installation, the download and installation of the PEAR Image_GraphViz package. This PEAR package is required to use the Drupal 3rd-party module Graphviz Filter.

My Pear install .php file location: C:\wamp\bin\php\php5.2.6\pear

Chapter 10. Installation

(Of the PHP PEAR HTML Manual)
This chapter describes how to install the PEAR package manager.

Introduction

Before you install PEAR, we recommend you understand what PEAR is and why you should install it.

The base installation that comes with the PHP distribution, contains all the stuff that is needed to run the PEAR installation tools etc. If you have a recent installation of PHP, you can relax: The PEAR base installation is already there, unless you have compiled your PHP with the ./configure flag --without-pear.

The packages that do not come with PHP can be installed with the PEAR package manager. The manager handles installation similar to Debian's "apt-get" package management utility, as well as others such as "yum". Again: If you are running a recent version of PHP (> 4.3.0) you can skip the next section. But if you are running PHP 4.2.* or earlier, you need to manually install the manager.

Apart from installing packages, the PEAR package manager also handles some other tasks: It can create new packages on your machine, manage a registry of installed packages, check dependencies and it can interact with services on pear.php.net, and other PEAR compatible channel servers to get information about available packages.
Getting the manager

Windows

After you have downloaded and installed PHP, you have to manually execute the batch file located in e.g. c:\php\go-pear.bat. The setup will ask you some questions and afterwards the PEAR Package Manager will be installed in the path, which you have specified during installation. Finally you have to add that installation path to your PATH environment. Either do this manually (Start > Control Panel > System > Environment) or run (double-click) the newly generated PEAR_ENV.reg that's now found in the PHP source directory. After that you can access the PEAR Package Manager by running the command pear in a Windows Command Prompt.

To update your PEAR installation, request http://pear.php.net/go-pear in your browser and save the output to a local file go-pear.php. You can then run
php go-pear.php

in a Windows Command Prompt to start the update process.

Note: After changing php.ini, you will need to restart your web server. (WampServer, etc.)

Now check that PEAR works.

Checking if PEAR works

Verifying command line tool

Both pear and pecl tools should be available everywhere from the command line. For that to work, pear's binary directory should be in your PATH variable.

To verify it works, simply type pear. A list of commands should be shown:
$ pear
Commands:
build Build an Extension From C Source
bundle Unpacks a Pecl Package
channel-add Add a Channel
...

You should further test that PEAR is up to date:
$ pear version
PEAR Version: 1.7.2
PHP Version: 5.2.6RC4-pl0-gentoo
Zend Engine Version: 2.2.0
Running on: Linux ...

Verify the include path

To use PEAR and PEAR compatible packages in your applications, you normally include them into your PHP scripts using require_once(). For this to work, PEAR's php_dir must be a part of PHP's include path.

  1. First, check where PEAR installs .php files:
    $ pear config-get php_dir
    /usr/share/lib/php/

    NOTE: For Windows and the default installation of WampServer it would typical be C:\wamp\bin\php\php5.2.6\pear

  2. Now it's time to find which configuration file is used by your PHP installation. (Make sure WampServer is running or else this will not output anything to screen.) On the command line, execute:
    $ php --ini
    Configuration File (php.ini) Path: /etc/php/cli-php5
    Loaded Configuration File: /etc/php/cli-php5/php.ini
    Scan for additional .ini files in: /etc/php/cli-php5/ext-active
    Additional .ini files parsed: /etc/php/cli-php5/ext-active/php_gtk2.ini,
    /etc/php/cli-php5/ext-active/xdebug.ini

    My Initial Results:
    Configuration File (php.ini) Path: C:\Windows
    Loaded Configuration File: C:\wamp\bin\php\php\php5.2.6\php.ini
    Scan for additional .ini files in: (none)
    Additional .ini files parsed: (none)

    NOTE: As illustrated in the "My Initial Results" example my Configuration File Path was not exactly what I wanted and I had to go back and fix it.

    To see which php.ini is used by PHP on your web server, create a file with only <?php phpinfo(); ?> as the contents, and save it in your local web root as check_php.php. Open the file in your browser as http://localhost/check_php.php, to find the path to the php.ini file your web server is using.

  3. Now check PHP's include_path setting on command line:
    php -c /path/to/php.ini -r 'echo get_include_path()."\n";'

    To check PHP's include_path in your web server, create a file with only
    <?php
    phpinfo();?>

    as the contents, and save it in your local web root as check_php.php. Open the file in your browser as http://localhost/check_php.php, to verify the include_path your web server is using.

    In every case, PEAR's php_dir should be in the include path. If not, add it in your system's php.ini.

  4. Create a new .php file with the following contents (I named it as "test_for_system_file.php"):
    <?php
    require_once 'System.php';
    ?>

System.php is shipped with every PEAR installation and thus should be on your computer, too. Open the file with the browser from your web server, and also try it on command line. There should be no output. A message like:
Warning: require_once(System.php): failed to open stream:
No such file or directory in /path/to/test.php on line 2

This means that your include path is not correct.

Chapter 11. Command line installer

Prerequisites
The following description requires the latest version of the PEAR package manager to be installed.

This chapter shows you how to use the PEAR command line installer.

Configuring your PEAR setup

Installing Packages

After getting PEAR working on your machine (see Installation) you most likely want to install some packages. This guide shows people new to the PEAR command line installer how to get started.

To install package, as in the case of Image_GraphViz which is required to use the Drupal Module Graphviz

Normal (package) installation procedure

The general command to install a PEAR package named "foo" is
pear install foo

Typing this and pressing return, the package will be downloaded and installed on your computer. It does not matter if you write the package name in lowercase, UPPERCASE or MixedCase - the installer will find the package by lowercasing the name.

When a package is already installed, you will get the following message:
pear install foo
Ignoring installed package pear/foo
Nothing to install

This happens even if there is a newer version of the package! The correct command to upgrade to the latest version is
pear upgrade foo
upgrade ok: channel://pear.php.net/Foo-1.2.3

If the package already has the latest version, you will get a message similar to the following:
Ignoring installed package pear/Foo
Nothing to upgrade

Dependencies

A package often requires other packages to be installed to function correctly. Such a relation is called a dependency. The PEAR installer has full support for dependencies; it can automatically install required and/or optional dependencies if you wish so.

If you try to install a package with required dependencies, you will get an error that the installation failed. Looking deeper and actually reading the messages shows you that the package needs dependencies that are not installed on your system:
pear install html_page2
Did not download dependencies: pear/HTML_Common,
use --alldeps or --onlyreqdeps to download automatically
pear/HTML_Page2 requires package "pear/HTML_Common" (version >= 1.2)
No valid packages found
install failed

You have several choices:

  • Install dependent packages by hand
  • Let PEAR automatically install necessary dependencies only
  • Let PEAR automatically install necessary and optional dependencies

The first method can be a painful and daunting process, because dependent packages itself can have dependencies.

Both other methods just require a switch to the install command, either --onlyreqdeps (install required dependencies only) or --alldeps (install all dependencies).
pear install --onlyreqdeps html_page2
WARNING: "pear/HTML_Common" is deprecated in favor of "pear/HTML_Common2"
downloading HTML_Page2-0.5.0beta.tgz ...
Starting to download HTML_Page2-0.5.0beta.tgz (15,467 bytes)
......done: 15,467 bytes
downloading HTML_Common-1.2.4.tgz ...
Starting to download HTML_Common-1.2.4.tgz (4,519 bytes)
...done: 4,519 bytes
install ok: channel://pear.php.net/HTML_Common-1.2.4
install ok: channel://pear.php.net/HTML_Page2-0.5.0beta

Off-line Installation

You can download individual packages for e.g. off-line installation on a second machine just as you would install or upgrade a package:
pear download Foo

After downloading, you will have a file like Foo-1.2.3.tgz if the latest version of Foo was 1.2.3. Installing it is as easy as typing
pear install Foo-1.2.3.tgz
Example using Image_GraphViz-1.2.1.tgz
C:\pear download Image_GraphViz-1.2.1.tgz
C:\pear install --alldeps Image_GraphViz-1.2.1.tgz