PHP's PEAR on Mac OS X
Pages: 1, 2

Using the PEAR Package Manager

With the Package Manager installed and configured, to see what packages the installer added to your system to satisfy its own dependencies, type:

% pear list

For a list of all packages available for installation with their version information and the current versions that you have installed, enter:

% pear list-all

All packages:
=============
+----------------------+--------+-------+
| Package              | Latest | Local |
| apd                  | 0.2    |       |
| PHPUnit              | 0.4    |       |
| Var_Dump             | 0.2    |       |
| Archive_Tar          | 0.9    | 0.9   |

For information about a specific package that's installed locally, use the pear info command:

% pear info XML_Parser

And you should see information similar to the following:

About XML_Parser-1.0
====================
+-----------------+------------------------------------------------+
| Package         | XML_Parser                                     |
| Summary         | XML parsing class based on PHP's bundled expat |
| Description     | This is an XML parser based on PHP's built-in  |
|                 | xml extension. It                              |
|                 | supports two basic modes of operation: "func"  |
|                 | and "event". In "func"                         |
|                 | mode, it will look for a function named after  |
|                 | each element                                   |
|                 | (xmltag_ELEMENT for start tags and             |
|                 | xmltag_ELEMENT_ for end tags), and             |
|                 | in "event" mode it uses a set of generic       |
|                 | callbacks.                                     |
| Maintainers     | Stig Saether Bakken <stig@php.net> (lead)      |
| Version         | 1.0                                            |
| Release Date    | 2002-05-09                                     |
| Release License | PHP License                                    |
| Release State   | stable                                         |
| Release Notes   | First independent release                      |
| Release Deps    | PHP >= 4.0.4pl1                                |
| Last Modified   | 2002-11-23                                     |
+-----------------+------------------------------------------------+

To get information for a package that you don't have installed locally, use the pear remote-info command:

% pear remote-info Net_Portscan

To install a new package, use the pear install command:

% pear install Net_Portscan

and to remove an installed package, use pear uninstall:

% pear uninstall Net_Portscan

Keeping your packages up to date with the latest releases either individually or en masse is done with the pear upgrade and pear upgrade-all commands:

% pear upgrade Net_Portscan

% pear upgrade-all

For now, install the Net_Portscan package by entering:

% pear install Net_Portscan

Were going to be using that in the next section when we cover using PHPDoc to generate the developer documentation for a package.

Generating Developer Documentation from PEAR Packages

Borrowing from Perl's PerlDoc and Java's JavaDoc, PHP has an application (natively coded in PHP, of course) called PHPDoc that will generate documentation for an installed package that's derived from that package's source code. To make use of PHPDoc, first make certain that it's installed using

% pear list

and look for the PHPDoc package. If it's not installed, install it using the PEAR Package Manager by issuing the

% pear install PHPDoc

command.

Before beginning the document generation, it's important to clarify that the word preceding the underscore of the package name indicates its subdirectory of the PHP Code Directory. When we initially set up the PEAR Package Manager, we specified that the PHP Code Directory should be located in the /usr/local/bin/share/pear directory. In the case of Net_Portscan, that means that the Portscanner class can be found in the Net subdirectory of /usr/local/bin/share/pear. Likewise, the XML_Parser can be found in the XML subdirectory. Now cd into to the Net subdirectory and do a listing of that directory's contents:

% cd /usr/local/share/pear/net 
% ls

You should see a listing of the Portscan.php package in addition to a couple of other packages. To generate the Portscan documentation, call PHPDoc with the s flag indicating the directory and filename of the package that you want to generate the documentation for. In the case of Net_Portscan, that should be:

% PHPDoc -s ./Portscan.php

The ./ preceding Portscan.php tells the Installer to use your current directory and within it the Portscan.php file. PHPDoc will run for a few seconds and you'll see output like this:

Parser starts...
... preparse to find modulegroups and classtrees.
... parsing classes.
... parsing modules.
... writing packagelist.
Parser finished.
Starting to render...

API Docs for ./Portscan.php done in /usr/local/share/pear/docs

4 seconds needed

Now use your preferred browser to open the file:

file://localhost/usr/local/share/pear/docs/index.html

Remember that this is beta software and the initial PackageList may be empty. That's fine because we can get to the information that we need by selecting ClassTrees and choosing the Net_Portscan link. You now have detailed documentation of the Net_Portscan class.

In the Public Method Summary, you'll see a method description that reads:

array  checkPortRange(string $host, integer $minPort, integer $maxPort,
[ integer $timeout ]) 
Check a range of ports at a machine

The first item, array, indicates the data type that this method will return, followed by the methods name (checkPortRange in this instance), followed by the methods list of parameters. The data type prepending each parameter's name is the data type that is expected of that parameter. Parameters in square brackets are optional.

Using PEAR Classes in Your Applications

Here's the code that we'll use to explore how to include and use installed PEAR packages:

<? 

  require_once("Net/Portscan.php");

  $scanner = new Net_Portscan;
  $host = "www.example.com"; 
  $minPort = 50; 
  $maxPort = 100;
	
  $activePorts = $scanner -> checkPortRange( $host,  $minPort,  $maxPort);
	
  foreach($activePorts as $portnumber => $status) { 
    if ($status) { 
      echo "port number $portnumber is open. <br />"; 
    } 
  }

?>

First we include the Portscan.php package by specifying the PEAR subdirectory and filename that it resides in. We're able to get away without specifying the complete path because we added /usr/local/share/pear to PHP's search path when we modified the php.ini. This will also be of use to us if were doing the development locally and upload it to a server for production that doesn't have the PEAR repository in the same location as it is on our local machine. By modifying the php.ini on the server, its PEAR repository can be located anywhere on that machine and our code will still work without modification.

We then create a new instance of the class and set the $host, $minPort, and $maxPort variables. We then call Net_Portscan's checkPortRange method. We know that $activePorts is going to be an array from the online documentation that we generated. Finally, we loop over $activePorts and echo any ports that were returned as active.

Conclusion

The PEAR project has made good strides toward being a working solution to the problem of distributing and versioning solid PHP packages. They're still working out some of the kinks and new features are being added daily, so some of the instructions here may be outdated by the time that you get a chance to use them. For additional, updated information on PEAR, check out its web site and consider subscribing to the PEAR mailing lists via this form.

Author's Note: PHP 4.2.3 is the version that this article is based on. The release of PHP 4.3 eases of the use of PEAR on Mac OS X as the PHP file at /usr/local/bin is now part of the default installation if you build PHP from source. It's unclear if Marc Liyanage of www.entropy.ch will be including that file in his packaged binary releases. I'm watching his site and when he releases his PHP 4.3 binary, I'll update this article to reflect any changes that may be required to get PEAR up and running using it.

Jason Perkins has been involved with Web design and development since 1996 and has recently started writing and technical editing.

---

Return to the Mac DevCenter.