Manual

A PHP parser, an XMI generator, and an API documentation tool

Introduction

Introduction – Purpose and simple usage example

Description

PHP_UML converts programming data from one format (PHP or XMI) to another (PHP, XMI or HTML). In other words, PHP_UML is a reverse-engineering tool, and an API documentation tool.

It can parse PHP files, and generate:

An XMI file, that reflects the object structure of the code parsed (you can then import it into a CASE tool, such as Rational Rose)
A full HTML API documentation. Two themes are available (an oldie, similar to Javadoc, and a modern looking one)
PHP code skeletons (useful if you have an existing XMI file, and want to generate the files, folders and class declarations all at once)

From its version 1.5, PHP_UML can also parse procedural code. The export format called "htmlnew" benefits from this new capability, and turns PHP_UML into a kind of competitor of PhpDocumentor (although it does not offer all of its features). See here an example of an API documentation as generated by PHP_UML.

Features

PHP_UML is able to parse the following PHP elements: namespaces, classes, interfaces, properties, and functions. It can also retrieve information from the inline comments, via the annotations: @package, @var, @param

@param and @var learn PHP_UML about the expected types of a parameter or a property (when type hinting is not present).
@package learns PHP_UML about the namespace of an element (even if, from PHP 5.3, it is recommended to use the PHP namespacing instructions instead)

So the more documented your PHP code is, the more precise your XMI file, or your API documentation, will be.

Usage

You can use PHP_UML either from command line (the simplest solution), or by writing a piece of code that relies on PHP_UML.

Parsing a single file test.php, and generating its XMI file:

<?php
require_once 'PHP/UML.php';

$uml = new PHP_UML();   
$uml->setInput('tests');               // this defines which files/folders to parse (here, the folder "tests")
$uml->parse('myApp');                  // this starts the parser, and gives the name "myApp" to the generated metamodel
$uml->export('xmi', 'myApp.xmi');      // this serializes the metamodel in XMI code, and saves it to a file "myApp.xmi"
?>

About XMI

At the current time, the UML/XMI standards exist in two distinct families of versions, 1.x and 2.x. PHP_UML can generate XMI in version 1.4, as well as in version 2.1. Be warned, though, that some UML tools might not interpret accurately the data contained in your XMI file. For example, the link between a UML artifact (a source file) and the classes defined inside that artifact is only available from version 2 of UML.

PHP_UML can also convert existing UML/XMI data from version 1.4 to version 2. An inline converter (using PHP_UML behind the scene) is available here.

Command line interface

Command line interface – How to run PHP_UML from the command line?

Install

The executable phpuml relies on Console::CommandLine. If you have followed the normal PEAR installation process to install PHP_UML, that dependency should have been resolved, and you should be able to run phpuml directly from the command line.

Arguments

PHP_UML converts data into another kind of data. This can be summarized with:

$ phpuml [INPUT] -o [OUTPUT LOCATION] -f [OUTPUT FORMAT]

[INPUT] can be PHP files, or XMI files. [OUTPUT FORMAT] can be PHP files, XMI files, or HTML files.

In other words, to specify the files/directories to scan, pass them as main arguments:

$ phpuml /var/www/foo

Separate the different elements by a space:

$ phpuml /var/www/file1.php file2.php

By default, phpuml will recursively parse the specified files/folders, and will echo the XMI code on the screen (UML/XMI version 2).

Options

Renaming the UML model name

By default, the root package of a UML model is named default. To rename it, use the switch -n:

$ phpuml /var/www/foo -n MyProject

Saving to a file

To save the XMI data in a particular place, instead of printing it on the screen, use -o:

$ phpuml /var/www/foo -n MyProject -o /var/tmp/

This will parse /var/www/foo, and save the XMI data to /var/tmp/MyProject.xmi. Use the dot to save to the current directory: -o .

The option -o also accepts a file name, instead of a directory path.

Generating an API's documentation in HTML, or some PHP code

In addition to xmi, 3 output formats are also available: html, htmlnew, and php.

"htmlnew" is a full XHTML-compliant API documentation ("modern" look and feel). It has the particularity to reflect the procedural code, in addition to the object code. The global procedural functions and constants appear in the top package.
"html" is another HTML API documentation ("Javadoc" look and feel)
"php" is a PHP code generation (code skeletons)

Use the option -f to specify which format you want phpuml to generate.

$ phpuml /var/www/foo -f html -o /var/tmp/

This will scan /var/www/foo, and create the API documentation in /var/tmp/.

If you need to provide your own XMI file (instead of parsing existing PHP files), simply pass it as argument.

$ phpuml myFile.xmi -f php -o /var/tmp/

This will read the XMI code contained in myFile.xmi, and generate the PHP code templates in /var/tmp/. Note that with the command line tool, you cannot both read an XMI file and parse PHP files: you will have to use the API if you need to build a UML model by merging inputs from XMI and PHP simultaneously.

Selecting the UML/XMI version

To select which version of the UML/XMI standards you want your XMI to be written in, use the option -x:

$ phpuml /var/www/foo -x 1 -o /var/tmp/

Note that Argouml accepts XMI code only in version 1, while the Eclipse plugins (Ecore standard) only in version 2.

Converting from UML/XMI version 1 to 2

phpuml can automatically convert UML/XMI data from version 1.4 to version 2.1.

$ phpuml foo1.xmi -o foo2.xmi

This will read foo1.xmi, and, if its XMI content is in version 1.x, converts it to version 2, and stores it in foo2.xmi. Note that this is an ad hoc conversion, inspired on what Rationale Rose, Argouml and Umbrello generate. It does not convert all of the UML entities, and it does not interpret all of the various XMI dialects.

Filtering the files to parse

By default, phpuml will parse only files with the extension .php. To modify this file pattern, use the - m selector:

$ phpuml /var/www/foo -m *.php *.txt

This will parse all php and txt files.

Ignoring some files and folders

Use the switch -i:

$ phpuml /var/www/foo -i tests *.php4

This will parse all files, except the ones in the folder "tests", and the ones with an extension "php4".

Removing the dollar sign ($) in the documentation

Use the switch --no-dollar:

$ phpuml /var/www/foo --no-dollar -o foo.xmi

Other options are available. You will discover them by asking for help, like this:

$ phpuml -h

Form more information about how PHP_UML interprets your PHP code, read this section.

Frequent problems

Frequent problems – List of issues that may be encountered when using PHP_UML

Class 'XSLTProcessor' not found in (...) ExporterXSL.php on line 192

PHP_UML relies on the PHP extension XSL for certain output formats. Please modify your php.ini to enable this extension.

Warning: date(): it is not safe to rely on the system's timezone settings (...)

You can ignore this warning. If you really don't want to see it, add a "date.timezone" configuration line in your php.ini

Error message when importing XMI into Umbrello or ArgoUML

Some modeling tools expect XMI in version 1. By default, PHP_UML generates XMI in version 2. So use the switch -x to specify the version 1, as described in Command line interface

About the parser

About the parser – Things to know about how PHP_UML parses PHP code

Types

Even though PHP is not a "strong typed language", PHP_UML relies a set of predefined types (integer, float, string, mixed, etc.) and tries to use them as much as it can guess. By inspecting the default values, the type hints in the functions parameters (when they are present), as well as the docblocks @param, PHP_UML can detect the types of the parameters, constants and properties. When it cannot guess, it assumes that it is the mixed type.

PHP_UML is also aware of a couple of internal PHP classifiers, such as Exception or Iterator (that's why you might see them appear in the API documentation).

What happens if the parser has not been able to resolve a type/class/interface? (for example, when a class implements an interface whose source code has not been provided)

With the export formats xmi and html, the target type does not appear at all.
With the export format htmlnew, the type is displayed, but is not clickable.

Packages and namespaces

Even if packages don't exist by themselves in PHP, PHP_UML reconstitutes them by using the PHP namespaces (from PHP 5.3), or by using the docblock @package (if the source code has some). As for the "top package", it is nothing else than the "global namespace" of PHP.

Procedural code

Although this is not very UML style, PHP_UML can parse procedural code. The output format htmlnew is currently the only format to benefit from this new capability (the XMI format cannot, since it is a strict object-oriented XML vocabulary).

In the API documentation, the procedural functions will appear under Functions and the procedural constants under Properties, inside the package that matches the namespace that these elements belong to.

Special switches

By default, the parser will ignore all the elements that have a docblock @internal. If you want to have them parsed anyway, use the switch --show-internal

Similarly, the switch --only-api forces PHP_UML to parse only the elements that are annotated with an @api.

With the switch --no-dollar, the parser removes the $ at the beginning of the property names (this character can cause problems with some UML tools).

Set the error reporting level to 2 with "--error-level 2" to display a list of the types/classes/interfaces that PHP_UML has not been able to resolve.

How do PHP elements map to UML concepts? (logical view)

A PHP class (or interface) maps to an UML Class (or Interface).
A PHP function maps to an UML Operation.
A PHP property, or class constant, maps to an UML Attribute.

Packages do not exist in PHP, like they do in Java. There are two possible ways to mimic them:

by using the PHP namespace instruction
by using the docblock @package in the comment of a class (or of a file)

Note that the namespace and use instructions will be parsed only if you run PHP_UML with PHP from version 5.3.

How do PHP elements map to UML concepts? (deployment view)

A PHP file maps to an UML Artifact.
A physical folder maps to an UML Package.

How do PHP elements map to UML concepts? (component view)

In UML 1.4:

A class (or an interface) maps to an UML Component.
A logical package maps to an UML Subpackage.

In UML 2.1:

A class (or an interface) maps to an UML Component.
A logical package maps to a nesting UML Component.

API

API – How to use PHP_UML from its API?

Principles

PHP_UML is structured in 4 packages:

The host package, which contains the main class (PHP_UML) and some utility classes
The Input package, where the PHP and XMI parser reside (they are the Importer objects).
The Metamodel package, which contains the data structures that PHP_UML is using to modelize the code parsed
The Output package, which contains all the objects (called Exporter) to transform the UML model stored into memory into an output format (like XMI, HTML, or PHP)

If the default settings suit your needs, the only single class you need to know about is PHP_UML. For more advanced operations, you must use the Importer and Exporter hierarchies of objects, whose roles, respectively, are to import data into the UML model, and export data out from the UML model.

Examples

Parsing of a single file test.php, and generation of its XMI file:

<?php
require_once 'PHP/UML.php';

$uml = new PHP_UML();   
$uml->setInput('test.php');
$uml->parse('foo');                 // parses, and sets the name of the root package
$uml->export('xmi', 'test.xmi');    // first param is the format (html, php, htmlnew or xmi), second param is the output folder
?>

Parsing of two directories, ignoring the CSV folders, and generation of HTML documentation

<?php
require_once 'PHP/UML.php';

$uml = new PHP_UML(); 
$uml->setInput(array('C:\Inetpub\foo', 'C:\Inetpub\libraries'));
$uml->parse();
$uml->export('html', 'C:\Inetpub\api');
?>

Import of an XMI file, and generation of PHP code templates

<?php
require_once 'PHP/UML.php';

$uml = new PHP_UML();

$uml->setInput('foo.xmi');

$uml->setImporter(new PHP_UML_Input_XMI_FileScanner());   // by default, PHP_UML uses a PHP_UML_Input_PHP_FileScanner

$uml->parse();

$exporter = new PHP_UML_Output_Php_Exporter();
$exporter->setModel($uml->getModel());
$exporter->export('./');
?>

Parsing of a PHP directory, followed by an XMI generation, without relying on a PHP_UML object

<?php
require_once 'PHP/UML.php';

$importer = new PHP_UML_Input_PHP_FileScanner();
$importer->setDirectories(array('somewhere/'));
$importer->import();

$exporter = new PHP_UML_Output_Xmi_Exporter();
$exporter->setModel($importer->getModel());
$exporter->setXmiVersion(1);
$exporter->setEncoding('utf-8');
$exporter->setDeploymentView(true);
$exporter->setComponentView(true);
$exporter->export('somewhere/else/');
?>

Note how the model is transfered from the importer object to the exporter object, with the methods getModel() and setModel().

You can use the factory method PHP_UML_Output_Exporter::getInstance($format) to get an exporter object given a format name, instead of instantiating the objects by yourself.

Extension

Extension – How to extend PHP_UML?

Extension

As said in the Command Line section, PHP_UML converts programming data from one format to another format. Between the two, it builds a UML model.

At the current moment, PHP_UML can read XMI and PHP, and can generate XMI, PHP and HTML.

If you want to write your own input format, you can program your own implementation of PHP_UML_Input_ImporterFileScanner.

If you want to write your own output format, you can program your own implementation of PHP_UML_Output_Exporter (either by traversing the model, like the "HtmlNew" implementation does, either by XSLT applied on XMI, like the implementation "Html" does).

For a better understanding of the program's guts, have a look at its class diagram, available in the docs folder (PHP_UML_simplified_class_diagram.png).

If you are interested in the PHP_UML project, and want to participate, do not hesitate to contact me.