Introduction

phpDocumentor is the most advanced automatic documentation system written for PHP, in PHP. This package has many features:

• New Exciting new tokenizer-based parser is literally twice as fast as previous parser!
• New versatile @internal, inline {@internal}}, @example tags
• New Brand new extensive phpDocumentor manual
• New extended/tutorial documentation in docbook format with linking to any element and to other documentation, including sub-sections, from the source code (see phpDocumentor Tutorials)
• New docblock templates to cut down on repetition
• New {@source} inline tag to display function source
• New XML:DocBook:peardoc2 templates for PEAR developers
• New Greater ease of extending a Converter, see Converter Manual
• ability to parse any PHP file, regardless of documentation format
• conforms loosely to the JavaDOC protocol, and will be familiar to Java programmers
• documents all includes, constants, functions, static functions, classes, methods, static variables, class variables, and can document global variables and external tutorials
• auto-linking to pre-defined PHP functions
• Output in HTML, CHM, PDF, XML DocBook formats
• templateable with many bundled templates
• automatic linking to elements in any documented package
• documents name conflicts between packages to help avoid PHP errors
• documentation CVS directly.
• support for JavaDoc doclet-like output through Converters
• error/warning tracking system
• extreme class intelligence: inherits documentation, package
• complete phpdoc.de DocBlock tag support. Additions include @var, @magic, @deprec, @todo, and phpdoc.de parsing of @param.
• alphabetical indexing of all elements by package and overall
• class trees
• MUCH more than just this short list

phpDocumentor Basics

Starting Out From Scratch

The documentation process begins with the most basic element of phpDocumentor: a Documentation blockor DocBlock. A basic DocBlock looks like this:

1 /** 2 * 3 */

A DocBlock is an extended C++-style PHP comment that begins with "/**" and has an "*" at the beginning of every line. DocBlocks precede the element they are documenting.

To document function "foo()", place the DocBlock immediately before the function declaration:

1 /** 2 * Defies imagination, extends boundaries and saves the world ...all before breakfast! 3 */ 4 function foo() 5 { 6 }

This example will apply the DocBlock to "define('me',2);" instead of to "function foo()":

1 /** 2 * DocBlock for function foo? 3 * 4 * No, this will be for the constant me! 5 */ 6 define('me',2); 7 function foo($param = me) 8 { 9 }

define() statements, functions, classes, class methods, and class vars, include() statements, and global variables can all be documented, see Elements of the source code that can be documented.

DocBlocks

A DocBlock contains three basic segments in this order:

• Short Description
• Long Description
• Tags

The Short Description starts on the first line, and can be terminated with a blank line or a period. A period inside a word (like example.com or 0.1 %) is ignored. If the Short Description would become more than three lines long, only the first line is taken. The Long Description continues for as many lines as desired and may contain html markup for display formatting. Here is a sample DocBlock with a Short and a Long Description:

1 /** 2 * return the date of Easter 3 * 4 * Using the formula from "Formulas that are way too complicated for anyone to 5 * ever understand except for me" by Irwin Nerdy, this function calculates the 6 * date of Easter given a date in the Ancient Mayan Calendar, if you can also 7 * guess the birthday of the author. 8 */

Optionally, you may enclose all paragraphs in a <p></p> tag. Be careful, if the first paragraph does not begin with <p>, phpDocumentor will assume that the DocBlock is using the simple double linebreak to define paragraph breaks as in:

1 /** 2 * Short desc 3 * 4 * Long description first sentence starts here 5 * and continues on this line for a while 6 * finally concluding here at the end of 7 * this paragraph 8 * 9 * The blank line above denotes a paragraph break 10 */

Here is an example of using <p>

1 /** 2 * Short desc 3 * 4 * <p>Long description first sentence starts here 5 * and continues on this line for a while 6 * finally concluding here at the end of 7 * this paragraph</p> 8 * This text is completely ignored! it is not enclosed in p tags 9 * <p>This is a new paragraph</p> 10 */

phpDocumentor also supports JavaDoc's DocBlock format through the command-line option -j, --javadocdesc. Due to the non-xhtml compliant unmatched p tag, we highly recommend you avoid this syntax whenever possible

1 /** 2 * <p> 3 * Short desc is only to the first period. 4 * This means a sentence like: 5 * "Parses Mr./Mrs. out of $_GET." will 6 * parse a short description of "Parses Mr." 7 * which is rather silly. Long description is 8 * the entire DocBlock description including the 9 * Short desc, and paragraphs begin where p is like: 10 * <p> 11 * The p above denotes a paragraph break 12 */

phpDocumentor will convert all whitespace into a single space in the long description, use paragraph breaks to define newlines, or <pre>, as discussed in the next section

DocBlock Description details

As of phpDocumentor 1.2.0, the long and short description of a DocBlock is parsed for a few select html tags that determine additional formatting. Due to the nature of phpDocumentor's output as multiple-format, straight html is not allowed in a DocBlock, and will be converted into plain text by all of the converters unless it is one of these tags:

• <b> -- emphasize/bold text
• <br> -- hard line break, may be ignored by some converters
• <code> -- Use this to surround php code, some converters will highlight it
• <i> -- italicize/mark as important
• <li> -- list item
• <ol> -- ordered list
• <p> -- If used to enclose all paragraphs, otherwise it will be considered text
• <pre> -- Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)
• <ul> -- unordered list

For in-depth information on how phpDocumentor parses the description field, see ParserDescCleanup.inc

DocBlock Templates

New for version 1.2.0, phpDocumentor supports the use of DocBlock templates. The purpose of a DocBlock template is to reduce redundant typing. For instance, if a large number of class variables are private, one would use a DocBlock template to mark them as private. DocBlock templates simply augment any normal DocBlocks found in the template block.

A DocBlock template is distinguished from a normal DocBlock by its header. Here is the most basic DocBlock template:

1 /**#@+ 2 * 3 */

The text that marks this as a DocBlock template is "/**#@+" - all 6 characters must be present. DocBlock templates are applied to all documentable elements until the ending template marker:

/**#@-*/

Note that all 8 characters must appear as "/**#@-*/" in order for phpDocumentor to recognize them as a template. Here is an example of a DocBlock template in action:

class Bob { // beginning of docblock template area /**#@+ * @access private * @var string */ var $_var1 = 'hello'; var $_var2 = 'my'; var $_var3 = 'name'; var $_var4 = 'is'; var $_var5 = 'Bob'; var $_var6 = 'and'; var $_var7 = 'I'; /** * Two words */ var $_var8 = 'like strings'; /**#@-*/ var $publicvar = 'Lookee me!'; }

This example will parse as if it were:

class Bob { // beginning of docblock template area /** * @access private * @var string */ var $_var1 = 'hello'; /** * @access private * @var string */ var $_var2 = 'my'; /** * @access private * @var string */ var $_var3 = 'name'; /** * @access private * @var string */ var $_var4 = 'is'; /** * @access private * @var string */ var $_var5 = 'Bob'; /** * @access private * @var string */ var $_var6 = 'and'; /** * @access private * @var string */ var $_var7 = 'I'; /** * Two words * @access private * @var string */ var $_var8 = 'like strings'; var $publicvar = 'Lookee me!'; }

Note that for $_var8 the DocBlock template merged with the DocBlock. The rules for merging are simple:

• The long description of the docblock template is added to the front of the long description. The short description is ignored.
• All tags are merged from the docblock template

Tags

Tags are single words prefixed by a "@" symbol. Tags inform phpDocumentor how to present information and modify display of documentation. All tags are optional, but if you use a tag, they do have specific requirements to parse properly.

A list of all possible tags in phpDocumentor follows:

1 /** 2 * The short description 3 * 4 * As many lines of extendend description as you want {@link element} links to an element 5 * {@link http://www.example.com Example hyperlink inline link} links to a website. The inline 6 * source tag displays function source code in the description: 7 * {@source } 8 * 9 * In addition, in version 1.2+ one can link to extended documentation like this 10 * documentation using {@tutorial phpDocumentor/phpDocumentor.howto.pkg} 11 * In a method/class var, {@inheritdoc may be used to copy documentation from} 12 * the parent method 13 * {@internal 14 * This paragraph explains very detailed information that will only 15 * be of use to advanced developers, and can contain 16 * {@link http://www.example.com Other inline links!} as well as text}} 17 * 18 * Here are the tags: 19 * 20 * @access public or private 21 * @author author name <author@email> 22 * @copyright name date 23 * @deprecated description 24 * @deprec alias for deprecated 25 * @example /path/to/example 26 * @exception Javadoc-compatible, use as needed 27 * @global type $globalvarname 28 or 29 * @global type description of global variable usage in a function 30 * @ignore 31 * @internal private information for advanced developers only 32 * @param type [$varname] description 33 * @return type description 34 * @link URL 35 * @name procpagealias 36 or 37 * @name $globalvaralias 38 * @magic phpdoc.de compatibility 39 * @package package name 40 * @see name of another element that can be documented, produces a link to it in the documentation 41 * @since a version or a date 42 * @staticvar type description of static variable usage in a function 43 * @subpackage sub package name, groupings inside of a project 44 * @throws Javadoc-compatible, use as needed 45 * @todo phpdoc.de compatibility 46 * @var type a data type for a class variable 47 * @version version 48 */ 49 function if_there_is_an_inline_source_tag_this_must_be_a_function() 50 { 51 ... 52 }

In addition, tutorials allow two addition inline tags: {@id}, used to allow direct linking to sections in a tutorial, and {@toc}, used to generate a table of contents from {@id}s in the file. Think of {@id} like an <a name="idname"> HTML tag, it serves the same function.

See inline {@id} and inline {@toc} for detailed information

In the example below, {@id} is used to name the refsect1 "mysection" and the refsect2 "mysection.mysubsection" - note that the sub-sections inherit the parent section's id.

<refentry id="{@id}"> <refsect1 id="{@id mysection}"> <refsect2 id="{@id mysubsection}"> </refsect2> </refsect1> </refentry>

For an in-depth look at phpDocumentor tags, read phpDocumentor tags, and for an in-depth look at inline tags, read phpDocumentor Inline tags.

Documenting your PHP project

Where to begin

Before you begin documenting your PHP project, you might want to try a test run on your undocumented source code to see what kind of information phpDocumentor will automatically extract from the source code. phpDocumentor is designed to make the task of documenting minimally redundant. This means less work, and better, up-to-date documentation with less effort than it used to take.

Elements of the source code that can be documented

Dividing projects into packages

To understand the role of packages and how to use @package, it is important to know the logic behind packaging in PHP. The quest for structured programming led to the invention of functions, then classes, and finally packages. Traditionally, a re-usable software module was a collection of variables, constants and functions that could be used by another software package. PHP is an example of this model, as their are many extensions that consist of constants and functions like the tokenizer extension. One can think of the tokenizer extension as a package: it is a complete set of data, variables and functions that can be used in other programs. A more structured format of this model is of course objects, or classes. A class contains variables and functions (but no constants in PHP). A single class packages together related functions and variables to be re-used.

phpDocumentor defines package in two ways:

1. Functions, Constants and Global Variables are grouped into files (by the filesystem), which are in turn grouped into packages using the @package tag in a page-level DocBlock
2. Methods and Class Variables are grouped into classes (by php), which are in turn grouped into packages in a Class DocBlock

<?php /** * Pretend this is a file * * Page-level DocBlock is here because it is the first DocBlock * in the file, and is immediately followed by the second * DocBlock before any documentable element is declared * (function, define, class, global variable, include) * @package pagepackage */ /** * Here is the class DocBlock * * The class package is different from the page package! * @package classpackage */ class myclass { } ?>

Perhaps the best way to organize packages is to put all procedural code into separate files from classes. PEAR recommends putting every class into a separate file. For small, utility classes, this may not be the best solution for all cases, but it is still best to separate packages into files for consistency.

Advanced phpDocumentor: tutorials and extended Documentation

phpDocumentor developers have received a number of requests to allow linking to external documentation, and to sections of that documentation. If phpDocumentor only could create HTML documents, this would be a simple task, but the presence of PDF and now XML converters as well as future possibilities complicates this question tremendously. What is the solution?

Give phpDocumentor the ability to parse external documentation in a common format and then convert it to the appropriate format for each converter. The implementation of this solution in version 1.2.0 is very versatile. Making use of the standard DocBook XML format, external documentation can be designed and then reformatted for any output. No longer is external documentation tied down to one "look." Here's a short list of the benefits of this approach:

Benefits of using DocBook as the format:

• DocBook is very similar to HTML at the basic level and very easy to learn.
• Each template has its own options.ini file which determines how the DocBook tags will be translated into the output language - no need to learn xslt.
• Adding in xslt support will be very easy to allow for future customization

• Linking to external documentation from within API docs is possible
• Linking to API docs from external documentation is also possible
• Customizable table of contents, both of all tutorials and within a tutorial via inline {@toc}
• It is possible to create User-level documentation that has direct access to Programmer-level documentation

User-level documentation generally consists of tutorials and information on how to use a package, and avoids extreme detail. On the other hand, programmer-level documentation has all the details a programmer needs to extend and modify a package. phpDocumentor has been assisting the creation of programmer-level documentation since its inception. With the addition of tutorials, it can now ease the creation of user-level documentation.

For an in-depth look at how to use tutorials, read phpDocumentor Tutorials

Running phpDocumentor

There are two bundled ways of invoking phpDocumentor, the command-line phpdoc, or the web interface phpdoc.php/new_phpdoc.php.

Using the Web Interface phpdoc.php or new_phpdoc.php

In order to use the web interface, there are a number of factors that must be set up before anything else can occur. First, you need a working web server with php (it had to be said). This manual will not assist with that setup. Next, the phpdoc.php or new_phpdoc.php file needs to be accessible by the webserver. In unix, place a symbolic link using ln -s to the desired interface into the public html directory.

Note that since the webserver runs as user nobody in unix, the generated files will be owned by nobody. The only way to change this is to either run phpDocumentor from the command-line or to add a chuser wrapper around httpd. We do not recommend using a chuser wrapper or running phpDocumentor as root. It is much easier and safer to use a config file (see phpDocumentor's dynamic User-defined config files) from the command line.

Using the Command-line tool

Running the command-line in MS Windows

Running phpDocumentor from the command-line is fairly straightforward, even in windows. It is recommended to use the web interface in windows, from a non-publicly accessible server root, as none of the permissions issues exist that exist in unix. However, to use phpDocumentor from the command line is possible. First, put the location of php into the system path, then type:

C:\>php-cli C:\path\to\phpdoc\phpdoc [commandline]

An alternative is to edit the phpdoc.bat file, and place phpdoc in the path, then you can run phpdoc as a normal command.

Running the command-line in unix

Running the command-line tool phpdoc is very easy in unix:

.\phpdoc [commandline]

-c, --config

Use this option to load a config file (see phpDocumentor's dynamic User-defined config files)

"phpdoc -c default" will load the default.ini file

-ct, --customtags

Use this option to specify tags that should be included in the list of valid tags for the current run of phpdoc

"phpdoc -ct mytag,anothertag" will tell phpDocumentor to parse this DocBlock:

1 /** 2 * @mytag this is my tag 3 * @anothertag this is another tag 4 */

without raising any errors, and include the tags in the known tags list for the template to handle. Note that in version 1.2.0+, the unknown_tags array is passed to templates.

-dn, --defaultpackagename

Use this option to tell phpDocumentor what the primary package's name is. This will also tell phpDocumentor to group any unpackaged elements into the primary packagename. If not specified, the primary package is "default"

/** * This class has no package and will be grouped into the default package unless -dn packagename is used */ class nopackage { }

-d, --directory

This or the -f option must be present, either on the command-line or in the config file.

Unlike -f, -d does not accept wildcards. Use -d to specify full paths or relative paths to the current directory that phpDocumentor should recursively search for documentable files. phpDocumentor will search through all subdirectories of any directory in the command-line list for tutorials/ and any files that have valid .php extensions as defined in phpDocumentor.ini. For example:

"phpdoc -d relative/path/to/dir1,/fullpath/to/here,.."

-f, --filename

This or the -d option must be present, either on the command-line or in the config file.

This option is used to specify individual files or expressions with wildcards * and ?. Use * to match any string, and ? to match any single character.

• phpdoc -f m*.p* will match myfile.php, mary_who.isthat.phtml, etc.
• phpdoc -f /path/m* will match /path/my/files/here.php, /path/mommy.php /path/mucho/grande/what.doc, etc.
• phpdoc -f file?.php will match file1.php, file2.php and will not match file10.php

-h, --hidden

Use this option to tell phpDocumentor to parse files that begin with a period (.)

-i, --ignore

Use the -i option to exclude files and directories from parsing. The -i option recognizes the * and ? wildcards, like -f does. In addition, it is possible to ignore a subdirectory of any directory using "dirname/"

• phpdoc -i tests/ will ignore /path/to/here/tests/* and /path/tests/*
• phpdoc -i *.inc will ignore all .inc files
• phpdoc -i *path/to/* will ignore /path/path/to/my/* as well as /path/to/*
• phpdoc -i *test* will ignore /path/tests/* and /path/here/my_test.php

-it, --ignore-tags

Use the -it option to exclude specific tags from output. This is used for creating multiple sets of documentation for different audiences. For instance, to generate documentation for end-users, it may not be desired to output all @todo tags, so --ignore-tags @todo would be used. To ignore inline tags, surround them with brackets {} like --ignore-tags {@internal}.

--ignore-tags will not ignore the core tags @global, @access, @package, @ignore, @name, @param, @return, @staticvar or @var.

-j, --javadocdesc

Use this command-line option to enforce strict compliance with JavaDoc. JavaDoc DocBlocks are much less flexible than phpDocumentor's DocBlocks (see DocBlocks for information).

-o, --output

Use this required option to tell phpDocumentor which Converters and templates to use. In this release, there are several choices:

• HTML:frames:* - output is HTML with frames.
  • HTML:frames:default - JavaDoc-like template, very plain, minimal formatting
  • HTML:frames:l0l33t - Stylish template
  • HTML:frames:phpdoc.de - Similar to phpdoc.de's PHPDoc output
  • HTML:frames:DOM/default, HTML:frames:DOM/l0l33t, HTML:frames:DOM/phpdoc.de - same as above with javascripted expandable lists of elements
  • HTML:frames:phphtmllib - Very nice user-contributed template
  • HTML:frames:phpedit - Based on output from PHPEdit Code Generator
• HTML:Smarty:* - output is HTML with no frames.
  • HTML:Smarty:default - Bold template design using css to control layout
  • HTML:Smarty:PHP - Layout is identical to the PHP website
• CHM:default:* - output is CHM, compiled help file format (Windows help).
  • CHM:default:default - Windows help file, based on HTML:frames:l0l33t
• PDF:default:* - output is PDF, Adobe Acrobat format
  • PDF:default:default - standard, plain PDF formatting
• XML:DocBook:* - output is XML, in DocBook format
  • XML:DocBook:peardoc2 - documentation ready for compiling into peardoc for online pear.php.net documentation, 2nd revision

In 1.2.0+, it is possible to generate output for several converters and/or templates at once. Simply specify a comma-delimited list of output:converter:template like:

phpdoc -o HTML:frames:default,HTML:Smarty:PHP,HTML:frames:phpedit,PDF:default:default -t ./docs -d .

-pp, --parseprivate

By default, phpDocumentor does not create documentation for any elements marked @access private. This allows creation of end-user API docs that filter out low-level information that will not be useful to most developers using your code. To create complete documentation of all elements, use this command-line option to turn on parsing of elements marked private with @access private.

-po, --packageoutput

Use this option to remove all elements grouped by @package tags in a comma-delimited list from output. This option is useful for projects that are not organized into separate files for each package. Parsing speed is not affected by this option, use -i, --ignore whenever possible instead of --packageoutput.

phpdoc -o HTML:frames:default -t ./docs -d . -po mypackage,thatotherpackage will only display documentation for elements marked with "@package mypackage" or "@package thatotherpackage"

-p, --pear

Use this option to parse a PEAR-style repository. phpDocumentor will do several "smart" things to make life easier:

• PEAR-style destructors are automatically parsed
• If no @package tag is present in a file or class DocBlock, it will guess the package based on subdirectory
• If a variable or method name begins with "_", it will be assumed to be @access private

-t, --target

Use this to tell phpDocumentor where to put generated documentation. Legal values are paths that phpDocumentor will have write access and directory creation priveleges.

-ti, --title

Set the global title of the generated documentation

phpDocumentor's dynamic User-defined config files

The new -c, --config command-line options heralds a new era of ease in using phpDocumentor. What used to require:

phpdoc -t /path/to/output -d path/to/directory1,/another/path,/third/path -f /path/to/anotherfile.php -i *test.php,tests/ -pp on -ti My Title -o HTML:frames:phpedit
    

Can now be done in a single stroke!

phpdoc -c myconfig
    

What makes this all possible is the use of config files that contain all of the command-line information. There are two configuration files included in the distribution of phpDocumentor, and both are in the user/ subdirectory. To use a configuration file "myconfig.ini," simply place it in the user directory, and the command-line "phpdoc -c myconfig" will tell phpDocumentor to read all the command-line settings from that config file. Configuration files may also be placed in another directory, just specify the full path to the configuration file:

phpdoc -c /full/path/to/myconfig.ini
    

The best way to ensure your config file matches the format expected by phpDocumentor is to copy the default.ini config file, and modify it to match your needs. Lines that begin with a semi-colon (;) are ignored, and can be used for comments.