PEAR—the PHP Extension and Application Repository—was set up in 1999 by one of the PHP project's most respected and longest-serving contributors, Norwegian Stig Sæther Bakken. Its principal purpose is to provide an officially sanctioned library of open-source components contributed by PHP architects from all over the world, as well as an integrated means for installing those components into installations of PHP.
Those with experience of PERL may well draw similarities to the Comprehensive Perl Archive Network (CPAN), and would be right to do so. PEAR borrows many of the excellent features offered by CPAN, including the detection and automatic installation of dependent components when installing modules.
The components—or packages—within the PEAR network cover a myriad of functionality, including database connectivity, support for reading and writing unusual file formats, and widgets for generating complex HTML. Many components feature XML support, meaning you can put to use the skills you learned in Chapter 11.
In addition, PEAR provides a set of coding standards to which its contributors must adhere, which we examine shortly.
How is PEAR Structured?
The PEAR Project is divided into a number of missions:
- A library of packages, each representing a discrete area of functionality.
- The PEAR Package Manager, used for installing and removing these packages from an installation of PHP.
- The PHP Foundation Classes (PFC), a subset of the PEAR repository consisting of modules of a highly stable and thoroughly tested nature, which are included in a standard PHP installation.
- The PHP Extension Community Library—PECL—a library of components written in C (rather than native PHP), which has just recently become a project in its own right (see http://pear.php.net for more information).
- The PEAR Coding Standards, which we'll explore later in the chapter.
Any single package found in the PEAR repository is almost always distributed as a class, a concept to which you've been introduced in the preceding two chapters. Because the packages are designed as reusable, modular components, an object-oriented methodology makes a great deal of sense.
The PHP Foundation Classes
The PHP Foundation Classes (PFC), which are included by default in a normal installation of PHP, offer a number of essential toolkit routines beyond the basic intrinsic functionality of PHP. Although still, strictly speaking, unofficial, their common use in PHP applications is considered standard and accepted.
Packages within PFC generally have large scopes of use, rather than concerning themselves with, for example, obscure database platforms or file formats. Furthermore, such packages are always considered stable. At the time of this writing, some of the foundation classes distributed with PHP5 include the Mail class, an OS Guess class for determining the host operating system in PHP, and classes for making socket connections to other network hosts. Some of these classes may seem a little obscure in their own right, but nonbundled PEAR classes often make substantial use of them. By distributing them with PHP, the Package Manager does not have to install them on your behalf when you install a PEAR class that requires them. The PFC classes are always optimized for the version of PHP with which they are bundled; were it left to the Package Manager to download a copy, obscure incompatibilities between versions of PHP and versions of the PFC classes might start to cause problems. Explicitly tying PFC classes to distributions provides a common interface to the core of PHP such that non-PFC PEAR classes do not have to concern themselves with any differences between PHP versions.
If you are curious to know which modules are included as part of the Foundation Classes, check out the /usr/local/lib/php (Unix) or C:\PHP\PEAR (Windows) folder on your fresh PHP installation. Documentation for usage of these classes resides, like any other PEAR class, on the PEAR Web site at http://pear.php.net.
As these packages are included in a standard installation of PHP, you should not need to install them by hand, unless you explicitly requested they not be installed when you set up your development environment.
In theory, you can keep them up-to-date by using the PEAR Package Manager (more on this shortly), but in practice they are upgraded as and when new versions of PHP become available.
The PHP Extension Community Library
The PHP Extension Community Library or PECL (pronounced pickle) was originally a subset of the PEAR repository consisting of components written in C, rather than in native PHP. The rationale behind such components is usually the need for speed; compiled C often works out a lot quicker than PHP, particularly for mathematically intensive operations. PECL offers a means for component developers to avail themselves of the speed and power of C, whilst continuing to provide an interface to those components through standard PHP syntax.
PECL has recently evolved into a project in its own right, completely separate from PEAR—although it does retain the layout and politics of PEAR.
PECL is outside the scope of this chapter; however, familiarity with PEAR should leave you in good stead to tackle PECL should you want to do so. A good starting point is the project's Web site: http://pecl.pear.net.
The PEAR Package Manager
Many of the packages in the PEAR repository have dependencies. A dependency is the existence of a requirement for one class to be installed in order for another to function successfully. For example, a PEAR component that provides the capability to perform HTTP POST requests may depend on the existence of a generic HTTP functionality package. That package may in turn depend on a TCP/IP abstraction package, and so on.
As you can tell, starting with a fresh PHP installation and installing all necessary dependencies to make your class of choice function correctly could be immensely difficult to do by hand. The process is made much easier by means of the PEAR Package Manager.
The Package Manager provides a wealth of functionality for managing the insurgence of PEAR into your PHP setup, but its principal purpose is to allow you to install and remove PEAR packages with ease.
It is dependency-aware, which means that when you ask it to install a particular package that depends on one or more other packages, it kindly installs those dependent packages for you. It's also aware of the hierarchy of dependency, so it ensures that those packages are installed in the correct order.
Installing packages using the PEAR Package Manager is covered later in this chapter.
Recapping PEAR Standards
We discussed coding standards in Chapter 6, but let's just review the stylistic conventions used in this book's sample code.
The "correct" way to write code is something that's been debated for the last 30 years or so, without any particular common consensus having been reached. PHP is somewhat fortunate in that as a relatively youthful language, there has not been time for the kind of stylistic divergence witnessed in other languages. In this book, all of the authors decided that any example code we write would follow the standards set out by PEAR—known as the PEAR coding standards (PCS); that is to say, we'd stick to the same standards in our code as that to which authors of packages submitted to PEAR are required to adhere.
Indeed, should you ever want to try your hand at submitting your own work to PEAR so that others might benefit from it, you will need to adhere to them, too, so it's not a bad thing to get into the habit straightaway.
The PEAR Web site goes into great detail on the subject of coding standards, so we'll just explore some of those here. The following sections should get you into the right habits, in case you aren't already in them.
Control Structures, Comments, and Indenting
PEAR dictates that all code should be indented appropriately according to its context by using a suitable number of spaces (not tabs). In the case of PEAR, it's four spaces.
You may be able to configure your editor of choice such that when the tab key is pressed, four spaces are rendered instead of an actual tab character.
As well as being indented, PEAR requires that constructs err on the side of verbosity. For example, if a parenthesis is optional but its inclusion improves clarity, then its inclusion is required. White space should be used only to separate out distinct lines and thoughts, and where it is included for reason of clarity, it should be kept as minimal as possible.
Curly braces should always be used in control structures (while/if/switch/for/foreach) even when there is only a single line within the block, and that's why the use of braces is not required by the PHP interpreter. This improves clarity immeasurably. The opening brace should always begin on the same line as the start of the control block. The closing brace should fall on a new line. PEAR does not comment on whether it is appropriate to suffix the closing brace with a semicolon.
Starting and finishing blocks of PHP by means of the <?php and ?> operators should always include the optional letters php for reasons of clarity.
Comments are encouraged wherever it would improve readability to include them. Avoid using the # comment predicate, even though PHP allows it; instead, opt for C-style // (for a single-line comment) or /* and */ (to begin and end a multiline comment).
Here is an example of a PEAR-compliant control structure:
Function Calls and Definitions
When calling a function, there should be no space placed between the name of the function and its opening parenthesis prior to its argument list. If there are no arguments to be passed, a blank list should be used by opening and then immediately closing parentheses, as this example shows:
<?php $strMyVar = myFunction($strA, $strB, $strC); $strAnotherVar = anotherFunctionWithNoParameters(); ?>
When declaring your own functions, the rules for braces in control structures are changed slightly; the starting brace for the block should begin on a new line, immediately after the function name and argument list definition. Here's an example of that syntax:
<?php function myFunction($strArg1, $strArg2) { return($strMyResult); }; ?>
In the argument list, arguments that are optional should be designated by using the $strArg = " methodology. Optional arguments should always be last in the argument lists.
Finally, functions should always return a value if it is meaningful to do so. At the very least, a function should return whether or not it was successful in its designed endeavors.
Naming Conventions
Naming of variables, classes, and functions in languages that have weak typing (are loosely typed), such as PHP, is of immense importance.
PEAR conventions require the following:
- Classes should begin with a capital letter, such as Publisher. If the class has hierarchical placement within PEAR, this should be reflected in the name, such as HTML_TreeMenu, where TreeMenu is a component within the HTML hierarchy of PEAR.
- Functions should be named using the name of their parent package followed by an underscore (if applicable), and then a descriptive name without underscores; the descriptive name should have its first word or syllable lowercase, with the first letter of each subsequent word or syllable (as appropriate) capitalized (XML_RPC_serializeData) Private member functions or variables of classes accessed only from inside other methods of that class should be prefixed with an underscore ($this->_currentStatus).
- Constants should be capitalized, with underscores used to separate words, such as $HOME_DIRECTORY.
PEAR does not voice an opinion about naming convention for working variables. Many PEAR authors have adopted Hungarian Notation whereby the expected contents of a variable are alluded to in its name; for example, $strMyVariable is designed to hold a string, and $intMyNumber is for holding a number.
The authors strongly suggest you adopt this method, except where it is awkward to do so; for example, counter variables for for loops might reasonably make use of $x, $y, and $z, but these should never be used for variables holding meaningful integers.
