I found three ways to get complexity measures for PHP code.

The most advanced technique is to use a continuous integration server. One good example is the server at test.pear.php.net which uses CruiseControl (a Java CI server) with phpUnderControl for the PHP specific parts. Certainly a nice solution for big projects, but nothing to use on your own laptop to improve a single package.

Often the easiest way is to use PHP_CodeSniffer, which includes checks for cyclomatic complexity and nesting level (causing warnings and errors above some thresholds). If you already use it to maintain a uniform coding style (e.g. PEAR, Zend) then you just have to add these checks to your standard definition. These commands add metrics to the PEAR standard:

cd /usr/local/share/pear/PHP/CodeSniffer/Standards
sudo cp -R Generic/Sniffs/Metrics PEAR/Sniffs
sudo sed -I .bck -e 's/Squiz_/PEAR_/' PEAR/Sniffs/Metrics/*

The program PDepend creates a more detailed analysis of methods, classes, and projects (see this release note for details). Because it is intended as a component within a CI server its primary output is in XML. So I wrote myself a small wrapper (pdepend_summary.php) to format the data as an ASCII table. This allows for quick edit-check-cycles and now I run it along with phpcs and phpunit before I commit PEAR code.

Example output:

Package              Class                                  LoC %Comment Variables Methods Class_SiZe   WMC
-------              -----                                  --- -------- --------- ------- ----------   ---
Payment_DTA          DTA                                   1084     36.3         3      15        114   111
Payment_DTA          DTAZV                                  757     37.1         1      12         72    71
Payment_DTA          DTABase                                563     33.0         6      19         33    27
Payment_DTA          Payment_DTA_ChecksumException            3      0.0         0       0          0     0
Payment_DTA          Payment_DTA_FatalParseException          3      0.0         0       0          0     0
Payment_DTA          Payment_DTA_Exception                    3      0.0         0       0          0     0
Payment_DTA          Payment_DTA_ParseException               3      0.0         0       0          0     0
 
Package/Class             Method                                   LoC %Comment    CCN    NPath
-------------             ------                                   --- --------    ---    -----
Payment_DTA/DTA           _generateCrecord                         158     25.9     13     1600
Payment_DTA/DTA           _parseCextension                          81     30.9     13       93
Payment_DTA/DTA           _processCextension                        47      2.1      8        8
Payment_DTA/DTA           parse                                     59     35.6      7       36
Payment_DTA/DTAZV         _exchangeFillSender                       33      0.0      7       64
Payment_DTA/DTAZV         parse                                     41     17.1      7       36
Payment_DTA/DTAZV         _exchangeFillReceiver                     26      7.7      6       24
Payment_DTA/DTA           _exchangeFillArrays                       31      0.0      6       32
Payment_DTA/DTA           _parseCrecord                            109     27.5      6       72
Payment_DTA/DTAZV         setAccountFileSender                      41      0.0      5       15
Payment_DTA/DTA           _parseErecord                             49     30.6      5       16
Payment_DTA/DTABase       getStr                                    18      0.0      4        8
Payment_DTA/DTAZV         __construct                               19     10.5      4        4
...

Mit dem DTA-Leser stelle ich nun ein Beispielskript online um Dateien entgegenzunehmen und ihren Inhalt anzuzeigen. Ist in einigen Situationen recht nützlich…

My first approach was to filter by file and path names, but not every message includes a filename, so I was left with some lines like these:

2010-03-15T00:00:15.00+01:00 server php-cgi: Undeclared entity warning at line 54, column 8

To overcome the problem I introduce two new php.ini variables: syslog.program, to give the program name, and the boolean syslog.pid, to enable logging the PID. Default values are "" and Off, resulting in the previous behaviour (using the executable name as program name without PID). I use suphp, so every user has an own php.ini with syslog.program set to “php/username”, thus writing log lines like:

2010-03-19T09:00:14.00+01:00 server php/mschuett[87777]: Undeclared entity warning at line 54, column 8

With mod_php the variables can also be set per directory with php_admin_value. Changing them with ini_set() is not supported (not necessary because a new call to openlog() has the same effect). For enhanced security one could/should also use the php.ini setting disable_functions=openlog to prevent users from overriding these settings.

Because the source file is also affected by the Suhosin patch, I prepared two diffs:

• PHP 5.2.12:patch-php5.2.12.ext_standard_syslog.diff
• PHP 5.2.12 with Suhosin: patch-php5.2.12.suhosin.ext_standard_syslog.diff

[Update: the patches still work for PHP 5.3.6]
[Update2: finally got around to write a Feature Request #54144]

When I implemented this I could not find documentation about this, so I wrote a small how-to.

First create a template file (I use OpenOffice) with filler text. Include all images, fields, tables, paragraph styles, etc. you want to use later. Save the file in ODT format.

A .odt file is a zip file containing all document components as XML files (as well all embedded files like pictures). Use unzip to extract the content into a subfolder.

[mschuett@dagny] ~> mkdir newdoc && unzip -d newdoc Untitled 1.odt
Archive:  Untitled 1.odt
 extracting: newdoc/mimetype
   creating: newdoc/Configurations2/statusbar/
  inflating: newdoc/Configurations2/accelerator/current.xml
   creating: newdoc/Configurations2/floater/
   creating: newdoc/Configurations2/popupmenu/
   creating: newdoc/Configurations2/progressbar/
   creating: newdoc/Configurations2/menubar/
   creating: newdoc/Configurations2/toolbar/
   creating: newdoc/Configurations2/images/Bitmaps/
 extracting: newdoc/Pictures/1000000000000181000000AD6DC45DA5.png
  inflating: newdoc/content.xml
  inflating: newdoc/styles.xml
 extracting: newdoc/meta.xml
  inflating: newdoc/Thumbnails/thumbnail.png
  inflating: newdoc/settings.xml
  inflating: newdoc/META-INF/manifest.xml

The subdirectories Configurations2 and Thumbnails as well as the file settings.xml are not required and can be deleted. The file META-INF/manifest.xml contains a list of all files, so the corresponding entries should be removed from this list.

That leaves us with three significant files: meta.xml for document metadata, styles.xml for styles and page elements (headers, footers), and content.xml for the main text. Use xmllint --format (part of libxml) to make the XML somewhat readable and then open it in an editor to take a look at the general structure and to locate your filler texts. More information about the files can be found in the free book “OASIS OpenDocument Essentials”.

After a modification the files can be zipped again to verify the resulting ODF can be opened:

[mschuett@dagny] ~> cd newdoc && zip -r ../newdoc.odt * && cd ..

Now it’s up to you to write your application data into all the right places. I simply use str_replace() to substitute a number of variables, thus I have a PHP string with the text of content.xml and place holders like this:

 <text:p text:style-name="P2">%(FirstName) %(LastName)</text:p>
 <text:p text:style-name="P1">%(AddrComplement)</text:p>
 <text:p text:style-name="P1">%(Street)</text:p>
 <text:p text:style-name="P1">%(ZIP) %(City)</text:p>
 <text:p text:style-name="P1">%(Country)</text:p>

The replacement uses two arrays — one with all place holders and one with all strings to replace them with. (Note: Because the database is still in Latin-1 but the XML files declare a UTF-8 encoding, all strings have to be converted. The call to utf8() is just shorthand for a call to mb_convert_encoding().)

$replace_from = array(
    "%(FirstName)",
    "%(LastName)",
    // etc.
);
$replace_to = array(
    utf8($dbentry['firstname']),
    utf8($dbentry['lastname']),
    // etc.
);
$content_xml = str_replace($replace_from, $replace_to, $ODT['content_xml']);

When the document’s content is thus prepared, the files have to be zipped and sent to the user. In this example I change only the file content.xml and decide to zip all other files beforehand. (Because my files contain pictures I assume this is more efficient than creating everything on the fly.)

[mschuett@dagny] ~> cd newdoc && zip -r ../template.zip * --exclude content.xml && cd ..

Finally this is the output function at the end of the PHP file:

// headers for download and correct MIME type
header('Content-disposition: attachment; filename="letter.odt"');
header('Content-Type: application/vnd.oasis.opendocument.text');
 
// this is slightly magic
File_Archive::extract(
    File_Archive::readMulti(    // read sources
        array(
            // a) an existing archive
            File_Archive::read("template.zip/"),
            // b) our memory buffers to be named
            File_Archive::readMemory($content_xml, "content.xml"),
        )
    ),
    File_Archive::toArchive(  // combine sources into one output
        'letter.odt',
        File_Archive::toOutput(false),  // send to stdout = browser
        $type = 'zip'
    )
);

First the HTTP headers are sent, so the browser knows it will receive a file in OpenDocument format (it should then ask the user whether to save the file or open it immediately in a word processor). The PEAR package File_Archive is used for all zipfile actions: first the prepared zipfile is read, then the string $content_xml is added with file name "content.xml", at last the new zipfile is sent to the user. And that’s it.

If necessary the other files can be customized in the same way. If the ODT files are not only used for printing but are archived or send to an end-user then you probably want to set a correct document creation date, generator, author information, etc. in meta.xml.

If you are looking for PHP library support of OpenDocument files then take a look at the PEAR OpenDocument class. Just like all other projects I have found it is in early alpha status, but now that Christian Weiske took over maintainership recently it seems to be the only one under active development.

Last but not least: you can use the ODF Validator to validate your documents against the ODF Specification (without having to rely on the “it is correct if OOo can open it” approach).

Es ist eine direkte Erweiterung der Klasse DTA von Hermann Stainer und soll dem bestehenden PEAR-Paket hinzugefügt werden; wegen SVN-Problemen ist das bisher aber noch nicht geschehen…  Daher veröffentliche ich den Code erstmal hier: DTAZV.php

Die Implementierung erfolgte auf Grundlage der DTAZV-Spezifikation der Bundesbank vom 22. November (pdf). Zur Korrektheit kann ich nur sagen dass die erzeugten Dateien von SFirm importiert werden und es im praktischen Einsatz seit März 2008 noch keine Probleme gab [Korrektur: der Sprung vom Test- auf's Produktivsystem steht noch aus]; für darüber hinausgehende Urteile fehlt mir die Grundlage, dazu bräuchte ich Testdatensätze oder eine Referenzimplementierung.

Außerdem habe ich noch einen Patch für die DTA.php mit allen Änderungen die ich an der Grundklasse selbst vorgenommen hab (ergänzt mehr Sonderzeichen, zusätzliche Parameter-Validierung und eine neue Methode count()).