Jason E. Sweat's weblog

There is an issue which kind of bugged me with external dependencies in my source code documentation after it is parsed by phpDocumentor, the source code doc does not know much about the external libraries, and therefore leaves references to them dangling…

This particular problem is highlighted when you use the source code highlighting feature (BTW: very cool feature!!!) and have a class method which returns an external class. Where you can normally click on the return class and jump to it’s documentation in your source code, you are only told the name of the class when it is external to the project.

This is rightfully so, after all “You don’t know what you don’t know.” You can not expect phpDocumentor to know about your external dependencies in a vacuum. What I have come up with in my own experimentation is to stub in a small file in the project called external.php which documents the classes as a 50,000 ft. level, and provides a link to the source of the external library. Obviously, you do not want to include this file in you project, as it would cause class re-definitions and all sorts of problems, but as a stop gap for documentation, it seems to work well.

external.php:

<?php

< ?php
/**
 *    Identify external dependancies for library classes
 *    for purposes of phpDocumentor inclusion
 *
 *    !!!WARNING! WARNING! WARNING!!!
 *            Do not include this file in the project code.
 *            It will cause the application to break. This file
 *            is for documentation only.
 *    !!!WARNING! WARNING! WARNING!!!
 *
 *    @author        Jason E. Sweat
 *    @since        2004-11-20
 *    @version    $Id: external.php,v 1.3 2004/11/22 16:03:35 sweatje Exp $
 *    @package    YourProject
 *    @subpackage    external
 */

/**#@+
 * SimpleTest 
 * @link http://simpletest.sf.net/
 */
class UnitTestCase {}
class WebTestCase {}
/**#@-*/

/**#@+
 * WACT
 * Web Application Component Toolkit
 * @link http://wact.sf.net/
 */
class WACT {}
class FormView {}
class ArrayDataSet extends WACT {}
class DataSpace extends WACT {}
class DatasetDecorator extends WACT {}
/**#@-*/

/**#@+
 * SPL
 * Standard PHP Library
 * @link http://www.php.net/~helly/php/ext/spl/
 */
class Exception {}
/**#@-*/

?>

This "fix" seems to clean up the class tree significantly where you have extended classes from external libraries as well.

I think that as a convention, I will now have all setters return $this instead of null. I arrived at this decision from messing around with the Specification design pattern (“Domain Driven Design” by Eric Evans, pg. 224). When I was creating a chain of specifications in my Policy object, I ended up making a large number of Factory methods, one for each concrete Specification type. During one refactoring, I added an attribute with a setter for if this was a “normal” specification or just a “warning” specification (one that would log a normal error message if not satisfied, but still allow the policy to take place if other specifications on the chain were sufficient). A little more info on my experiment with the Specification pattern here.

Anyway, you end up with a factory method like this:

<?php

    private function fieldEquals($field, $value, $msg, $logdesc) {
        return new FieldEqualsSpecification($field, $value, $this->log, $msg, $logdesc);
    }

?>

And if you want a small variation of this method that sets the warning, you can do:

<?php

    private function fieldEqualsWarn($field, $value, $msg, $logdesc) {
        $ret = $this->fieldEquals($field, $value, $msg, $logdesc);
        $ret->setWarning();
        return $ret;
    }

?>

But, if you have the Specification::setWarning() method return $this instead of null (void) you can eliminate the temporary variable in the second Factory method and end up with this code:

<?php

    private function fieldEqualsWarn($field, $value, $msg, $logdesc) {
        return  $this->fieldEquals($field, $value, $msg, $logdesc)->setWarning();
    }

?>

Breaking it down the way the PHP parser does, you get:
$this->fieldEquals() returns an object
which we call the setWarning() method on
which returns an object that we return from this method

I’ll have to contemplate it a bit, but “When in doubt, return $this” may become a mantra for my PHP5 development 😉

Ages ago (it seems anyway, Feb 2003 timeframe), I wrote a book for Wrox ( PHP Graphics Handbook (Wrox) – ISBN: 1-86100-836-8 ). Wrox published it and then immediately went bankrupt. For a brief period of time they had the source code downloads for the first four chapters available on their web site as 8368_part1.zip. When I pointed out that my chapters were missing from the download, they replaced 8368_part1.zip with 8368_part2.zip instead of adding it as an additional file. I somehow failed to ever keep a copy of 8368_part1.zip.

Over the years, several people have tried to contact me regarding obtaining 8368_part1.zip. If anyone managed to download a copy and hold onto it, please email me a copy (jsweat_php AT yahoo DOT com).

Thanks!