CHAPTER 12 – BUILDING PACKAGES

In this section, you explore the PEAR package system from the inside, learning how to build your own packages and how to make the most out of the installer. Following is an example package containing a PHP class, a command-line script, a regression test, and a package description file.

PEAR Example: HelloWorld This is the minimal example, a single PHP source file implementing a class called HelloWorld: <?php /** * Hello World class. The ubiquitous example. * @package HelloWorld */ class HelloWorld { function HelloWorld($html = true) { if ($html) { print "Hello, World!<br />n"; } else { print "Hello, World! n"; } } } HelloWorld.php Here is a command-line script called "hello" for demonstration: #!/bin/sh exec php -d output_buffering=1 $0 $@ <?php ob_end_clean(); require_once "HelloWorld.php"; $hello = new HelloWorld(false); hello It is a good idea to write regression tests for your classes sooner rather than later. This example regression test verifies that the HelloWorld construc- tor's $html parameter works like intended: --TEST-- HelloWorld test --FILE-- <?php include dirname(__FILE__).'/../HelloWorld.php'; new HelloWorld(false); new HelloWorld(true); ?> --EXPECT-- Hello, World! Hello, World!<br /> HelloWorld.phpt A .phpt file is split into sections that start with a single line containing --SECTION--. The following sections exist (see Table 12.2).

Table 12.2 Test Section Headings Section Description TEST* Short description of the test. FILE* Actual test code. EXPECT* The exact output that the test code should print. EXPECTF Expected output with some placeholders. EXPECTREGEX Regular expression matching expected output. GET HTTP GET variables (for example, a=foo&b=bar). POST HTTP POST variables; same format as GET. SKIPIF If this code snippet prints "skip," the test is not executed but marked as skipped. ARGS Command-line parameters; space-separated. INI Php.ini directives; directive=value, one per line. The sections marked with "*" are required; the rest are optional. The EXPECTF section uses these placeholders (see Table 12.3). Table 12.3 EXPECTF Placeholders Placeholder Description %e Platform directory separator, typically "/" or "" %s Any string (not greedy) %i Any integer %d Any positive integer %x Any hexadecimal positive integer %f Any floating-point number %c Any single character To package this class into a proper PEAR package, you need a package description file called package.xml: <?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE package SYSTEM "http://pear.php.net/dtd/package-1.0"> <package version="1.0"> <name>HelloWorld</name> <summary>Simple Hello World Package</summary> <description> This package contains a class that simply prints "Hello, World!". </description> <license>PHP License</license> <maintainers> <maintainer> <user>ssb</user> <role>lead</role> <name>Stig S. Bakken</name> <email>stig@php.net</email> </maintainer> </maintainers> <release> <version>1.0</version> <state>stable</state> <date>2004-04-24</date> <notes> First production release. </notes> <filelist> <file role="php" name="HelloWorld.php"/> <file role="script" name="hello"/> <file role="test" name="01-HelloWorld.phpt"/> </filelist> </release> </package> A comprehensive reference of all the XML elements of the package description format is found in "The package.xml Format" section later in this chapter.