Introduction

Introduction – Purpose and simple usage example

Description

PHP_UML is a reverse-engineering tool, and a documentation tool.

It can parse PHP files and directories, and generate:

  • An XMI file, reflecting the object structure of the code parsed; you can then import that file into a CASE tool (such as Rational Rose)

  • A full HTML API documentation, very similar to Javadoc

  • PHP code skeletons (useful if you have an existing XMI file, and want to generate the files, folders and class declarations all at once)

XMI is an OMG standard for exchanging metadata information via XML, and is commonly used as an interchange format for UML models. Many UML softwares support importing and exporting of XMI files.

Features

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

  • @param and @var learn PHP_UML about the expected types of a parameter or a property.

  • @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.

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 (simple conversion).

Usage

You can use PHP_UML either from command line, or by writing a piece of code that will exploit the API.

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

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

$uml = new PHP_UML();   
$uml->parseFile('test.php'); 
$uml->generateXMI(1);             // UML version number (1 or 2)
$uml->saveXMI('test.xmi');
?>

Compatibility of XMI

Your UML/XMI code might be interpreted differently by the modeling tool you are going to use along with PHP_UML. This is particularly true for the version 2 of UML/XMI. For instance, the Eclipse plug-ins (EMF, Papyrus) only accept a particular flavour of XMI, called ecore, which is only partly compatible with the one you will get with PHP_UML.

Extension

PHP_UML is designed with evolution in mind. By choosing XMI as the pivot format for representing object oriented program structures, PHP_UML can not only interface with many design tools. It can also be transformed, through XSLT, into many other formats, like the HTML API documentation generator, included in PHP_UML.

To start your own transformation, create a folder under /Output, and create a main.xsl file inside (you can copy the one in /Output/html). Run the method PHP_UML->export(), passing the name of your format as the first parameter.

Instead of transforming XMI code, another way to create new output formats is to write a PHP class that will directly exploit the metamodel that the parser has built, exactly like the package XMI does.

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

PHP_UML (Previous) Command line interface (Next)
Last updated: Tue, 02 Jun 2009 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

Note by: fjas@free.fr
Thanks for your message.
I know you sent it a while ago, but I'm just reading it, sorry.

It is true that some of the things I wrote about XMI and UML are ambiguous, and I have cleared a little bit the documentation about PHP_UML accordingly (it should be published soon).
Thanks for your remarks.

I quite agree with you that PHP lacks type hinting for class properties (as well as for function returns). Since it is already possible to specify a type for the function parameters in PHP, it would be very coherent to allow it for the class properties and constants too.

BTW, you have suggested to make PHP_UML aware of annotations, in order to compensate this lack, but it's already a feature of PHP_UML (PHP_UML can read the properties types through the @var annotation)

Baptiste Autin
Note by: darren@webel.com.au
Thanks for your work on this, I am very interested in this project. I formerly worked for a major UML tool vendor, and use PHP and Drupal CMS for some web work, however the lack of graphical engineering and UML support in PHP is a big issue for me, especially because I am very used to UML-driven Java and XML Schema engineering.

Firstly however some clarifications. You wrote:

"Your UML/XMI code might be interpreted differently by the modeling tool you are going to use along with PHP_UML. This is particularly true for the version 2 of UML/XMI. For instance, the Eclipse plug-ins (EMF, Papyrus) only accept a particular flavour of XMI, called ecore, which is only partly compatible with the one you will get with PHP_UML."

You seem to be equating XMI with UML (and eCore in EMF with XMI), which is getting the cart before the horse. XMI is able to represent various metam metamodels, as described well here:

http://xml.sys-con.com/node/40066
XMI: The OMG's XML MetaData Interchange Standard

"The MOF standard selects a subset of UML that's appropriate for modeling metadata. This subset is called the MOF Core."

"the technology-neutral nature of the MOF Core made it relatively easy to produce a mapping from the MOF Core's elements to XML so that, given a metamodel, a Document Type Definition (DTD) could be generated. This DTD can be used to stream models that conform to the metamodel.
..
The generated DTD defines XML elements for each element of the metamodel."

"Several specific XMI DTDs have been standardized by the OMG. Each was produced by feeding an MOF-compliant metamodel into an XMI DTD generator. .. The UML DTD is the most widely used XMI DTD."

To call Ecore XMI files "a particular flavour of XMI" is not quite right. Please visit:

http://wiki.eclipse.org/index.php/EMF/FAQ#What_is_the_relationship_of_OMGTM_MOFTM_to_the_EMF_Ecore_model.3F

Also, concerning Papyrus (from http://wiki.eclipse.org/MDT/Papyrus):

" this project will provide the glue around valuable UML and SysML diagram editors (GMF-based or not) and other MDE tools. It will also offer support for UML and SysML profiling mechanisms."

Ok, so to the PHP_UML tool. I gave it a spin on a very simple PHP web application (for bulk migration and admin of subscription data for the Drupal Simplenews module), and then imported it into MagicDraw UML. The results is available here:

http://www.webel.com.au/php/uml

Because PHP does not support typed Properties it is very difficult to manage the Relationships between Classes (even with your handy 'mixed' DataType). The process shown requires so much manual intervention (I've used Dependencies and Usages to indicate where Associations could be) that the benefits of obtaining the UML representation are greatly undermined.

I find it unfortunate that (according to these minutes by these minutes by Derick Rethans from a PHP Developer meeting from Nov 2005) it was apparently decided that type-hinting would not be introduced for properties in future version of PHP:

"5.8 Type-hinted properties and return values
Issue: PHP only supports type hinted arguments and not for return values or properties.

Discussion:

We quickly agreed that we don't need type-hinted properties, as it would cause problems when they are assigned to other variables and it's just generally not-PHP style."

"We do not allow type-hinted properties as it's not the PHP way."

http://www.php.net/~derick/meeting-notes.html#type-hinted-properties-and-return-values

The lack of associative graphical engineering for PHP is enough to force me to stick with Java for most of my work (while I do use PHP for some web work).

One solution might be to use annotations to indicate type, which your PHP_UML tool could then interpret in strongly typed UML Properties.

Dr Darren Kelly (Webel IT)