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:
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.
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.
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:email@example.com: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:
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!