Docbook2Wiki: Initial conversion from Docbook

2008-03-06T22:28:45Z

Initial conversion from Docbook

New page

{{PHP Cookbook/TOC}}

== Introduction ==

PEAR is the PHP Extension and Application Repository, a collection of open source classes that work together. Developers can use PEAR classes to generate HTML, make SOAP requests, send MIME mail, and a variety of other common tasks. A pear is also a tasty fruit.

To find general information on PEAR, read the PEAR manual; to discover the latest PEAR packages, go to ''http://pear.php.net''. A summary of each week's happenings can be found at ''http://pear.php.net/weeklynews.php''.

Only a few core PEAR packages are bundled with the main PHP release. However, part of PEAR is a program called, appropriately enough, ''pear'' , that makes it easy for you to download and install additional PEAR packages. This program is also known as the PEAR package manager. [[PHP Cookbook/PEAR#Using the PEAR Package Manager|Recipe 21.2]] shows how to use the PEAR package manager.

PEAR packages divide into two major parts. One is the PHP Foundation Classes — object-oriented code written in PHP that's high quality and usable in production environments on any platform and web server. The other is PECL, or PHP Extension Code Library. PECL, pronounced pickle, is a series of extensions to PHP written in C. These extensions are just like ones distributed with the main PHP release, but they're of more specialized interest — such as an interface to the XMMS multimedia player or the ImageMagick graphics library.

Additionally, the PEAR package manager allows you to use the PEAR class management infrastructure with your personal projects. By creating your own packages that follow the PEAR format, your users can use ''pear'' to download and install the files from your project's web site.

This chapter explains how to find a PEAR package you may want to use and how to install it on your machine. Because PEAR has many classes, you need an easy way to browse them. [[PHP Cookbook/PEAR#Finding PEAR Packages|Recipe 21.3]] covers the different ways to find PEAR packages; once you've found a package's name, [[PHP Cookbook/PEAR#Finding Information About a Package|Recipe 21.4]] shows how to view package details and information.

Once you locate a class you want to use, you need to run ''pear'' to transfer the class to your machine and install it in the correct location on your server. Installing PEAR packages and PECL extensions are the subjects of [[PHP Cookbook/PEAR#Installing PEAR Packages|Recipe 21.5]] and [[PHP Cookbook/PEAR#Installing PECL Packages|Recipe 21.6]], respectively. [[PHP Cookbook/PEAR#Upgrading PEAR Packages|Recipe 21.7]] shows how discover if any upgrades are available to packages on your machine and how to install the latest versions. If you want to remove a package, see [[PHP Cookbook/PEAR#Uninstalling PEAR Packages|Recipe 21.8]].

Finally, [[PHP Cookbook/PEAR#Documenting Classes with PHPDoc|Recipe 21.9]] describes how PEAR developers can write classes that abide by PEAR's coding standards and how to document your class with PHPDoc.

PHP 4.3 includes the first stable release of PEAR. Earlier copies of PHP bundled versions of PEAR prior to PEAR 1.0, but ''pear'' and the other packages weren't guaranteed to work, as they were still in beta. If you are having problems using PEAR, you should remove any old files that may be interfering with the release version. This includes the ''pear'' application itself; it can't always upgrade itself to the latest release.

If you can't upgrade to PHP 4.3 and need to bootstrap a copy of PEAR onto your system, run the following:

% '''<nowiki>lynx -source http://go-pear.org | php -q</nowiki>'''
Welcome to go-pear!

Go-pear will install the 'pear' command and all the files needed by
it. This command is your tool for PEAR installation and maintenance.

Go-pear also lets you download and install the PEAR packages bundled
with PHP: DB, Net_Socket, Net_SMTP, Mail, XML_Parser.

If you wish to abort, press Control-C now, or press Enter to continue:

This downloads a PHP script from the PEAR web site and hands it to PHP for execution. The program downloads all files needed to run ''pear'' and gets you up and running.

On some Unix systems, you may need to run ''links'' instead of ''lynx''. If you have the command-line version of PHP installed, remove the <tt>-q</tt> flag to PHP; the CLI version automatically suppresses HTTP headers. If ''go-pear'' seems to hang, set <tt>output_buffering</tt> to <tt>off</tt> in your ''php.ini'' configuration file.

Installation on Windows is a two-step process:

C:\> '''<nowiki>php-cli -r 'readfile("http://go-pear.org");' > go-pear</nowiki>'''
c:\> '''php-cli go-pear'''

The ''go-pear'' script requires PHP 4.1 or greater. For the Windows installation, ''php-cli'' is the command-line version of PHP.

PHP installs PEAR by default, so if you're running PHP 4.3, you should be able to use PEAR without any additional setup.<ref>If you disable building the command-line version of PHP with <tt>--disable-cli</tt>, PHP doesn't install PEAR.</ref> Out of the box, PEAR installs ''pear'' in the same directory as ''php'' and places PEAR packages in ''prefix/lib/php''.<ref>This is probably ''/usr/local/lib/php''.</ref> To install PEAR in another directory, add <tt>--with-pear=DIR</tt> when configuring PHP.

Once a PEAR package is installed, use it in your PHP scripts by calling <tt>require</tt>. For example, here's how to include the <tt>Net_Dig</tt> package:

require 'Net/Dig.php';

If a package name contains an underscore, replace it with a slash, and add ''.php'' to the end.

Some packages may require you to include multiple classes, such as SOAP, so instead of requiring ''SOAP.php'', you include ''SOAP/Client.php'' or ''SOAP/Server.php''. Read the documentation to discover if a particular package requires nonstandard file includes.

Because PEAR packages are included as regular PHP files, make sure the directory containing the PEAR classes is in your <tt>include_path</tt>. If it isn't, <tt>include</tt> and <tt>require</tt> can't find PEAR classes.

To view instructions and examples showing how to use a particular PEAR class, check the PEAR Manual at ''http://pear.php.net/manual/en/packages.php'' or read the top section of the package's PHP files. For an example of a full-featured PEAR class in action, see the discussion of PEAR's database library in [[PHP Cookbook/Database Access#Connecting to a SQL Database|Recipe 10.4]].

== Using the PEAR Package Manager ==

=== Problem ===

You want to use the PEAR package manager, ''pear''. This allows you to install new packages, and upgrade and get information about your existing PEAR packages.

=== Solution ===

To execute a command with the PEAR package manager, type the command name as the first argument on the command line:

% '''pear'''
''command''

=== Discussion ===

Here's how to list all installed PEAR packages with the <tt>list</tt> command:<ref>In early versions of ''pear'', this command was <tt>list-installed</tt>.</ref>

% '''pear list'''
Installed packages:
= == == == == == == == == ==
+-----------------+----------+--------+
| Package | Version | State |
| Archive_Tar | 0.9 | stable |
| Console_Getopt | 0.11 | beta |
| DB | 1.3 | stable |
| HTTP | 1.2 | stable |
| Mail | 1.0.1 | stable |
| Mail_Mime | 1.2.1 | stable |
| Net_SMTP | 1.0 | stable |
| Net_Socket | 1.0.1 | stable |
| Net_URL | 1.0.4 | stable |
| PEAR | 0.91-dev | beta |
| XML_Parser | 1.0 | stable |
| XML_RPC | 1.0.3 | stable |
+-----------------+----------+--------+

For a list of all valid PEAR commands, use <tt>list-commands</tt> . Many commands also have abbreviated names; for example, <tt>list</tt> is also just <tt>l</tt>. These names are usually the first few letters of the command name. See [[PHP Cookbook/PEAR#phpckbk-CHP-21-TABLE-1|Table 21-1]] for a list of frequently used commands.

<div id="phpckbk-CHP-21-TABLE-1">
'''Table 21-1. PEAR package manager commands'''

{| border="1"
|-
! Command name !! Shortcut !! Description
|-
| <tt>install</tt> || <tt>i</tt> || Download and install packages
|-
| <tt>upgrade</tt> || <tt>up</tt> || Upgrade installed packages
|-
| <tt>uninstall</tt> || <tt>un</tt> || Remove installed packages
|-
| <tt>list</tt> || <tt>l</tt> || List installed packages
|-
| <tt>list-upgrades</tt> || <tt>lu</tt> || List all available upgrades for installed packages
|-
| <tt>search</tt> || None || Search for packages
|}
</div>

''pear'' has commands both for using and for developing PEAR classes; as a result, you may not need all the commands. The <tt>package</tt> command, for example, creates a new PEAR package. If you only run other peoples' packages, you can safely ignore this command.

Like all programs, if you want to run ''pear'', you must have permission to execute it. If you can run ''pear'' while running as root, but not as a regular user, make sure the group- or world-execute bit is set. Similarly, for some actions, ''pear'' creates a lock file in the directory containing the PEAR files. You must have write permission to the file named ''.lock'' located in that directory.

To find where your PEAR packages are located, run the <tt>config-get php_dir</tt> command. You can check the value of the <tt>include_path</tt> by calling <tt>ini_get('include_path')</tt> from within PHP or by looking at your ''php.ini'' file. If you can't alter ''php.ini'' because you're in a shared hosting environment, add the directory to the <tt>include_path</tt> at the top of your script before including the file. See [[PHP Cookbook/Web Basics#Setting Configuration Variables|Recipe 8.24]] for more on setting configuration variables from within PHP.

If you're behind a HTTP proxy server, configure PEAR to use it with the command:

% '''pear config-set http_proxy proxy.example.com:8080'''

You can configure PEAR package manager settings using:

% '''pear set-config'''
''setting value''

Here <tt>''setting''</tt> is the name of the parameter to modify and <tt>''value''</tt> is the new value. To see all your current settings, use the <tt>config-show</tt> command:

% '''pear config-show'''
Configuration:
= == == == == == == =
+---------------------+-----------------+-------------------------------------+
| PEAR executables | bin_dir | /usr/local/bin |
| directory | | |
| PEAR documentation | doc_dir | /usr/local/lib/php/docs |
| directory | | |
| PHP extension | ext_dir | /usr/local/lib/php/extensions/no-de |
| directory | | bug-non-zts-20020429 |
| PEAR directory | php_dir | /usr/local/lib/php |
| PEAR data directory | data_dir | /usr/local/lib/php/data |
| PEAR test directory | test_dir | /usr/local/lib/php/tests |
| HTTP Proxy Server | http_proxy | <not set> |
| Address | | |
| PEAR server | master_server | pear.php.net |
| PEAR password (for | password | <not set> |
| maintainers) | | |
| PEAR username (for | username | <not set> |
| maintainers) | | |
| Preferred Package | preferred_state | stable |
| State | | |
| Unix file mask | umask | 18 |
| Debug Log Level | verbose | 1 |
+---------------------+-----------------+-------------------------------------+

For a brief description of each configuration option, use the <tt>config-help</tt> command.

== Finding PEAR Packages ==

=== Problem ===

You want a listing of PEAR packages. From this list you want to learn more about each package and decide if you want to install the package.

=== Solution ===

Browse packages at ''http://pear.php.net/packages.php'' or search for packages at ''http://pear.php.net/package-search.php''. Use ''pear'' 's <tt>remote-list</tt> command to get listing of PEAR packages or the <tt>search</tt> command to search for packages.

=== Discussion ===

There are a few ways to review PEAR's packages. First, to browse the listings in a directory-style fashion, go to ''http://pear.php.net/packages.php''. From there you can burrow into each individual PEAR category.

Alternatively, you can search through the listings at ''http://pear.php.net/package-search.php''. The search page allows you to search by package name, author, category, and release date.

You can ask the PEAR package manager to provide you with a listing using the <tt>remote-list</tt> command:

% '''pear remote-list'''
Available packages:
= == == == == == == == == ==
+----------------------+---------+
| Package | Version |
| Archive_Tar | 0.9 |
| Auth | 1.0.2 |

...

| XML_Transformer | 0.3 |
| XML_Tree | 1.1 |
+----------------------+---------+

The short form of <tt>remote-list</tt> is <tt>rl</tt>.

To search for package names from the command line, use the <tt>search</tt> command:

% '''pear search auth'''
Matched packages:
= == == == == == == == ==
+-----------+--------+-------+------------------------------------+
| Package | Latest | Local | |
| Auth | 1.0.2 | 1.0.2 | Creating an authentication system. |
| Auth_HTTP | 1.0.1 | 1.0.1 | HTTP authentication for PHP |
+-----------+--------+-------+------------------------------------+

This does a case-insensitive search of package names and returns the package name, the latest version number, the version you have installed (if any), and a short description about the package.

=== See Also ===

[[PHP Cookbook/PEAR#Finding Information About a Package|Recipe 21.4]] to find out more information about a package.

== Finding Information About a Package ==

=== Problem ===

You want to gather information about a package, such a description of what it does, who maintains it, what version you have installed, and which license it's released under.

=== Solution ===

If the package is installed on your machine, use the PEAR package manager's <tt>info</tt> command:

% '''pear info Net_URL'''

Otherwise, use the <tt>remote-info</tt> command:

% '''pear remote-info SOAP'''

You can also view the package's home page on ''http://pear.php.net''.

=== Discussion ===

The <tt>info</tt> command provides summary information about a package:

% '''pear info Net_URL'''
About Net_URL-1.0.4
= == == == == == == == == ==
+-----------------+-----------------------------------------+
| Package | Net_URL |
| Summary | Easy parsing of Urls |
| Description | Provides easy parsing of URLs and their |
| | constituent parts. |
| Maintainers | Richard heyes <richard@php.net> (lead) |
| Version | 1.0.4 |
| Release Date | 2002-07-27 |
| Release License | BSD |
| Release State | stable |
| Release Notes | License change |
| Last Modified | 2002-08-23 |
+-----------------+-----------------------------------------+

If you don't have the package installed, ask the remote server for a description:

% '''pear remote-info Net_URL'''
Package details:
= == == == == == == == =
+-------------+-----------------------------------------+
| Latest | 1.0.4 |
| Installed | 1.0.4 |
| Package | Net_URL |
| License | BSD |
| Category | Networking |
| Summary | Easy parsing of Urls |
| Description | Provides easy parsing of URLs and their |
| | constituent parts. |
+-------------+-----------------------------------------+

This request displays a slightly different set of information. It doesn't include the release data but does include the general PEAR category and the latest version number for the package.

The package home page provides a more complete view and also provides links to earlier releases, a change log, and browseable access to the CVS repository. You can also view package download statistics. [[PHP Cookbook/PEAR#phpckbk-CHP-21-FIG-1|Figure 21-1]] shows a sample package information page.

<div id="phpckbk-CHP-21-FIG-1">
'''Figure 21-1. Net_URL Package Information page on PEAR web site'''

[[Image:PHP Cookbook_I_21_tt1185.png|Net_URL Package Information page on PEAR web site]]
</div>

=== See Also ===

[[PHP Cookbook/PEAR#Finding PEAR Packages|Recipe 21.3]] to search for packages.

== Installing PEAR Packages ==

=== Problem ===

You want to install a PEAR package.

=== Solution ===

Download and install the package from your PEAR server using the PEAR package manager:

% '''pear install'''
''Package_Name''

You can also install from any location on the Internet:

% '''<nowiki>pear install http://pear.example.com/</nowiki>'''
''Package_Name-1.0.tgz''

Here's how to install if you have a local copy of a package:

% '''pear install'''
''Package_Name-1.0.tgz''

=== Discussion ===

To install PEAR packages, you need write permission where the packages are stored; this defaults to ''/usr/local/lib/php/''.

You can also request multiple packages at the same time:

% '''pear install HTML_Common HTML_Javascript'''
downloading HTML_Common-1.0.tgz ...
...done: 2,959 bytes
install ok: HTML_Common 1.0
downloading HTML_Javascript-1.0.0.tgz ...
...done: 4,141 bytes
install ok: HTML_Javascript 1.0.0

When installing a package, PEAR checks that you have all the necessary PHP functions and PEAR packages the new package depends on. If this check fails, PEAR reports on the dependencies:

% '''pear install HTML_Table'''
downloading HTML_Table-1.1.tgz ...
...done: 5,168 bytes

requires package `HTML_Common' >= 1.0
HTML_Table: dependencies failed

To fix this problem, download and install the missing packages first. If you want to ignore these dependencies, force installation with <tt>-n</tt> or <tt>--nodeps</tt>. You can then later install the required package.

=== See Also ===

[[PHP Cookbook/PEAR#Installing PECL Packages|Recipe 21.6]] for information on installing PECL packages; [[PHP Cookbook/PEAR#Upgrading PEAR Packages|Recipe 21.7]] for more on upgrading an existing package; [[PHP Cookbook/PEAR#Uninstalling PEAR Packages|Recipe 21.8]] to uninstall a package.

== Installing PECL Packages ==

=== Problem ===

You want to install a PECL package; this builds a PHP extension written in C to use inside PHP.

=== Solution ===

Make sure you have all the necessary extension libraries and then use the PEAR package manager <tt>install</tt> command:

% '''pear install xmms'''

To use the extension from PHP, load it using <tt>dl( )</tt> :

dl('xmms.so');

=== Discussion ===

The frontend process for installing PECL packages is just like installing PEAR packages for code written in PHP. However, the behind-the-scenes tasks are very different. Because PECL extensions are written in C, the package manager needs to compile the extension and configure it to work with the installed version of PHP. As a result, at present, you can build PECL packages on Unix machines and on Windows machines if you use MSDev.

Unlike PHP-based PEAR packages, PECL extensions don't automatically inform you when you lack a library necessary to compile the extension. Instead, you are responsible for correctly preinstalling these files. If you are having trouble getting a PECL extension to build, check the ''README'' file and the other documentation that comes with the package. The package manager installs these files inside the ''docs'' directory under your PEAR hierarchy.

When you install a PECL extension, the PEAR package manager downloads the file, extracts it, runs ''phpize'' to configure the extension for the version of PHP installed on the machine, and then makes and installs the extension. It may also prompt you for the location of libraries:

% '''pear install xmms'''
downloading xmms-0.2.tgz ...
...done: 11,968 bytes
4 source files, building
running: phpize
PHP Api Version : 20020307
Zend Module Api No : 20020429
Zend Extension Api No : 20020731
Xmms library install dir? [autodetect] :
building in /var/tmp/pear-build-adam/xmms-0.2
running: /tmp/pearKIv63P/xmms-0.2/configure --with-xmms
running: make
xmms.so copied to /tmp/pearKIv63P/xmms-0.2/xmms.so
install ok: xmms 0.2

If these libraries are in a standard location, hitting Return selects the <tt>autodetect</tt> option. PHP then searches for the libraries and selects them; you don't need to enter an explicit pathname, as in the case of the xmms library shown earlier.

PECL extensions are stored in different places than non-PECL packages. If you want to run ''pear'', you must be able to write inside the PHP ''extensions'' directory. Some PECL packages, such as xmms, install files in the same directory as the PHP binary. Because of this, you may want to install these packages while running as the same user you used to install PHP. Also, check the execute permissions of these files; because most PEAR files aren't executable, your umask may not provide those executable files with the correct set of permissions.

=== See Also ===

[[PHP Cookbook/PEAR#Installing PEAR Packages|Recipe 21.5]] for information on installing PEAR packages; [[PHP Cookbook/PEAR#Upgrading PEAR Packages|Recipe 21.7]] for more on upgrading an existing package; [[PHP Cookbook/PEAR#Uninstalling PEAR Packages|Recipe 21.8]] to uninstall a package.

== Upgrading PEAR Packages ==

=== Problem ===

You want to upgrade a package on your system to the latest version for additional functionality and bug fixes.

=== Solution ===

Find out if any upgrades are available and then tell ''pear'' to upgrade the packages you want:

% '''pear list-upgrades'''
% '''pear upgrade'''
''Package_Name''

=== Discussion ===

Upgrading to a new version of a package is a simple task with the PEAR Package Manager. If you know a specific package is out of date, you can upgrade it directly. However, you may also want to just periodically check to see if any new releases are available.

To do this, user the <tt>list-upgrades</tt> command, which prints out a table showing package names, the new version number, and the size of the download:

% '''pear list-upgrades'''
Available Upgrades (stable):
= == == == == == == == == == == == == == =
+-------------+---------+--------+
| Package | Version | Size |
| Archive_Tar | 0.9 | 8.9kB |
| Auth | 1.0.2 | 8.8kB |
| Auth_HTTP | 1.0.1 | 1.7kB |
| DB | 1.3 | 58kB |
| HTTP | 1.1 | 2.9kB |
| Mail | 1.0.1 | 11.6kB |
| Mail_Mime | 1.2.1 | 15.0kB |
| Net_Ping | 1.0.1 | 2.1kB |
| Net_SMTP | 1.0 | 2.8kB |
| Net_Socket | 1.0.1 | 3.5kB |
| PEAR | 0.9 | 40kB |
| XML_Parser | 1.0 | 4.8kB |
| XML_RPC | 1.0.3 | 11.9kB |
| XML_RSS | 0.9.1 | 3.1kB |
| XML_Tree | 1.1 | 4.7kB |
+-------------+---------+--------+

If you're up to date, ''pear'' prints:

No upgrades available

To upgrade a particular package, use the <tt>upgrade</tt> command. For example:

% '''pear upgrade DB'''
downloading DB-1.3.tgz ...
...done: 59,332 bytes

The short command for <tt>list-upgrades</tt> is <tt>lu</tt>; for <tt>upgrade</tt> it's <tt>up</tt>.

PEAR also has an RSS feed listing new packages available at ''http://pear.php.net/rss.php''.

=== See Also ===

[[PHP Cookbook/PEAR#Installing PEAR Packages|Recipe 21.5]] and [[PHP Cookbook/PEAR#Installing PECL Packages|Recipe 21.6]] for information on installing PEAR and PECL packages; [[PHP Cookbook/PEAR#Uninstalling PEAR Packages|Recipe 21.8]] to uninstall a package; [[PHP Cookbook/XML#Reading RSS Feeds|Recipe 12.12]] for more on parsing RSS feeds.

== Uninstalling PEAR Packages ==

=== Problem ===

You wish to remove a PEAR package from your system.

=== Solution ===

The <tt>uninstall</tt> command tells the PEAR package manager to delete packages:

% '''pear uninstall HTML_Common'''
uninstall HTML_Common ok

=== Discussion ===

Uninstalling a package removes it completely from your system. If you want to reinstall it, you must begin as if the package was never installed. PEAR doesn't warn you if you try to remove a package that's dependent on another package, so be careful when you uninstall.

There is no way to automatically roll back an upgrade to an earlier version of a package using <tt>uninstall</tt>. Also, PEAR complains if you try to install an earlier version over a later one. To force PEAR to overwrite a newer version, use <tt>install -f</tt> or <tt>install --force</tt>:

% '''pear install --force Net_URL'''
downloading Net_URL-1.0.4.tgz ...
...done: 3,540 bytes
install ok: Net_URL 1.0.4

The short command for <tt>uninstall</tt> is <tt>un</tt>.

=== See Also ===

[[PHP Cookbook/PEAR#Installing PEAR Packages|Recipe 21.5]] and [[PHP Cookbook/PEAR#Installing PECL Packages|Recipe 21.6]] for information on installing PEAR and PECL packages.

== Documenting Classes with PHPDoc ==

=== Problem ===

You want to be able to integrate documentation with your code.

=== Solution ===

Use PHPDoc. This allows PEAR to accurately list your class, and you can use the PHPDoc tools to automatically generate API documentation in HTML and XML.

PHPDoc syntax is based on Javadoc. The following tags are available for use: <tt>@access</tt> , <tt>@author</tt>, <tt>@package</tt>, <tt>@param</tt>, <tt>@return</tt>, <tt>@since</tt>, <tt>@var</tt>, and <tt>@version</tt>.

You can then use PEAR's PHPDoc utility to generate documentation.

=== Discussion ===

PHPDoc has a special inline documentation style. By formatting your comments in a particular way, the PHPDoc script can parse your code to not only generate which parameters a function take and what type of variable it returns, but also associate comments and other useful information with objects, functions, and variables.

PHPDoc comments are based on the same formatting and naming conventions as Javadoc. So, to flag a comment block to grab PHPDoc's attention, use a traditional C-style comment but use two asterisks after the opening slash:

/**
* This is a PHPDoc comment block
*/

Inside of a block, certain keywords have special meaning. These keywords all begin with an at sign. [[PHP Cookbook/PEAR#phpckbk-CHP-21-TABLE-2|Table 21-2]] lists the keywords and what they stand for.

<div id="phpckbk-CHP-21-TABLE-2">
'''Table 21-2. PHPDoc keywords'''

{| border="1"
|-
! Keyword !! Meaning
|-
| <tt>@access</tt> || Method access: public or private
|-
| <tt>@author</tt> || Package author
|-
| <tt>@package</tt> || Package name
|-
| <tt>@param</tt> || Function parameter
|-
| <tt>@return</tt> || Function return value
|-
| <tt>@see</tt> || See also reference
|-
| <tt>@since</tt> || Debut version of PHP
|-
| <tt>@var</tt> || Object variable
|-
| <tt>@version</tt> || Package release number
|}
</div>

A more fully fleshed out example looks like this:

<nowiki>/**
* Example_Class is a sample class for demonstrating PHPDoc
*
* Example_Class is a class that has no real actual code, but merely
* exists to help provide people with an understanding as to how the
* various PHPDoc tags are used.
*
* Example usage:
* if (Example_Class::example()) {
* print "I am an example.";
* }
*
* @package Example
* @author David Sklar <david@example.com>
* @author Adam Trachtenberg <adam@example.com>
* @version $Revision: 1.6 $
* @access public
* @see http://www.example.com/pear
*/
class Example extends PEAR
{
/**
* returns the sample data
*
* @param string $sample the sample data
* @return array all of the exciting sample options
* @access private
*/
function _sampleMe($sample)
{</nowiki>

Any text following a keyword is treated as the value assigned to it. So, in this example, the value of <tt>@package</tt> is "Example." It can be okay to have two instances of the same keyword, depending upon the situation. For instance, it's perfectly legal to have multiple <tt>@param</tt> keywords, but it's illegal to have multiple <tt>@return</tt> keywords.

PHPDoc and the PEAR web site use this information to generate hyperlinked references, so it's important to use a consistent naming scheme, or the cross-references won't work correctly.

To generate PHPDoc, first install the PHPDoc PEAR package. Inside that package is a program named ''phpdoc'' ; run it from the command line, and use the <tt>-s</tt> flag to pass in the directory of the source files. By default, documentation is generated in ''/usr/local/doc/pear/'', so be sure the ''phpdoc'' program has write permission to that location, or use <tt>-d</tt> to alter the destination directory.

To permanently modify the default values, edit the values at the top of the script. Pass <tt>-h</tt> for a listing of all possible command-line parameters.

PHPDoc isn't very efficient, so be patient. Generating documentation may take a while, depending upon the size of your files. A faster program is currently under development.

=== See Also ===

PEAR coding standards at ''http://pear.php.net/manual/en/standards.php''; PHPDoc at ''http://pear.php.net/package-info.php?package=PHPDoc''.
== Notes ==

<references/>

PHP Cookbook/PEAR - Revision history

Docbook2Wiki: Initial conversion from Docbook

Evanlenz: 1 revision(s)

Docbook2Wiki: Initial conversion from Docbook