The PEAR Installer Manifesto

Chapter 1. Acquiring PEAR: What is it and How do I Get It?

Chances are, you've seen the acronym PEAR at some point in your use of PHP, whether it was in passing or when installing and using a package from pear.php.net. If you've investigated, you might have probably heard of popular software provided by PEAR, such as the DB database abstraction package, or the HTML_QuickForm package. What you may not realize is that PEAR is much more than just a collection of packages that you can use. PEAR also contains the most versatile installation program for PHP, the PEAR installer. With the PEAR installer, you can do much more than just install packages from pear.php.net. You can install packages from other PEAR channels, distribute your own software projects using your own PEAR channel, and even maintain a complex intranet web project, all using the PEAR installer. Surprised? Read on, this book will reveal the intimate secrets of the PEAR installer and how it will revolutionize your everyday development with the PHP programming language.

The primary purpose of PEAR is to support code reuse. PEAR stands for the PHP Extension and Application Repository. PEAR provides both an advanced installer and a code repository at http://pear.php.net. Unlike competing PHP code repositories that you may be familiar with such as http://www.phpclasses.org or general purpose development sites like http://www.sourceforge.net, all PEAR code is organized into discrete reusable components called packages. A package consists of a group of files and a descriptor file called package.xml that contains meta-data about the package's contents, such as the package version, any special dependencies, and textual information such as the package description and authors.

Although most packages contain PHP code, there is no special restriction on the contents of a package. Some packages, such as http://pear.php.net/HTML_AJAX provide JavaScript files as well as PHP files. One of the example packages mentioned in Chapter 4 bundles only MP3 music files. Literally anything you can save as a file can be distributed in a PEAR package.

The software that transforms a package from an inert grouping of files into a dynamic software package is called the PEAR installer and is itself a PEAR package, located at http://pear.php.net/PEAR. In other words, the PEAR installer can be used to upgrade itself. It is truly a very powerful application.

Traditionally, PHP software has been distributed with a passive installation approach, following these typical steps:

1. Download a .zip or a .tar.gz containing all the files of the application
2. Decompress the files into a folder in your website's document root
3. Read the Readme and Install files
4. Do various post-installation tasks, creating files, checking requirements
5. Test it
6. Often, changes are required at the system-level changes (adding extensions to php.ini, changing php.ini settings, upgrading PHP itself)

For lack of a better name, we'll call this the "unzip-and-go" system of PHP software distribution. Although this in fact works very well for small, single-developer low-traffic websites, it contains a hidden cost that is not immediately apparent. There is one single fact about the unzip-and-go software installation system that limits its ultimate usefulness:

Note

Upgrading unzip-and-go installations is very hard

In today's fast-paced development world, one of the weaknesses of the Internet is security. Quite often, serious security vulnerabilities are discovered in software that requires an immediate upgrade to fix. When using a complete unzip-and-go software application, upgrading involves a large degree of risk. First of all, once the upgrade is complete, if the software is broken, reverting the upgrade requires either restoring from a backup or re-installing the old software. Reverting to an earlier package version with the PEAR installer is a one-line command and is very straightforward.

Note

Why is Upgrading Necessary at all if the Code is Working?

Just a month before writing this chapter, our hosting provider's website was compromised. Due to a number of unfortunate events, I was completely locked out of our server for an unacceptable period of time and we lost business as a result of the delay in receiving important emails.

The cause of this compromise was—an innocent installation of an outdated copy of a CVS viewing program. The program contained an arbitrary PHP execution vulnerability, and the systems administrator had not upgraded to the latest version because it was tremendously difficult to upgrade the viewing software.

Had this same software been distributed as a PEAR package, upgrading would have been a one-line command as follows:

$ pear upgrade PackageName

The lost business would have never been a problem then. In today's world, upgrading software is in fact critical to the long-term success of any website, no matter how large or small.

The advantages of using the PEAR installer over a simple unzip-and-go solution are most apparent when projects grow in complexity. Let's look at a short list of the advantages:

File conflicts are not possible
Problems caused by incompatible PHP versions/PHP extensions/PHP code are all handled by advanced dependency resolution
Distributing application development between different sites is simple due to the revolutionary new PEAR channels feature introduced in PEAR version 1.4.0 (Chapter 5 is devoted to exploration of PEAR channels)
All installation configurations can be handled in a standardized and consistent way for all packages—once you learn how to handle one PEAR package; all the others are handled in the same way.

Versioning of code allows clear fault resolution as well as the ability to revert changes that break code.

Before using the PEAR installer, it is important to understand the disadvantages of using the PEAR installer over unzip-and-go:

The PEAR installer itself must be installed on the development machine and preferably on the server (although this is no longer required thanks to the PEAR_RemoteInstaller package, discussed in section 1.3.3.1, Synchronizing to a server with no shell access using PEAR_RemoteInstaller).
If you are distributing your own packages, you need a full understanding of the package.xml description file, and possibly an understanding of PEAR channels in order to set one up yourself.
Depending on relative file locations is not always possible through traditional means. This is due to the flexibility of PEAR configuration. Rather than relying upon dirname(__FILE__), a PEAR-specific way must be used, such as file replacement tasks (discussed in Chapter 2).

Additional configuration outside of php.ini may be needed in pear.conf/pear.ini (most of this configuration is handled when the PEAR installer is installed).

The most significant barrier to using PEAR has traditionally been the effort it takes to install the PEAR installer itself, and this has been the focus of recent efforts to improve the installer's installation process. There is a great deal of possibility in recent innovations made possible by PHP version 5.1.0 or newer, as evidenced by work made possible by the PHP_Archive PEAR package (http://pear.php.net/PHP_Archive) and its sibling, the phar PECL extension (http://pecl.php.net/phar). These packages enable the distribution of an application in a single file that greatly enhances the capabilities of an installer.

A Democratic Innovation for PHP: PEAR Channels

The most important innovation of the PEAR installer is PEAR channels, something that no other package distribution mechanism supports. PEAR channels are a simple way to easily install packages from multiple sources over the Internet.

Through the use of PEAR channels, applications can reliably depend on code from several unrelated sources. Some of the more prominent channels are:

pear.php.net: PEAR itself is a channel
pecl.php.net: PECL is for PHP extensions what PEAR is to regular PHP packages
gnope.org: PHP-GTK2 channel
pear.chiaraquartet.net: The first PEAR channel outside the php.net domain
components.ez.no: eZ components PEAR channel
pearified.com: source of PEAR-packaged Smarty, phpMyAdmin and others

Also of interest are channel aggregators like:

http://www.pearadise.com: Tobias Schlitt's PEAR channel aggregator
http://www.pearified.com: The channel aggregator portion of the pearified channel
http://www.upear.com: Another aggregator

Each PEAR channel distributes code fitting a wide variety of needs.

What is PEAR? A Code Repository or an Installer?

PEAR has a tendency to confuse people as the name is used interchangeably for the PEAR installer and for the PEAR repository at http://pear.php.net. This confusion naturally arises from the fact that the front page of pear.php.net says "PEAR is a framework and distribution system for reusable PHP components" but the PEAR installer's package name is "PEAR". In fact, PEAR is both a code repository and an installer; the two are linked inextricably by the fact that much of PEAR's strength is the ability to update a local installation from packages on a remote server over the Internet.

PEAR Package Repository and PEAR Channel

The PEAR package repository at pear.php.net is the official PEAR channel, and is the oldest PEAR channel, predating the concept of PEAR channels by five years. Many popular packages are distributed via pear.php.net such as HTML_QuickForm, DB_DataObject, MDB2, and PhpDocumentor. Most of the time, when people refer to "PEAR" in the abstract, one of the packages distributed at pear.php.net is what they are talking about.

The package repository at pear.php.net was established in 1999 by Stig Bakken and a few others to help fill in the gaps in PHP. PEAR's first usable release coincided with approximately PHP version 4.0.6. At this time, PEAR was designed as a framework, providing several base classes and an installer to manage them. The PEAR package provided two of the base classes, PEAR and System. The PEAR class, located in file PEAR.php was designed to provide basic error handling and a few other add-ons beyond what is available in PHP's internal trigger_error() error handling.

Several basic packages were designed to handle common tasks, such as DB for database-independent code, HTML_Form for HTML Forms, Log for basic logging, and this list expanded (to make a long story short) until the present day where there are 374 packages available from pear.php.net at the time of this chapter, and more on the way via pending proposals.

PEAR has had its share of woes since its rosy beginnings. PHP has evolved, and introduced several features that supersede the functionality provided by PEAR. For instance, the Exception class introduced in PHP 5.0.0 provides similar functionality to the PEAR_Error class, the PDO extension provides similar functionality to the DB package, and so on. In addition, as PEAR has grown, some problems in its initial design as a repository have surfaced and led to both minor and major crises.

Several good things have come out of these growing pains, including the efficient PEPr proposal system for proposing new packages, and a strong push towards both stability and innovation. Much of the push towards innovation is coming from external pressure due to the advent of new ideas from projects like SolarPHP, eZ components, Phing, Propel, Agavi, and the Zend Framework. However, one of the significant forces of innovation in PEAR is the PEAR installer itself, specifically with the new features found in version 1.4.0 and newer.

One of the crucial new features in the newer versions of the PEAR installer is PEAR channels. A PEAR channel is simply a server that provides packages like pear.php.net, and also provides special web services that enable the PEAR installer to communicate with the server; channels are covered in detail in Chapter 4.

PEAR Installer

Most books that discuss PEAR spend a great deal of time on using popular packages from the PEAR repository (http://pear.php.net) such as DB (http://pear.php.net/DB) or HTML_QuickForm (http://pear.php.net/HTML_QuickForm). This book takes a different route, instead focusing exclusively on the power surrounding the installation mechanism of the PEAR installer itself. When you see a reference to PEAR in this book, you should know that it is in fact a reference to the PEAR installer (http://pear.php.net/PEAR) and not to the repository at large.

The PEAR installer consists of four abstract task-oriented sections:

package.xml parser and dependency processor
File installation processor, configuration processor, and package registry
User front end and command processor

Remote server synchronization and downloading engine

Fortunately, as an end-user, you don't really need to know or care about any of these beyond the way that your application communicates with the installer and how people will actually use the installer to install your code.

First and foremost, you need to understand how PEAR actually installs its packages, as this is a little different from the old unzip-and-go philosophy. PEAR categorizes files into different types, and installs each file type differently. For instance, files of type php will be installed into a subdirectory of the user's configuration variable php_dir. So if the user has set php_dir to /usr/local/lib/php/pear, a file that is packaged in directory Foo/Bar/Test.php will be installed into /usr/local/lib/php/pear/Foo/Bar/Test.php. Files of type data will be installed into a subdirectory of the user's configuration variable data_dir, but unlike PHP files, data files are installed into their own private sub-directory based on the package name. If the user has set data_dir to be /usr/local/lib/php/data and the package is named "TestPackage", a file that is packaged in directory Foo/Bar/Test.dat will not be installed at /usr/local/lib/php/data/Foo/Bar/Test.dat, but instead be installed in /usr/local/lib/php/data/TestPackage/Foo/Bar/Test.dat! This and other details of PEAR's installation are covered in Chapter 2.

Next, you need to know a bit about how PEAR knows which files are in a package, what it needs in order to work (i.e. "This package only works in PHP 4.3.0 and newer, and needs any version of the DB_DataObject package, and only versions 1.2.3 of the Log package, recommending version 1.4.6 be installed"), or its dependencies. This information is also covered in Chapter 2, where we learn about the package.xml file format.

After reading Chapters 2 and 3, you should know enough about PEAR to manage the creation of your own packages for local installation, or to propose a new package to the official pear.php.net repository. Should you wish to distribute your packages for others to use, whether it be free, for private clients, or for sale, you will need to have an understanding of how PEAR channels work. Setting up a channel server is a relatively easy task. At the time of writing this chapter, there was one option available for setting up a channel, but several potential competing options are on the verge of completion. It's an exciting time to be involved in PHP! Setting up your own channel is covered in Chapter 5.

Of course, not everyone is distributing their code publicly. Most developers are busy designing their own websites either by themselves or in a team. The PEAR installer is a highly effective tool for managing a complete website when used in conjunction with a revision control system. Chapter 4 covers this topic in great detail.

In short, the PEAR installer is one of the most effective tools for managing a high-quality software library, high-quality application, or a high-quality website.

Installing the PEAR Installer

There are three methods of acquiring PEAR. The first way has been available since PHP 4.2.0, and simply involves installing PHP and either configuring --with-pear (on Unix) or running go-pear from within the PHP directory.

Note

I'm Running Windows and my PHP doesn't have PEAR in it, Where is it?

If you are running PHP version 5.1 or older, to get a copy of PHP that bundles PEAR, you need to download the .zip file rather than the Windows installer (.msi). PHP 5.2.0 and newer has vastly improved the Windows Installer (.msi) distribution, and this is recommended to acquire PEAR. The installer (at least at this time) is not really useful at all, as it is never updated unless there is a critical error. As such, getting the truly useful elements of PHP requires using the .zip file. Never fear, PHP is pretty much an unzip-and-go language on Windows.

If I were less diplomatic, I might say something like "Don't even think about running PHP on Windows as a production server." However, I do feel it is important to say this: "In my opinion, running PHP on Windows as a production server is not worth the effort and expense." Although it can be done, the only reason it should ever be considered is if your boss will fire you on installing Unix. Or you work for a company that maintains the Windows operating system. In that case, you will be forgiven.

The second involves grabbing the go-pear script from http://pear.php.net/go-pear, and saving it as go-pear.php, then running this file. Last, there are a few unofficial sources for acquiring PEAR, the most notable being the Gnope installer that sets up PHP 5.1, PEAR, and PHP-GTK2 in one step.

PEAR Bundled with PHP

As mentioned above, if you are running Windows, installing PEAR is relatively simple. Running the go-pear command will run the installation script. In addition, as of PHP version 5.2.0, there is an excellent Windows Installer-based (.msi file extension) installation mechanism that bundles PEAR in its distribution, and is

recommended. For earlier PHP versions, in order to obtain a bundled PEAR, you must download the .zip file distribution instead of the .msi Windows Installer-based installation mechanism.

If you are running Unix, you need to use at least this minimal configure line to set up PEAR:

$ ./configure --enable-cli --enable-tokenizer --with-pcre-regex -- enable-xml

To take full advantage of PEAR, it is a good idea to enable the zlib extension for accessing compressed PEAR packages as well:

$ ./configure --enable-cli --enable-tokenizer --with-pcre-regex -- enable-xml --with-zlib

When you install, be sure that you have full write access to the directory that PEAR will be installed in (usually /usr/local/lib, but configurable with the --prefix option; /lib is appended to the prefix). When you install PEAR, it will also install the needed packages Console_Getopt and Archive_Tar.

$ make install-pear
Installing PEAR Environment: /usr/local/lib/php/
[PEAR] Archive_Tar - installed : 1.3.1
[PEAR] Console_Getopt installed : 1.2
pear/PEAR can optionally use package "pear/XML_RPC" (version >= 1.4.0)
[PEAR] PEAR - installed : 1.4.9
Wrote PEAR system config file at: /usr/local/etc/pear.conf
You may want to add: /usr/local/lib/php to your php.ini include_path

After completing PEAR installation, as the last line of installation suggests, you will want to ensure that PEAR is in php.ini's include_path setting. The easiest way to determine this is to first find php.ini:

$ php i |grep php[.]ini
Configuration File (php.ini) Path => /usr/local/lib

This example shows that php.ini is located at /usr/local/lib/php.ini. Open this file with your favorite editor, and either find the line that says "include_path=" or add a new one that is something like this:

include_path=.:/usr/local/lib/php

Of course, substitute the suggested path from your specific installation (the last line of output) for /usr/local/lib/php.

Note

What is this so-called "include_path"?

Oh dear—time to pull out the PHP manual again, to be specific, http://www.php.net/include. To summarize, the include statement and its cousins include_once, require and require_once all serve to dynamically include external PHP code. If you pass a full path like /path/to/my.php:

include '/path/to/PEAR.php';

Note

then naturally /path/to/my.php will replace the include statement and be executed. If, however, you pass in a relative path like:

include 'PEAR.php';

This will instead search through the include_path and try to find a PEAR.php file. If the include_path is .:/usr/local/lib/php, then PHP will first try to find PEAR.php in the current directory (.), and if it is not found, then it will search for PEAR.php in /usr/local/lib/php/PEAR.php. This allows customization of library locations on the disk, which is precisely what PEAR attempts to accomplish.

If you are running Windows, the go-pear batch file will prompt you to choose a location to install PEAR, defaulting to either C:\php4 for version 4, C:\php5 for version 5.0, or the current directory for version 5.1 or newer. Unless you have a compelling reason to install PEAR elsewhere, it is a good idea to accept the default locations, as it will save some potential trouble later on. If you are installing PEAR from version 5.1.0 or newer, the installer will ask you if you are installing a local or a system installation.

Are you installing a system-wide PEAR or a local copy?
(system|local) [system] :

Simply hit Return to install a system-wide PEAR (in general, with installation of PEAR, if you don't know what it is asking you, always choose the default value). Next, it will ask you for a location to install your copy of PEAR:

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 them or simply press Enter to
accept these locations.
1. Installation base ($prefix) : C:\php51
2. Binaries directory : C:\php51
3. PHP code directory ($php_dir) : C:\php51\pear
4. Documentation directory : C:\php51\pear\docs
5. Data directory : C:\php51\pear\data
6. Tests directory : C:\php51\pear\tests
7. Name of configuration file : C:\php5\pear.ini
8. Path to CLI php.exe : C:\php51\.
1-8, 'all' or Enter to continue:

Change any values you wish to change by typing the number in front of the item and hit Enter. If you wish to change the installation base directory, type 1 and hit Enter. If you want to modify all of the values, type all and hit Enter. Once you are satisfied, hit Enter without typing anything to continue. At this point, it will install packages (which should look similar to what is displayed in Unix installation of PEAR) and finally ask if you would like to modify php.ini. If you choose to do this, it will automatically update the include_path setting in php.ini, and you will be good to go.

Installation for PHP Versions Older than 5.1.0

If you have a version of PHP older than 5.1.0 and wish to install PEAR, you should not use the bundled version of PEAR, but instead install PEAR via the go-pear script. To retrieve this script, browse to http://pear.php.net/go-pear in any web browser and save it to disk as go-pear.php, or if on Unix, then you have the wget command:

$ wget O go-pear.php http://pear.php.net/go-pear

Once you have go-pear.php accessible, simply run it:

$ php go-pear.php

Note

Why Just for PHP 5.1.0 and Older?

As I was asked once, "Why is it important to only use the go-pear script for PHP versions older than 5.1.0? Will this not also change over time when there is a new PEAR installer released with PHP 6.0.0?"

The reason for this has to do with how go-pear works. The go-pear script is a brilliant design that extracts key files directly from CVS based on their release tags and then downloads packages and installs them based on their latest stable version. Although brilliant, this is a dangerous approach that guarantees your installation will break if there is a problem in CVS.

The PEAR installer bundled with PHP version 5.1.0 and newer is in fact self-contained, does not contact the Internet at all, and is tested and guaranteed to work with that version of PHP. Once PEAR is installed, grabbing the latest version is both easy and safer than using go-pear:

pear upgrade PEAR

Output will be very similar to go-pear from bundled PHP, but will instead begin with:

$ php go-pear.php
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.
Use 'php go-pear.php local' to install a local copy of PEAR.
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:

Because go-pear requires internet access, the next question will be for a proxy. Be sure that if you are behind a firewall, you know whether you need to use a proxy:

HTTP proxy (http://user:password@proxy.myhost.com:port), or Enter for none::

The next step of the installation process should look pretty familiar:

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 them or simply press Enter to accept these locations.
1. Installation prefix : C:\php51
2. Binaries directory : $prefix
3. PHP code directory ($php_dir) : $prefix\pear
4. Documentation base directory : $php_dir\docs
5. Data base directory : $php_dir\data
6. Tests base directory : $php_dir\tests
7. Temporary files directory :
8. php.exe path : C:\php51\php.exe
1-8, 'all' or Enter to continue:

After choosing location, go-pear will download the needed code, and install PEAR packages. It will also ask whether to install a few more packages, and at the end whether to modify php.ini.

If you are feeling adventurous, you might also simply try opening go-pear.php inside a web browser. This will install the web front end to PEAR, which is very nice but not as actively maintained as the Command-Line Installer (CLI).

Other Unofficial Sources

Before we continue, it is important to note that everything in this section is unofficial and therefore not supported by the folks over at pear.php.net. Any problems you encounter are the domain of the site from which you downloaded it! Ok, enough preambles.

Christian Weiske over at http://www.gnope.org has been working hard at both making PHP-GTK2 work in PHP 5.1 and making it easy to install PHP-GTK2 applications using PEAR. As such, he worked very closely with me to create a GTK2 front end to the PEAR installer, which is now available through PEAR at http://pear.php.net/PEAR_Frontend_Gtk2. This is the official PHP-GTK2 front end for PEAR. The front end requires that PEAR already be installed in order to use it.

However, Christian has taken it up a notch, and has written a Windows installer that provides the latest stable PHP 5.1, PEAR, and PHP-GTK2 that sets up everything for you. This is a great way to get started with PEAR, if you are new to the whole process. The current release is version 1.0, but this is an alpha release, so things may not work properly.

The first thing you should note is that if you have already set up PHP, the PATH environment variable in Windows may cause some conflicts with the existing PHP installation. In short, don't try to install both a regular copy of PHP and the gnope PHP unless you know what you are doing.

Installing gnope is really easy, just download the installer and run it. The prompts are just like any other Windows installation.

Synchronizing to a Server with no Shell Access Using PEAR_RemoteInstaller

Once you have successfully installed PEAR on a development machine, how do you properly install PEAR on the live server? For many developers, this is simply a matter of repeating the same steps on the live server that are performed on the development server. However, many developers out there have the misfortune of using a shared hosting provider who does not provide a shell, but does provide PHP. In the past, this essentially eliminated any possibility of successfully installing PEAR packages.

As of PEAR 1.4.0, this is no longer an issue, thanks to the PEAR_RemoteInstaller package (http://pear.php.net/PEAR_RemoteInstaller). This package provides special commands for synchronizing a customized PEAR server and the remote server. Unlike other solutions, the only tools required to implement this are PHP 5 on your development machine, and access to an FTP server.

To get started, install PEAR_RemoteInstaller onto your development machine:

$ pear install PEAR_RemoteInstaller

Note

Publication Limitation

Note that at the time this book was written, the latest version of PEAR_RemoteInstaller was 0.3.0, stability alpha. To install, you will need to append alpha or -0.3.0 as in:

$ pear install PEAR_RemoteInstaller-alpha

$ pear install PEAR_RemoteInstaller-0.3.0

Next, you need to create a configuration file for the remote machine using the config-create command. However, before this is possible, it is important to know the full path to your host. The easiest system to determine this is to run this simple script on your web host:

<?php
echo __FILE__;
?>

Save this as me.php, and upload it to your web host. When run, this will output something similar to:

/home/myuser/htdocs/me.php

Once you have this information, you can begin

$ pear config-create /home/myuser pear.ini

This will display something similar to:

CONFIGURATION (CHANNEL PEAR.PHP.NET):
=====================================
Auto-discover new Channels auto_discover <not set>
Default Channel default_channel pear.php.net
HTTP Proxy Server Address http_proxy <not set>
PEAR server [DEPRECATED] master_server <not set>
Default Channel Mirror preferred_mirror <not set>
Remote Configuration File remote_config <not set>
PEAR executables directory bin_dir /home/myuser/pear
PEAR documentation directory doc_dir /home/myuser/pear/docs
PHP extension directory ext_dir /home/myuser/pear/ext
PEAR directory php_dir /home/myuser/pear/php
PEAR Installer cache directory cache_dir /home/myuser/pear/cache
PEAR data directory data_dir /home/myuser/pear/data
PHP CLI/CGI binary php_bin C:\php5\php.exe
PEAR test directory test_dir /home/myuser/pear/tests
Cache TimeToLive cache_ttl <not set>
Preferred Package State preferred_state <not set>
Unix file mask umask <not set>
Debug Log Level verbose <not set>
PEAR password (for password <not set> maintainers)
Signature Handling Program sig_bin <not set>
Signature Key Directory sig_keydir <not set>
Signature Key Id sig_keyid <not set>
Package Signature Type sig_type <not set>
PEAR username (for username <not set> maintainers)
User Configuration File Filename C:\test\pear.ini
System Configuration File Filename #no#system#config#
Successfully created default configuration file "C:\test\pear.ini"

Once you have the pear.ini file, upload it to your remote web host and save it in the /home/myuser directory (the default directory of your FTP login). Next, we need to create our local working copy of PEAR:

$ mkdir remote
$ cd remote

If you are running Windows:

$ pear config-create w C:\remote\ pear.ini

Otherwise (assuming you are running as user foo on your development machine):

$ pear config-create /home/foo pear.ini

Next, determine the kind of FTP connection you use. You'll need to know your username and password for accessing FTP, and the host name. For our example, we will use myuser and password as the user/password combination, and yourwebsite.example.com as the host.

If you use regular FTP, you will want to do:

$ pear c pear.ini config-set remote_config ftp://myuser:password@yourwebsite.example.com/

If you use FTPS, you will want to do:

$ pear c pear.ini config-set remote_config ftps://myuser:password@yourwebsite.example.com/

If you use SFTP, you will want to do:

$ pear c pear.ini config-set remote_config ssh2.sftp://myuser:password@yourwebsite.example.com/

In order to use SFTP, you need to install the SSH2 extension from pecl.php.net (http://pecl.php.net/ssh2), an excellent extension written by Sara Golemon. On Unix, this is simple; SSH2 can be installed via:

$ pecl install ssh2

On Windows, php_ssh2.dll should be distributed with your distribution of PHP 5. If not, you can grab a copy from http://pecl4win.php.net.

Once we reach this stage, the next step is to try installing a package. Let's install Savant3, an excellent template engine for PHP 5+ that utilizes the elegance of PHP itself as a templating language.

$ pear c pear.ini channel-discover savant.pearified.com
$ pear c pear.ini remote-install savant/Savant3

If everything works, you will see:

remote install OK: savant.pearified.com/Savant3-3.0.0

At this point, fire up your FTP browser and you'll see that the files were uploaded to /home/myuser/pear/php/Savant3.php and to the /home/myuser/pear/php/Savant3 directory.

Note

Errors about alpha/beta

If installation fails with a notice about preferred state, try appending -alpha as in:

$ pear -c pear.ini remote-install savant/Savant3-alpha

Note

This will work because it instructs the installer to temporarily ignore your preferred_state configuration variable and to instead download the latest alpha or more stable version. In other words, with a preferred_state of stable, if Savant3 version 3.2.0 stable is available, it will be installed. However, if version 3.2.1 alpha is available, a newer version, it will not be installed because its stability is too low. However, by appending -alpha, the installer is instructed to instead grab the newest version 3.2.1 and install that version.

You may be thinking, how does this differ from just extracting the files and uploading them manually? The answer becomes apparent when managing more complex packages like DB_DataObject or LiveUser. Both of these packages have dependencies that must be installed in order to work. Although it is possible to manually install them and upload, it is very easy to forget a dependency. Worse, the entire process has to be repeated upon upgrade.

Installing DB_DataObject with its dependency on PEAR, Validate, and DB is as simple as:

$ pear c pear.ini remote-install o DB_DataObject

The same is true of upgrading:

$ pear c pear.ini remote-upgrade o DB_DataObject

Uninstalling is also simple, and responds to the full strength of the PEAR installer's dependency validation:

$ pear c pear.ini remote-uninstall DB_DataObject

Note

The rsync Method

If you are developing a complex website for a customer who has money, it may be best to develop on an identical machine with identical software and hardware configuration. Set up the entire website locally, and synchronize it with the remote website using rsync. This still works well with using source control and a PEAR-installable package, as development should be synced with discrete package versions.

Brett Bieber Dec 14, 2006

I recently finished a book on the PEAR installer written by Greg Beaver. The book itself is an excellent read for anyone who develops installable PHP libraries or applications, and one I would highly recommend for anyone interested in building small to large PHP web applications.Throughout the book, Greg demonstrates the complex features of the PEAR installer and package description file (package.xml) to guide you through understanding methods of distributing, installing, and maintaining PHP (and other) projects. The book is filled with real world examples and working applications from the guy who (seriously) 'wrote the book' on the PEAR installer.To anyone who is building distributed PHP applications or reusable libraries, this book is a must have for understanding release deployment strategies and how they are managed with powerful ease. The author knows his stuff, and has used every one of the examples within real word applications. The book has everything from "Hello World" installable applications to a full blown source code repository and distribution system through PEAR channels.With the book you will have all of the necessary information to build and maintain your complex PHP applications and easily distribute them across many servers, clients, or the open source community.If you're at the point in your application development where the unzip-and-go distribution method has reached its limit (typically the first bug after the first zip), the time has come to start building installable PEAR packages and to take advantage of all the capabilities the PEAR installer offers.Despite maintaining my own PEAR channel server (...........) for over a year now, I still found plenty of information to continue the ease with which the PEAR installer offers. So even if you are an experienced PEAR developer, the book is still a good read and shelf reference.I highly recommend the book, check it out.

Amazon Verified review

Travis Swicegood Jun 11, 2007

"Isn't PEAR just a bunch of packages you can install?" That's the question you'll receive most of the time if you ask a PHP developer if his software can be installed through the PEAR Installer. There's been a lot of work happening in PEAR that's culminated most recently in the PEAR elections and the announcement of Pyrus - PEAR 2. A major force behind all of these changes, including work on the PEAR Installer, is Greg Beaver. With this book, he can claim "he wrote the book on PEAR". Not that anyone could have disagreed with him before getting this book published. :-)This past weekend I read through the PEAR Installer Manifesto. For anyone who's not familiar the PEAR installer and how it can be used in projects outside of PEAR, I would point them to this book. It's only six chapters long, but it walks through the ways to use the PEAR Installer to enhance your projects - large or small, open or closed source, free or pay. This book covers the basics of what the PEAR Installer is, how to use it to distribute your own packages, and explains how to deploy a website using the installer. The book closes out with the two chapters that make this book a must read to someone already familiar with the PEAR Installer, but not familiar with what it is capable of: a chapter on PEAR channels and one on embedding the PEAR installer.A PEAR channel isn't a difficult thing to setup; there are blog posts aplenty on the topic. This chapter fill in the gaps in those posts answering the "why" to how things are done. I've setup my own channel before, but I hadn't investigated the internals to figure out exactly how everything ticked. Chapter 5 - Releasing to the World: PEAR Channels, fills in the gaps and gives you a thorough understanding of what makes a channel tick.Chapter 6 - Embedding the PEAR Installer: Designing a Custom Plug-In System, discusses several methods of handling plug-in systems then demonstrates how to create one using the PEAR Installer as a base. This chapter really starts to show exactly how powerful the installer can be once you start to re-purpose it, making it more than the command line tool we all use to download and install code. Thinking of the possibilities this introduced, I actually got giddy. Yes, I know... I'm a geek.This is a four star rating, so there were a few things that weren't exactly what I had hoped for. I hoped this would serve as a full reference to the installer. While this book takes you a lot of great jumping off points, it doesn't have the thoroughness I wanted. There are areas where the complexity of the code you're calling isn't covered in depth and you're left with a "this is all you'll need to know for this task" type comment. It took a visit to Greg's PEAR channel to fully understand how to package a custom file role. The book demonstrated the required PHP for the role and showed the custom XML, but didn't explicitly state that they were to be packaged together or how they were to be packaged. An appendix offering an in-depth overview of the code related to the installer would be a great addition to this book. With the recent news of Pyrus, that might be outdated before it could be ready though.I would have liked to have seen a more in-depth comparison to competing methods of building/packaging software. Instead, the only alternative that is discussed at any length is "unzip and go". It would have been interesting to see the comparison of the PEAR Installer to a traditional build system - such as PHP's phing or Java's Ant - and to explore using the installer inside a phing/Ant environment and how they could compliment each other. For example, using phing to handle the build process, while using PEAR channels and the installer to handle distribution and installation.This book is definitely worth the read for anyone interested in the PEAR Installer and understanding what it is capable of. The absence of a full reference to the installer code and no mention of viable alternatives to handle packaging are the only things that kept me from rating this book at 5 stars.

PJS5 Aug 11, 2010

I bought this book because I found PEAR rather confusing. The first time I read it I was bewildered so I thought I must have missed something and read it again but found myself none the wiser. I was hoping it would clarify things, teach me how to create my own PEAR packages and how to use PEAR to deploy apps etc. Instead the book seems to just talk about how great and simple PEAR is. It prefers to talk about PEAR in a general sense, offering no real guidance on how to actually use it for anything. The instruction that is present is very basic and already prominent on the PEAR website. A complete waste of time.

The PEAR Installer Manifesto: The PEAR Installer maintainer shows you the power of this code management and deployment system to revolutionize your PHP application development

What do you get with Print?