Using PEAR Packages in Applications

Setting Up php.ini

To use PEAR packages installed through the use of the pear command (and therefore located in the directory set up for PEARusually /usr/local/lib/php or C:\php\PEAR, depending on the system), the only change to be made to php.ini is to set the include_path variable and point it to the correct directory.

For *NIX systems, this may look something like this:

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

On Windows systems, it may look like this:

include_path = ".;C:\php\PEAR"

Notice the use of the dot (.) at the beginning of the path. This dot tells PHP to include the current working directory (of any running script) in the include path, as well as any other directories that may be specified in include_path.

TIP To specify other directories in *NIX, use a colon (:) to separate the values; on Windows, use a semicolon (;).

Including the Package

Including the PEAR package is simple. Following the PEAR Coding Standardsthough it is not necessary to adhere to these standards in code that is not being developed for PEARuse require_once() to unconditionally include a PEAR package; use include_once() to conditionally include one.

require_once 'DB.php';

The name PEAR::DB itself suggests it is at the top level of PEAR. Therefore, no further path is required to include it. As long as the include_path in php.ini correctly points to the PEAR installation, all is well. If the included package were PEAR::Net_SMTP, the statement may look like this:

require_once 'Net/SMTP.php';

NOTE Because require_once() and include_once() are PHP language statements and not functions, the parentheses are not required.

Using Packages Not Installed Through pear

Sometimes it may be necessary to use a PEAR package from directly within an application. Such an example is an application intended for distribution. In this case, the PEAR installation on multiple platforms cannot be relied upon. It may not have the correct packages installed, or it may not be installed at all. In a case like this, the package need not be installed through the PPM as discussed earlier.

PEAR packages are made to live together, so to speak, in a specific directory structure that is defined in the package.xml file accompanying every package. For the most part, this XML file goes unnoticed to those installing a package through the PPM. However, it is this very file that tells the PPM how to install the package and how it relates to other packages in the way of dependencies. For this reason, every PEAR developer is required to include package.xml in the package release.

If installing a package without the use of the PPM and from within the structure of an application, this file may prove useful. For example, assuming that all PEAR packages in an application will be installed off the root of the application in the lib/pear directory (a fictional directory for an imaginary application), download the package from the PEAR website (as described earlier) and unzip it.

Now, open package.xml to look at the package's dependencies and file structure. Without going into too much detail on how this file is arranged, note that the areas of greatest concern are the <deps> and <filelist> tags.

The <deps> tag for PEAR::DB gives the following information:

<deps>
  <dep type="php" rel="ge" version="4.2.0"/>
  <dep type="pkg" rel="ge" version="1.0b1">PEAR</dep>
</deps>

For PEAR::DB, two dependencies are identified and the relationships are noted as ge, meaning that the versions of these items must be greater-than-or-equal-to that in the version attribute. Thus, to use PEAR::DB, PHP 4.2.0 or greater must be installed, as well as PEAR 1.0b1 or greater.

Because PEAR::DB is being installed apart from the PPM, there is no dependency check; it is up to the developer to ensure that PEAR >= 1.0b1 is installed in a location that DB can find.

The <filelist> tag holds the other important information for installing a PEAR package. It describes the file structure of the package in relation to the other packages in PEAR. Continuing with the PEAR::DB example, the <filelist> tag displays the following:

<filelist>
  <file role="php" baseinstalldir="/" name="DB.php"/>
  <file role="php" name="DB\common.php"/>
  <file role="php" name="DB\dbase.php"/>
  <file role="php" name="DB\fbsql.php"/>
  <file role="php" name="DB\ibase.php"/>
  <file role="php" name="DB\ifx.php"/>
  <file role="php" name="DB\msql.php"/>
  <file role="php" name="DB\mssql.php"/>
  <file role="php" name="DB\mysql.php"/>
  <file role="php" name="DB\mysqli.php"/>
  <file role="php" name="DB\oci8.php"/>
  <file role="php" name="DB\odbc.php"/>
  <file role="php" name="DB\pgsql.php"/>
  <file role="php" name="DB\sybase.php"/>
  <file role="php" name="DB\storage.php"/>
  <file role="php" name="DB\sqlite.php"/>
  ...
</filelist>

Notice that the role of these files is "php." These are the files that are important to install for the package. Other common roles include "doc" and "test," which can be excluded from the application, but can be helpful in learning how the package works. Following the structure given in <filelist> and given the lib/pear base location of all PEAR packages for this application, DB.php would go to lib/pear, whereas all the other files in the DB package would go to lib/pear/DB.

Finally, now that the files have a home and the dependencies have been satisfied, the best method for configuring the application to correctly use the PEAR packages is to modify the include_path from the application level. This will ensure that the code within the PEAR packages can find and include any files upon which it is dependent. To do this, place the following code at the top of all files that will use any of the PEAR packages, or place it in a global configuration file:

$include_path = ini_get('include_path') . PATH_SEPARATOR . '/path/to/lib/pear';
ini_set('include_path', $include_path);

This will add the application's lib/pear directory to the include_path so that the PEAR packages may be included as described in the section "Including the Package."

TIP To find out more about the package.xml file definition, visit http://pear.php.net/manual/en/developers.packagedef.php.