PHP's PEAR on Mac OS X
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.
Prev [1] [2]
