Using the Documenter Class

That completes the description of the Documenter class. We will now use it in a web page to display information about all internal and user-defined classes. We'll create a sidebar of links to all existing classes and interfaces, and display detailed information in the main portion of the page. Again, we won't discuss every line of code, only those lines that are of special interest.

Creating a Sidebar of Classes and Interfaces

Let's create a sidebar that will display the names of all PHP classes as hyperlinks—fulfilling the promise of a central repository of information about all classes. Clicking a hyperlink will display documentation for this class in the main portion of your web page. The code to do this follows:

❶include 'MySQLResultSet.php';
include 'MySQLConnect.php';
include 'Documenter.php';
include 'PageNavigator.php';
$arr = ❷get_declared_classes();
natcasesort($arr);
$classname = ❸@$_GET["class"];
if(!isset($classname)){
    $classname = current($arr);
}
echo "<h4 style="background-color:#fff;">Classes</h4>";
foreach($arr as $key => $value){
    echo "<a href="getclass.php❹?class=$value">".
        "$value</a><br />";
}

In addition to built-in classes, any user-defined classes that have been loaded using ❶ an include or require statement will be retrieved when you call ❷ the get_declared_classes function. If no ❸ variable named class has been passed to this page, then $classname will default to the name of the first class in the array of declared classes. This $classname variable contains the class name that will be passed to the constructor of the Documenter class. Information about the specified class will be displayed in the center of the page. A foreach loop creates the list of hyperlinks to all available classes by creating ❹ a query string that includes the class name.

Your sidebar also displays links to all the declared interfaces. The code to do this is identical to the code to retrieve classes except that it calls the function get_declared_interfaces instead of get_declared_classes. Therefore this code will not be reproduced here.

Formatting Detailed Documentation

The MySQLException class is a derived class that has a variety of methods (see Figure 14-1), so use it as an example of how we would like the class documentation to look.

Let's proceed by relating the code to this output. The web page that displays your documentation first creates an instance of the Documenter class:

❶try{
    $class = new Documenter($classname);
    echo "<h2>Name: ". $class->❷getName() . "</h2>
";
    $today = ❸date("M-d-Y");
    echo "<p> Date: $today<br />";
    echo "PHP version: ". phpversion() . "<br />";
    echo "Type: ". $class->❹getClassType() . "<br /><br />
";
    echo "<span class="fulldescription">". $class->❺getFullDescription().
         "</span><br /><br />
";
    echo $class->❻getDocComment() . "</p>
";
    ...
}

Because creating an instance may throw a ReflectionException, you enclose your call to the constructor within ❶ a try block. You need to know which class we are documenting, so you display the class name by calling ❷ the inherited method getName. Knowing when documentation was created is important, so you display the date using ❸ the date function. Likewise with the PHP version number. Since you are mixing built-in and user-defined classes, specifying ❹ the class type will reduce confusion.

As you saw earlier in this chapter, ❺ the full class description identifies whether you are dealing with a class or an interface, and also details the class parentage. Because internal comments within the class file have been properly formatted, you can extract them using ❻ the getDocComment method. When this method is called against an instance of a class, it retrieves the comment that immediately precedes the class definition. Let's see how that's done.

Formatting Comments for the Documenter

The getDocComment method is fussy about what it will retrieve, so let's look at the format of the comments within an existing user-defined class. We'll continue using the MySQLException class as an example.

/** For use with MySQLConnection and MySQLResultSet classes */
class MySQLException extends Exception
{ ... }

A class-related, internal comment must meet the following conditions for the getDocComment method to work:

• It must immediately precede the class definition statement.

• It may run to any number of lines but must begin with a forward slash, followed by two asterisks, followed by white space, and be terminated by an asterisk and forward slash—in other words, exactly the format required by Javadoc.

The ReflectionFunction, ReflectionMethod, and ReflectionObject classes also support a getDocComment method. (As of PHP 5.1, the ReflectionProperty class also supports this method.) Exactly the same formatting rules apply. Again, internal comments must immediately precede what they document.

As you can see in Figure 14-1, the internal comments documenting the constructor are displayed immediately after the class description—as promised, the Documenter class incorporates internal comments. Unfortunately, getDocComment only applies to user-defined classes and user-defined methods or data members; comments cannot be extracted for internal classes.

Documenting Methods

As shown in Figure 14-1, method documentation is displayed immediately after the class description and comments. With a view to the client programmer, public methods are displayed immediately after the class name and description, followed by protected methods, and finally private methods. Because the MySQLException class has no protected methods, none are shown.

Methods of all levels of visibility are passed to the show_methods function to handle the details of displaying method descriptions. Here is the prototype for this function:

function show_methods(Documenter $d, $type, $arr)

One of the parameters of this function is an object. In PHP 4 you would want to ensure that this object was passed by reference by preceding the variable with & (an ampersand). As discussed in Chapter 13 in the section "__clone" on page 117, in PHP 5 all objects are automatically passed by reference, so there is no need to do this. This parameter is also type hinted, disallowing anything other than a Documenter object.

To summarize, this function displays the variable names of method parameters, type hints, and default values where applicable. Syntax highlighting has been used for the keywords describing each method—you can quickly see in Figure 14-1 that the getMessage method of the MySQLException class is both final and public. User-defined methods are flagged as such, and any internal comments are displayed.

---

Note:

If you are running PHP 5.1 or higher, you can type hint the array passed to show_methods by changing the function prototype to read function show_methods(Documenter $d, $type, array $arr).

---

Data Members

Data members are handled in much the same way as methods. Those with the least restrictive visibility are presented first. Again, keywords are highlighted. Even default values assigned to data members can be retrieved. Somewhat surprisingly, this is done using the getDefaultProperties method of ReflectionClass rather than by using a ReflectionProperty class method. As with methods, all modifiers are shown. The value of constants is retrieved using the ReflectionClass method getConstants.