Example 2: Generating PHP Documentation with Reflection
One final example generates PHP class documentation using reflection—a task that requires deep class introspection, and thus uses many Reflection API methods.
First you need a simple HTML-based console that lets clients specify the name of the class to document. The console code could be as simple as this:
<html>
<head>
<b>Provide the class name to be documentated: <br /><br /></b>
</head>
<body>
<form method="get" action="generatingDocumentation.php">
<input type="text" name="class">
<input type="submit" value="Generate documentation">
<input type="reset" value="Reset">
</form>
</body>
</html>
The
generatingDocumentation.php code in
Listing 2 functions as the main component of the documentation application.
The page first retrieves the class name submitted by the user through the console, adds a file extension, includes the class, and then opens a file where it will write the output documentation:
//get the class name to be documentated
$className=$_GET['class'];
//paste the name class with the extension .inc
$classNameExtension=$_GET['class'].".inc";
$b=$_GET['class'];
//include the $classNameExtension class
include($classNameExtension);
//get a ReflectionClass for the $className class
$reflection=new ReflectionClass($className);
//prepare the output
$hf=fopen("PTD.html","w");
Next it cycles through the various parts of the class, retrieving the interfaces the class supports, the name of its parent class (if any), constants, properties, and finally the methods, along with all their parameters. It writes all that information, including any description comments, into the documentation file. You can see the full code in
Listing 2, but here's the section that retrieves and documents a class's methods and parameters:
//get information about methods
$methods=$reflection->getMethods();
if($methods != null)
{
fwrite($hf,"\t<tr><td align=\"center\"".
" colspan=\"0\"><font face=\"arial\"".
" size=\"2\" color=\"purple\">Methods:".
"</td><td align=\"center\" colspan=\"0\">".
"<font face=\"arial\" size=\"2\"".
" color=\"black\"><b>Name</b></td>".
"<td align=\"center\" colspan=\"0\">".
"<font face=\"arial\" size=\"2\"".
" color=\"black\"><b>Modifiers</b>".
"</td><td align=\"center\" colspan=\"0\">".
"<font face=\"arial\" size=\"2\"".
" color=\"black\"><b>Parameters</b>".
"</td><td align=\"center\" colspan=\"0\">".
"<font face=\"arial\" size=\"2\"".
" color=\"black\"><b>Description</b>".
"</td></tr>\n");
foreach($methods as $in)
{
fwrite($hf,"\t<tr><td></td><td>");
fwrite($hf,$in->getName());
if($in->isConstructor())
{ fwrite($hf," [c]"); }
fwrite($hf,"</td><td>");
if ($in->isPublic())
{ fwrite($hf,"[public]"); }
if ($in->isPrivate())
{ fwrite($hf,"[private]"); }
if ($in->isProtected())
{ fwrite($hf,"[protected]"); }
if ($in->isAbstract())
{ fwrite($hf,"[abstract]"); }
if ($in->isFinal())
{ fwrite($hf,"[final]"); }
if ($in->isStatic())
{ fwrite($hf,"[static]"); }
fwrite($hf,"</td>");
$parameters=$in->getParameters();
if($parameters != null)
{
fwrite($hf,"<td align=\"center\">");
$nr_parameters=count($parameters);
foreach($parameters as $out)
{
 | |
| Figure 3. PHP Documentation Output: The PHP Documentation Tool application emits documentation showing the interfaces, superclass, constants, properties, and methods. |
fwrite($hf,"$");
fwrite($hf,$out->getName());
if($out->isPassedByReference())
{ fwrite($hf," [&] "); }
if($out->allowsNull())
{ fwrite($hf," [+] "); }
}
fwrite($hf,"</td>");
}else { fwrite($hf,"<td></td>"); }
fwrite($hf,"<td align=\"center\"><i>");
fwrite($hf,$in->getDocComment());
fwrite($hf,"</i>\n\t</td></tr>\n");
}
}
For example, if you provide the test class in
Listing 1 to the PHP Documentation Tool, it will output the information shown in
Figure 3.
As you have seen, the new Reflection API provides a good implementation of reflection, and gives you the tools to create more complex applications, such as the PHP Documentation Tool. You'll find reflection particularly useful when you don't know which class or method you need to execute at design time.
Previous Page
