- OOP Theory
- Defining a Class
- Creating an Object
- The $this Attribute
- Creating Constructors
- Creating Destructors
- Designing Classes with UML
- Better Documentation with phpDocumentor
- Review and Pursue
This chapter is from the book
This chapter is from the book
This chapter is from the book
Better Documentation with phpDocumentor
Along with creating a UML class design, another new topic in this edition is creating better code documentation using phpDocumentor (www.phpdoc.org).
In my opinion, properly documenting one’s code is so vitally important that I wish PHP would generate errors when it came across a lack of comments! Having taught PHP and interacted with readers for years, I am amazed at how often programmers omit comments, occasionally under the guise of waiting until later. Proper documentation is something that should be incorporated into code for your own good, for your client’s, for your co-workers’ (if applicable), and for the programmer in the future who may have to alter or augment your work—even if that programmer is you.
Although you can adequately document your code using simple comments, as I do in this book, there are two obvious benefits to adopting a formal phpDocumentor approach:
- It conveys many best practices and recommended styles.
- phpDocumentor will generate documentation, in HTML and other formats, for you.
The generated HTML 
can also be a valuable resource for anyone using your code, particularly your classes.
)
phpDocumentor creates documentation by reading the PHP code and your comments. To facilitate that process, you would start writing your comments in a way that phpDocumentor understands. To begin, you’ll use the docblock syntax:
/** * * Short description * * Long description * Tags */
The short description should be a single line description. The long description can go over multiple lines and even use some HTML. Both are optional.
After the description, write one or more lines of tags. Each tag is prefaced by @, and phpDocumentor supports several kinds; which you use will depend on the thing you’re documenting.
A docblock can be placed before any of the following:
- Class definition
- Function or method definition
- Variable declaration
- Constant definition
- File inclusion
A docblock should be written at the top of a script, in order to document the entire file (Script 4.8).
Script 4.8. A more formally documented version of the HelloWorld class.
1 <?php # Script 4.8 - HelloWorld.php #2
2 /**
3 * This page defines the HelloWorld class.
4 *
5 * Written for Chapter 4, "Basic Object-Oriented Programming"
6 * of the book "PHP Advanced and Object-Oriented Programming"
7 * @author Larry Ullman <Larry@LarryUllman.com>
8 * @copyright 2012
9 */
10
11 /**
12 * The HelloWorld class says "Hello, world!" in different languages.
13 *
14 * The HelloWorld class is mostly for
15 * demonstration purposes.
16 * It's not really a good use of OOP.
17 */
18 class HelloWorld {
19
20 /**
21 * Function that says "Hello, world!" in different languages.
22 * @param string $language Default is "English"
23 * @returns void
24 */
25 function sayHello($language = 'English') {
26
27 // Put the greeting within P tags:
28 echo '<p>';
29
30 // Print a message specific to a language:
31 switch ($language) {
32 case 'Dutch':
33 echo 'Hallo, wereld!';
34 break;
35 case 'French':
36 echo 'Bonjour, monde!';
37 break;
38 case 'German':
39 echo 'Hallo, Welt!';
40 break;
41 case 'Italian':
42 echo 'Ciao, mondo!';
43 break;
44 case 'Spanish':
45 echo '¡Hola, mundo!';
46 break;
47 case 'English':
48 default:
49 echo 'Hello, world!';
50 break;
51 } // End of switch.
52
53 // Close the HTML paragraph:
54 echo '</p>';
55
56 } // End of sayHello() method.
57
58 } // End of HelloWorld class.
To document a variable declaration, you use the @var tag, followed by the variable’s type (and optional description):
/** * @var string */ $name = 'Larry Ullman';
Notice that the docblock doesn’t need to reference the variable name, as phpDocumentor will be able to read that from the following line of code. The point of the docblock is to indicate the variable’s intended type.
To document methods and functions, use @param to detail the function’s parameters and @return to indicate the type of value the function returns (Script 4.8).
The details as to the possible types, and the full usage of all of phpDocumentor, can be found in the documentation (www.phpdoc.org/docs/).
Once you’ve written comments in the proper format, you can use the phpDocu-mentor tool to generate your documentation. To do that, you must first install phpDocumentor. The best way to install it is using PEAR (http://pear.php.net), so you must have that installed, too. PEAR already comes installed with many all-inone WAMP, MAMP, or LAMP stacks; check your associated documentation if you’re using one of these. If not, see the sidebar for some tips on installing PEAR.
To use phpDocumentor:
Complete the phpDocumentor-type comments for a file (Script 4.8) or application.
For simplicity’s sake, Script 4.8 shows a fully documented HelloWorld.php.
Access your computer via the command-line interface.
My assumption is that you already know how to do this for your platform. If not, search the Web or use my support forums for answers.
Add the phpDocumentor PEAR channel
:pear channel-discover pear.phpdoc.org
This will allow you to download the latest version of the phpDocumentor directory from that site.
Install phpDocumentor
:pear install phpdoc/ phpDocumentor-alpha
This instruction comes straight from the phpDocumentor Web site. It may change in time; check the site for the best, current instructions.
Note that on my system, in both Step 3 and Step 4, I had to preface these commands with sudo, to invoke the superuser, and include the full path to PEAR (both suggestions are made in the sidebar).
Move to the directory where your PHP scripts are:
cd /path/to/folder
Document a single file using
phpdoc -f HelloWorld.php -t docs
That line tells phpDocumentor to parse the file HelloWorld.php and to write the output to the target (-t) directory docs, which would be a folder in that same directory. phpDocumentor will attempt to create that directory, if it does not exist.
- Open docs/index.html in your browser
.
)
)