Section 10.3. Obtaining PEAR

10.3. Obtaining PEAR

In this section, you learn how to install PEAR on your platform from a PHP distribution or through the go-pear.org web site.

10.3.1. Installing with UNIX / Linux PHP Distribution

This section describes PEAR installation and basic usage that is specific for UNIX or UNIX-like platforms, such as Linux and Darwin. The installation of the PEAR Installer itself is somewhat OS-dependent, and because most of what you need to know about installation is OS-specific, you find that here. Using the installer is more similar on different platforms, so that is described in the next section, with the occasional note about OS idiosyncrasies.

As of PHP 4.3.0, PEAR with all its basic prerequisites is installed by default when you install PHP.

If you build PHP from source, these configure options cause problems for PEAR:

• --disable-pear. make install will neither install the PEAR installer or any packages.

• --disable-cli. The PEAR Installer depends on a standalone version of PHP installed.

• --without-xml. PEAR requires the XML extension for parsing package information files.

10.3.1.1 Windows

This section shows how to install PEAR on a Windows PHP installation. Start by just installing a binary distribution of PHP from http://www.php.net/downloads.php (see Figure 10.1). If you go with the defaults, your PHP install will end up in C:\PHP, which is what you will see in the forthcoming examples.

Figure 10.1. PHP Welcome screen.

10.3.2. Installing with PHP Windows Installer

When you have PHP installed, you need to make sure that your include_path PHP setting is sensible. Some versions of the Windows PHP Installer use c:\php4\pear in the default include path, but this directory (c:\php4) is different from the one created by the PHP Windows Installer. So, edit your php.ini file (in c:\winnt or c:\windows, depending on your Windows version) and change this directory to c:\php\pear (see Figure 10.2).

Figure 10.2. Example php.ini modifications

Now, you are ready to use go-pear.

10.3.3. go-pear.org

go-pear.org is a web site with a single PHP script that you can download and run to install the latest stable version of the PEAR Installer and the PHP Foundation Classes (PFC). go-pear is cross-platform and can be run from the command line and from your web server.

PHP distributions bundle a particular release of the PEAR Installer; on the other hand, go-pear gives you the newest stable PEAR releases. However, go-pear does know your directory layout, but really contorts itself to figure it out, and will try adapting your PEAR Installation to that.

In this section, you learn how to use go-pear from the command line and web server, and on UNIX and Windows.

10.3.3.1 Prerequisites

Because go-pear is written in PHP, you need a CGI or CLI version of PHP to execute it outside the web server. By default, the CLI version is installed along with your web server PHP module. Try running php v to see if it is available to you:

 PHP 5.0.0 (cli), Copyright (c) 1997-2004 The PHP Group Zend Engine v2.0, Copyright (c) 1998-2004 Zend Technologies 

By default, the php command is installed in the /usr/local/bin directory on UNIX, or c:\php on Windows. In Windows, the CLI version of PHP may also be called php-cli; in that case, you need to type php-cli for every example that says just php.

10.3.3.2 Going PEAR

If your PHP install did not include PEAR, you can use go-pear as a universal PEAR bootstrapper. All you need is a CLI or CGI version of PHP installed somewhere.

You can download the go-pear script and execute it, or run it all in one command, like this:

 $ lynx source http://go-pear.org | php 

This command simply takes the contents of http://go-pear.org and sends it to PHP for execution.

If you do not have lynx available on your system, try an alternative way of executing go-pear directly:

Using GNUS wget:

 $ wget O- http://go-pear.org | php 

Using fetch on FreeBSD:

 $ fetch o  http://go-pear.org | php 

Using Perl LWP's GET utility:

 $ GET http://go-pear.org | php 

On Windows, there is no "fetch this URL" tool, but you may be able to use PHP's URL streams (make sure that url_includes is not disabled in your php.ini file):

 C:\> php-cli r "include('http://go-pear.org');" 

If none of this works, open http://go-pear.org in your browser, save the contents as go-pear.php and simply run it from there:

 C:\> php go-pear.php 

The output will look like this:

 Welcome to go-pear! Go-pear will install the 'pear' command and all the files needed by  it. This command is your tool for PEAR installation and maintenance. Go-pear also lets you download and install the PEAR packages bundled  with PHP: DB, Net_Socket, Net_SMTP, Mail, XML_Parser, PHPUnit. If you wish to abort, press Control-C now, or press Enter to continue: 

This greeting tells you what you are about to start. Press Enter for the first real question:

 HTTP proxy (http://user:[e-mail]:port), or Enter for  none: 

go-pear checks your http_proxy environment variable and presents the value of that as the default value if http_proxy is defined. If you want to use an HTTP proxy when downloading packages, enter the address of it here, or just press Enter for "no proxy."

Now, on to the interesting part:

 Below is a suggested file layout for your new PEAR installation. To  change individual locations, type the number in front of the  directory. Type 'all' to change all of then, or simply press Enter to accept these locations. 1.  Installation prefix          :/usr/local 2.  Binaries directory           : $prefix/bin 3.  PHP code directory           : $prefix/share/pear 4.  Documentation base directory : $php_dir/docs 5.  Data base directory          : $php_dir/data 6.  Tests base directory         : $php_dir/tests 1-6, 'all' or Enter to continue: 

Each setting is internally assigned to a variable (prefix, bin_dir, php_dir, doc_dir, data_dir and test_dir, respectively). You may refer to the value of other settings by referencing these variables, as shown previously. Let's take a look at each setting:

• Installation prefix. The root directory of your PEAR installation. It has no other effect than serving as a root for the next five settings, using $prefix.

• Binaries directory. Where programs and PHP scripts from PEAR packages are installed. The pear executable ends up here. Remember to add this directory to your PATH.

• PHP code directory. Where PHP code is installed. This directory must be in your include_path when using the packages you install.

• Documentation base directory. The base directory for documentation. By default, it is $php_dir/doc, and the documentation files for each package are installed as $doc_dir/Package/file.

• Database directory. Where the PEAR Installer stores data files. Data files are just a catch-all category for anything that does not fit as PHP code, documentation, and so on. As with the documentation base directory, the package name is added to the path, so the data file convert.xsl in MyPackage would be installed as $data_dir/MyPackage/convert.xsl.

• Tests base directory. Where regression test scripts for the package are installed. The package name is also added to the directory.

When you are satisfied with the directory layout, press Enter to proceed:

 The following PEAR packages are bundled with PHP: DB, Net_Socket,  Net_SMTP, Mail, XML_Parser, PHPUnit2. Would you like to install these as well? [Y/n] : 

For your convenience, go-pear requests whether you want to install the PFC packages. Just install them (press Enter):

 Loading zlib: ok Downloading package: PEAR.............ok Downloading package: Archive_Tar......ok Downloading package: Console_Getopt....ok Downloading package: XML_RPC..........ok Bootstrapping: PEAR...................(remote) ok Bootstrapping: Archive_Tar............(remote) ok Bootstrapping: Console_Getopt.........(remote) ok Downloading package: DB...............ok Downloading package: Net_Socket.......ok Downloading package: Net_SMTP.........ok Downloading package: Mail.............ok Downloading package: XML_Parser.......ok Downloading package: PHPUnit2.........ok Extracting installer..................ok install ok: PEAR 1.3.1 install ok: Archive_Tar 1.2 install ok: Console_Getopt 1.2 install ok: XML_RPC 1.1.0 install ok: DB 1.6.4 install ok: Net_Socket 1.0.2 install ok: Net_SMTP 1.2.6 install ok: Mail 1.1.3 install ok: XML_Parser 1.2.0 install ok: PHPUnit2 2.0.0beta2 The 'pear' command is now at your service at /usr/local/bin/pear 

Congratulations, you have just installed PEAR!