PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

Advanced Documentation With Reflection In PHP 5

A Crash Course In PhpDoc

For those of you not familiar with phpdoc, it is a method for documenting code that derives from Java’s JavaDoc format. Basically, it is a way to format comments so that they are machine readable, meaningful and easy for the programmer to write.

Some people are die-hard phpdoc users, some use derivatives that borrow the best from phpdoc and add some extra formatting. It is always highly controversial when you make changes to an established technology, but for the purposes of reflection, a few changes can be made to make it arguably more useful. Most specifically the addition of tab delimited fields for common attributes, which will be explained later in this article.

I will not discuss the original phpdoc standard here, because it is quite large, so if you are interested in the original way of doing this you should probably visit http://phpdoc.org. Instead, from now on when I refer to phpdoc I am referring purely to the derivative which my studio uses that is in absolutely no way associated with phpdoc.org or the defacto standardized phpdoc.

Our first look at actual phpdoc comments

To begin lets look at the general format of a phpdoc comment.

Listing 2 listing-2.php
<?php
    /**
     * Classname Additionaltitle
     *
     * Summary
     *
     * @attribute   some    something       something else
     */
    class classname
    {
 
    }
?>

The comment begins with the first word of the first line being a mirror of the items name. This is used in the title of the comment, and is added for readability. In my experience, it occasionally happens that code blocks are copied and pasted without regard to the comment; the function is then modified and the comment never updated. By mirroring the name we guarantee that the comment belongs to this function and helps to keep documentation straight from project to project.

The rest of the first line is what you want the entire title to show up as when the information is output. For example, the additional title for a merchant class might be:

Merchant provides credit card processing services.

The next part is always a blank line, as this indicates the end of the title and the beginning of the Summary block. The summary, unlike the title, should describe in brief how the class completes its function. For a Merchant class a several line summary is appropriate:

This class accepts multiple parameters via the constructor, depends on the global configuration manager for merchant account information and uses curl to communicate the credit card information to the processor. There are also various methods for checking the authenticity of the transaction and receiving processor status messages.

Next we have attributes. Attributes are a string that has special meaning to the parser. Attributes are always prefixed with @ and the data they refer to is tab delimited. There can be one or more tabs between each field in an attribute, so you can make all the data align nicely. Spaces will not be recognized as a delimiter only the \t tab character will be.

One such attribute is @var:

Listing 3 listing-3.php
<?php
    /**
     * Title
     *
     * Summary
     *
     * @var     type    $varname    Description
     * @var     array   $someVar    This array contains something
     */
?>

This data — unlike the summary — must be all on one line and the tab delimiting is important. This is derivative from the official phpdoc standard which only provides the name and a description.

When working with variables that change type the value mixed should be used for the type field. When working with objects, the name of the class should be used for the type field.

Here is a list of attributes that we make use of, some deviating from the official standard. There are many more attributes, so this is just a partial list of the most commonly used ones.

Global attributes

These can be used on all classes, interfaces, methods and functions.

Listing 4 listing-4.php
<?php
    /**
     * ...
     *
     * @author      Firstname Lastname
     * @copyright   ACME Inc.
     * @license     GNU LGPL
     * @see         Something
     * @link        http://www.example.com      Description of site
     * @remarks     Something people using the class might want to know.
     */
?>

Class specific attributes

Listing 5 listing-5.php
<?php
    /**
     * ...
     *
     * @var         type        $varname        Description
     * @extends     SomeClass
     * @implements  SomeInterface, SomeOtherInterface
     */
?>

Interface and class attributes

Listing 6 listing-6.php
<?php
    /**
     * ...
     *
     * @depends     SomeClass
     */
?>

Method specific attributes

Listing 7 listing-7.php
<?php
    /**
     * ...
     *
     * @access      public|private|protected
     */
?>

Function and method attributes

Listing 8 listing-8.php
<?php
    /**
     * ...
     *
     * @param       type            $variableName       Description
     * @throws      someException   Description
     * @return(s)   type            Description
     */
?>

In This Article