Section 12.8. Dependencies

12.8. Dependencies

An important benefit of using PEAR is code reuse. However, when you re-use code from a package system, there will be dependencies between packages. These dependencies need to be expressed in the package description to inform users about them.

12.8.1. Element: <deps>

Element name:	deps
Attributes:	none
May occur in:	release (optional)

This element is a container for the <dep> element.

12.8.2. Element: <dep>

Element name:	dep
Attributes:	name (required) type (required) rel (optional)
May occur in:	deps (required)

The dep element describes a single dependency.

12.8.2.1 name Attribute

This is the target of the dependency. For pkg dependencies, the name attribute contains the package name; for ext dependencies, it contains the extension name, and so on.

12.8.2.2 type Attribute

Valid dependency types are

• php. PHP version dependency; name is ignored.

• ext. Extension dependency (extension must be installed).

• pkg. PEAR package dependency.

• prog. External program dependency; name is the name of program (without suffix).

• ldlib. Build-time library dependency.

• rtlib. Run-time library dependency.

• os. Operating system dependency.

• websrv. Web server dependency.

• sapi. SAPI backend dependency.

Dependency types are described in detail later.

12.8.2.3 rel Attribute

rel is short for relation and tells if and how the version attribute is compared. Possible values include

• has. Default. No version comparison; target just needs to be installed/exist/be true.

• lt. Installed version must be less than specified.

• le. Installed version must be less than or equal to specified.

• gt. Installed version must be greater than specified.

• ge. Installed version must be greater than or equal to specified.

• eq. Installed version must be equal to specified.

• ne. Installed version must be different than specified.

12.8.2.4 optional Attribute

This attribute lets you specify that a dependency is not a drop-dead requirement for installing the package, but rather something that would provide enhanced functionality. You may leave it out, or give it the value yes or no.

12.8.3. Dependency Types

The PEAR Installer supports different types of dependencies. A package may require another package, that some PHP extension is available, a specific operating system and so on. This is expressed with the following dependency types.

12.8.3.1 PHP Dependencies

PHP dependencies express what version of PHP the package requires.

It is good practice to be conservative about PHP version dependencies. If you release the package to a lot of people (such as through pear.php.net), there will always be some PHP upgrade lag among your package's potential users. If you require bleeding-edge PHP, fewer people will be able to use your package.

12.8.3.2 Extension Dependencies

This type of dependency expresses that the package needs a specific PHP extension. During package installation, the installer checks whether the extension is loaded, or if it can be loaded from the default extension directory. If not, the dependency fails.

12.8.3.3 PEAR Package Dependencies

PEAR package dependencies say that this package requires another package. This type of dependency is checked by looking up the PEAR package registry. Because the registry information is stored inside php_dir, this means that the required package must be installed in the same php_dir as the depending package.

12.8.3.4 External Program Dependencies

When a PEAR package relies on an external program that is not part of PHP or PEAR, this is expressed with an external program dependency. During installation, the installer checks if it can find the required program in the current PATH; if not, the dependency fails.

12.8.3.5 Operating System Dependencies

Most packages run on all operating systems, but some are OS specific, such as the "printer" package. This is specified with an OS dependency.

12.8.4. Reasons to Avoid Dependencies

Dependencies are a necessary mechanism for expressing that Package A requires B to function. Although reuse through components is a good practice in theory, it comes at the risk of creating run-way dependencies. These dependencies are not literally out of control, but they aggregate more dependencies than intended or reasonable.

So, what is the problem with that? Aren't dependencies taken care of by the installer? Yes, but managing dependencies can become time-consuming and complex. If badly managed, complex dependencies will eventually require more time spent managing dependencies and builds than time spent on development. Often, the biggest motivation for re-use is saving development time, but if re-use becomes too complex, the economics of re-use suddenly fail, and, in a fit of irony, you would save time writing your own.

Use dependencies consciously and wisely. If the difference is just a few lines of code or the fact that some package wraps some PHP extension without offering anything else you need, think twice before adding a dependency.

As an example, imagine that Package A has dependencies to Packages B and C, and these have dependencies to Packages D, E, and F, respectively (see Figure 12.2).

Figure 12.2. Hairy dependencies.

In Figure 12.2, the boxes are packages, and the arrows are dependencies between them. A depends on B and C, and so on. As we can see, the B dependency adds four dependencies in practice: B, D, E, and G, while the C dependency adds two: C and F. It may be worth looking at whether the B dependency is strictly necessary, because it causes so many extra dependencies.

12.8.5. Optional Dependencies

Use optional dependencies (<dep optional="yes" ...> in package.xml) for packages or extensions that would add functionality to your package without being absolutely required.

For example, if you have a file-handling package, you could use an optional dependency to the zlib extension and handle .gz files only if the zlib extension is available.

12.8.6. Some Examples

This example shows a package.xml snippet with dependency definitions taken from the DB package:

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

DB requires PHP 4.2.0 or newer, as well as release 1.0b1 or newer of the PEAR package.

Here is a an example demonstrating optional dependencies:

 <deps>   <dep type="php" rel="ge" version="5.0.0" />   <dep type="pkg" optional="yes">Cache_Lite</dep>   <dep type="ext">zlib</dep> </deps> 

This package requires PHP 5.0.0 or newer with zlib loaded, and offers extra features if the Cache_Lite package is installed.