Zend Framework 1.8 Web Application Development book review

2009-10-14T21:22:00.005Z

As the days are rapidly getting shorter, my reading appetite grows potentially and this evening I finished the 'Zend Framework 1.8 Web Application Development' book written by Keith Pope. While Keith worked on the book, I peeked several times at it's tutorial application, dubbed the Storefront, to get me going with the new Zend_Application component. Looking at it's code made me feel certain to get another great digest of the new features and components of version 1.8, and also a different practical perspective on web application development with the Zend Framework, once the book has been published. Therefor I got in touch with the publisher Packt and fortunately got a copy of which I'd like to share a personal review in this blog post.

What's in it?

The book opens with a quick run-through of the Model-View-Controller (MVC) architecture by creating a project structure via Zend_Tool and building a first very basic web application. While this introduction intentionally skips over a lot of details, the following chapter provides very detailed insights into the Zend Framework's MVC components by explaining the surrounded objects, the Design Patterns they are based upon and their interactions.

After laying out that hefty block of theory the aforementioned tutorial application is introduced and built incrementally over several chapters; each one going into more detail for the specific application aspect. The highlight content of these chapters reach from introducing the Fat Model Skinny Controller concept, thoughts on Model design strategies which are reflected in a custom Storefront Model design, to developing application specific Front Controller Plugins, Action-Helpers, and View-Helpers. The application walk-through is completed by looking at general techniques to optimize the Storefront application and by building an automated PHPUnit Test Suite of functional tests utilizing Zend_Test to keep the Zend Framework based application self-reliant and refactorable.

Conclusion

The book by Keith Pope provides any interested PHP developer, who's not already sold on a specific framework, a thorough introduction to the vivid Zend Framework and it's use in a MVC based web application development context. The content of the book is delivered in a fluent, very enthusiastic and 'knowledge-pillowed' writing tone. By implementing or working through the Storefront application seasoned web developers using older versions of the Framework will get a good blue sheet on new components like Zend_Application and it's implication in the bootstrapping process; while new developers tending towards picking up the Zend Framework will get a current and well compiled guide, which might first start off with a steep learning-curve but will turn into profund knowledge once hanging in there.

The only thing that seemed a bit odd to me, was the utilization of Ant instead of Phing as the build tool for the Storefront application to set the application environment, to remove all require_once statements from the framework library and to run the PHPUnit Test Suite; but this might also be inflicted by my Phing nuttiness.

Logging to MongoDb and accessing log collections with Zend_Tool

2009-09-19T19:00:00.012Z

Influenced by a recent blog post of a colleague of mine and by being kind of broke on a Saturday night; I tinkered with the just recently discovered MongoDb and hooked it into the Zend_Log environment by creating a dedicated Zend_Log_Writer. The following post will therefore present a peek at a prototypesque implementation of this writer and show how the afterwards accumulated log entries can be accessed and filtered with a custom Zend_Tool project provider.

Logging to a MongoDb database

The following steps assume that an instance of a MongoDb server is running and that the required PHP MongoDb module is also installed and loaded. To by-pass log entries to a MongoDb database there is a need to craft a proper Zend_Log_Writer. This can be achieved by extending the Zend_Log_Writer_Abstract class, injecting a Mongo connection instance and implementing the actual write functionality as shown in the next listing.

<?php
require_once 'Zend/Log/Writer/Abstract.php';

class Recordshelf_Log_Writer_MongoDb extends Zend_Log_Writer_Abstract
{
    private $_db;
    private $_connection;
    
    /**
     * @param Mongo $connection The MongoDb database connection
     * @param string $db The MongoDb database name
     * @param string $collection The collection name string the log entries 
     */
    public function __construct(Mongo $connection, $db, $collection)
    {
        $this->_connection = $connection;
        $this->_db = $this->_connection->selectDB($db)->createCollection(
            $collection);
    }
    public function setFormatter($formatter)
    {
        require_once 'Zend/Log/Exception.php';
        throw new Zend_Log_Exception(get_class() . ' does not support formatting');
    }
    public function shutdown()
    {
        $this->_db = null;
        $this->_connection->close();
    }
    protected function _write($event)
    {
        $this->_db->insert($event);
    }
}

With the MongoDb writer available and added to the library directory of the application it's now possible to utilize this new storage backend as usual with the known Zend_Log component. The Mongo connection injected into the writer is configured via Zend_Config and initialized via the Zend_Application bootstrapping facility as shown in the listings below.

application/configs/application.ini


[production]
app.name = recordshelf

....

log.mongodb.db = zf_mongo
log.mongodb.collection = recordshelf.log
log.mongodb.server = localhost
log.priority = Zend_Log::CRIT

....

application/Bootstrap.php

<?php

class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    protected $_logger;

    protected function _initConfig()
    {
        Zend_Registry::set('config', new Zend_Config($this->getOptions()));
    }

    protected function _initLogger()
    {
        $this->bootstrap(array('frontController', 'config'));
        $config = Zend_Registry::get('config');     
        
        $applicationName = $config->app->get('name', 'recordshelf');
        $mongoDbServer = $config->log->mongodb->get('server', '127.0.0.1');
        $mongoDbName = $config->log->mongodb->get('db', "{$applicationName}.logs");
        $mongoDbCollection = $config->log->mongodb->get('collection', 'entries');
        
        $logger = new Zend_Log();
        $writer = new Recordshelf_Log_Writer_MongoDb(new Mongo($mongoDbServer), 
            $mongoDbName, $mongoDbCollection);
        
        if ('production' === $this->getEnvironment()) {
            $priority = constant($config->log->get('priority', Zend_Log::CRIT));
            $filter = new Zend_Log_Filter_Priority($priority);
            $logger->addFilter($filter);
        }
        $logger->addWriter($writer);
        $this->_logger = $logger;
        Zend_Registry::set('log', $logger);
    }
}

controllers/ExampleController.php

<?php

class ExampleController extends Zend_Controller_Action
{
    private $_logger = null;
    
    public function init()
    {
        $this->_logger = Zend_Registry::get('log');
    }

    public function fooAction()
    {
        $this->_logger->log('A debug log message from within action ' . 
            $this->getRequest()->getActionName(), Zend_Log::DEBUG);
    }

    public function barAction()
    {
        $this->_logger->log('A debug log message from within ' . 
            __METHOD__, Zend_Log::DEBUG);
    }
}

Accessing the log database with a Zend_Tool project provider

After handling the application-wide logging with the MongoDb writer sooner or later the issue to access the gathered log entries will rise. For this mundane and recurring use case the ProjectProvider provider of the Zend_Tool framework is an acceptable candidate to hook a custom action into the Zend_Tool environment of a given project. Therefor a new Zend_Tool_Project Project provider is first scaffolded via the forthcoming command.

sudo zf create project-provider mongodb-logs filter

Second the generated provider skeleton its filter action is enliven with the logic to query the MongoDb database and the stored log collection. The action to come accepts three arguments to filter the stored log entry results by a specific date in the format of 'YYYY-MM-DD' and a given Zend_Log priority (currently limited to the constants defined in Zend_Log) in a specific application environment. The next listing shows the implementation of the import action of the MongodbLogsProvider project provider; which is clearly, as it's length indicates, in need for a clean-up task.

providers/Mongodb-logsProvider.php

<?php
require_once 'Zend/Tool/Project/Provider/Abstract.php';
require_once 'Zend/Tool/Project/Provider/Exception.php';
require_once 'Zend/Date.php';
require_once 'Zend/Validate/Date.php';
require_once 'Zend/Log.php';
require_once 'Zend/Config/Ini.php';

class MongodbLogsProvider extends Zend_Tool_Project_Provider_Abstract
{

    public function filter($date = null, $logPriority = null, 
        $env = 'development')
    {
        $ref = new Zend_Reflection_Class('Zend_Log');
        $logPriorities = $ref->getConstants();
        
        if (in_array(strtoupper($date), array_keys($logPriorities)) || 
            in_array(strtoupper($date), array_values($logPriorities))) {
            $logPriority = $date;
            $date = null;
        }
        if (!is_null($date)) {
            $validator = new Zend_Validate_Date();
            if (!$validator->isValid($date)) {
                $exceptionMessage = "Given date '{$date}' is not a valid date.";
                throw new Zend_Tool_Project_Provider_Exception($exceptionMessage);
            }
            $dateArray = array();
            list($dateArray['year'], $dateArray['month'], $dateArray['day']) = 
                explode('-', $date);
            $date = new Zend_Date($dateArray);
        } else {
            $date = new Zend_Date();
        }
        $date = $date->toString('Y-MM-dd');
                
        if (!is_null($logPriority)) {
            
            if (!is_numeric($logPriority)) {
                $logPriority = strtoupper($logPriority);
                if (!in_array($logPriority, array_keys($logPriorities))) {
                    $exceptionMessage = "Given priority '{$logPriority}' is not defined.";
                    throw new Zend_Tool_Project_Provider_Exception($exceptionMessage);
                } else {
                    $logPriority = $logPriorities[$logPriority];
                }
            }
            if (!in_array($logPriority, array_values($logPriorities))) {
                $exceptionMessage = "Given priority '{$logPriority}' is not defined.";
                throw new Zend_Tool_Project_Provider_Exception();
            }
            $priorities = array_flip($logPriorities);
            $priorityName = $priorities[$logPriority];
        }
        
        if ($env !== 'development' && $env !== 'production') {
            $exceptionMessage = "Unsupported environment '{$env}' provided.";
            throw new Zend_Tool_Project_Provider_Exception();
        }
        $config = new Zend_Config_Ini('./application/configs/application.ini', 
            $env);

        $applicationName = $config->app->get('name', 'recordshelf');
        $mongoDbServer = $config->log->mongodb->get('server', '127.0.0.1');
        $mongoDbName = $config->log->mongodb->get('db', "{$applicationName}.logs");
        $mongoDbCollection = $config->log->mongodb->get('collection', 'entries');
    
        try {
            $connection = new Mongo($mongoDbServer);
            $db = $connection->selectDB($mongoDbName)->createCollection(
                $mongoDbCollection);
        } catch (MongoConnectionException $e) {
            throw new Zend_Tool_Project_Provider_Exception($e->getMessage());
        }
        $dateRegex = new MongoRegex("/$date.*/i");
        
        if (is_null($logPriority)) {
            $query = array('timestamp' => $dateRegex);
            $appendContentForResults = "Found #amountOfEntries# log entrie(s) "
               . "on {$date}";
            $appendContentForNoResults = "Found no log entries on {$date}";
        } else {            
            $query = array('priority' => (int) $logPriority, 
                'timestamp' => $dateRegex);
            $appendContentForResults = "Found #amountOfEntries# log entrie(s) "
                . "for priority {$priorityName} on {$date}";
            $appendContentForNoResults = "Found no log entries for priority "
                . "{$priorityName} on {$date}";
        }
        
        $cursor = $db->find($query);
        $amountOfEntries = $cursor->count();

        if ($amountOfEntries > 0) {
            $content = str_replace('#amountOfEntries#', $amountOfEntries, 
                $appendContentForResults);
            $this->_registry->getResponse()->appendContent($content);
            foreach ($cursor as $id => $value) {
                $content = "{$id}: {$value['timestamp']} > ";
                if (is_null($logPriority)) {
                    $content.= "[{$value['priorityName']}] ";
                }
                $content.= "{$value['message']}";
                $this->_registry->getResponse()->appendContent($content);
            }
        } else {
            $content = $appendContentForNoResults;
            $this->_registry->getResponse()->appendContent($content);
        }
        $connection->close();
    }
}

The coming outro screenshots show two use cases for the filter action of the MongodbLogsProvider issued against the zf command line client. The first screenshot shows the use case where all log entries for the current day are queried, while the second one shows the use case where all log entries for a specific date and log priority are queried and fed back to the user.

Kicking off custom Phing task development with TextMate

2009-08-22T13:08:00.004Z

As a reader of this blog you migth have noticed that from time to time I like to utilize Phing's ability to write custom tasks. Though that's not an everyday routine for me and therefor I might, depending on my form of the day, end up with some real smelly code where for example the task's properties validation is handled in the task's main worker method. This is actually a bad habit/practice I'm aware of and to improve my future endeavours in custom Phing task development, I bended TextMate's snippet feature to my needs.

Snippets in TextMate are a very powerful feature that can be used to insert code that you do not want to type again and again, or like in my case might have forgotten over a certain time.

The next code listing shows the snippet providing a basic custom Phing task class skeleton which can be utilized over and over at the beginning of the implementation activities.

<?php
require_once 'phing/Task.php';

class ${1:CustomName}Task extends Task
{
    private \$_${2:property} = null;
    
    /**
     * @param string \$${2:property} ${3:description}
     */
    public function set${2/./\u$0/}(\$${2:property})
    {
        \$this->_${2:property} = trim(\$${2:property});
    }
    /**
     * Initializes the task environment if necessary
     */
    public function init()
    {
    }
    /**
     * Does the task main work or delegates it
     * @throws BuildException
     */
    public function main()
    {
        \$this->_validateProperties();
    }
    /**
     * Validates the task properties
     * @throws BuildException
     */
    private function _validateProperties()
    {
        if (is_null(\$this->_${2:property})) {
            throw new BuildException('${4:message}.');
        }$0
    }
}

To apply the snippet, after installing it, on a PHP source file it can either be selected from the Bundles menue or more comfortable via the assigned tab trigger i.e. ctask. After triggering the snippet it's possible to properly name the task under development and dynamically set it's first property, which is also treated as a mandatory property in the extracted _validateProperties method.

The outro image shows the above stated snippet in the TextMate Bundle Editor and it's configuration.

Scaffolding, implementing and using project specific Zend_Tool_Project_Providers

2009-07-04T15:41:00.011+01:00

Working on a project involving several legacy data migration tasks, I got curious what the Zend_Tool_Project component of the Zend Framework offers to create project specific providers for the above mentioned tasks or ones of similar nature. Therefore the following post will try to show how these providers can be developed in an iterative manner by scaffolding them via the capabilities of the Zend_Tool_Project ProjectProvider provider, enlived with action/task logic, and be used in the project scope.

Scaffolding project specific providers

All following steps assume there is a project available i.e. recordshelf initially created with the Zend_Tool_Project Project provider and that the forthcoming commands are issued from the project root directory against the zf command line client. The scaffolding of a project specific provider can be triggered via the create action of the ProjectProvider provider by passing in the name of the provider i.e. csv and it's intended actions. As the next console snippet shows it's
possible to specify several actions as a comma separated list.

sudo zf create project-provider csv importSpecials,importSummersale

After running the command the project's profile .zfproject.xml has been modified and a new providers directory exists in the project root directory containing the scaffolded Csv provider. The next code snippet shows the initial Csv provider class skeleton and its two empty action methods named importSpecials and importSummersale. At the point of this writing, using the Zend Framework 1.8.4 and PHP 5.2.10 on a Mac OS X system the generated Csv provider code or the mapping in the .zfproject.xml is incorrect, but can be fixed by renaming the class from CsvProvider to Csv.

<?php

require_once 'Zend/Tool/Project/Provider/Abstract.php';
require_once 'Zend/Tool/Project/Provider/Exception.php';

class CsvProvider extends Zend_Tool_Project_Provider_Abstract
{

    public function importSpecials()
    {
        /** @todo Implementation */
    }

    public function importSummersale()
    {
        /** @todo Implementation */
    }


}

Implementing the action logic

Having the project provider class skeleton ready to get going, it's time to enliven the actions with their intended features by using either other components of the Zend Framework, any suitable third party library or plain-vanilla PHP. For the sake of brevity I decided to implement only the importSpecials action which transforms the data of a known CSV file structure into a relevant database table. The CSV parsing steps shown next might not be that sophisticated, as their sole purpose is to illustrate an exemplary implementation of a project specific provider action.

<?php

require_once 'Zend/Tool/Project/Provider/Abstract.php';
require_once 'Zend/Tool/Project/Provider/Exception.php';

class Csv extends Zend_Tool_Project_Provider_Abstract
{
    private function _isProjectProviderSupportedInProject(Zend_Tool_Project_Profile $profile, 
        $projectProviderName)
    {
        $projectProviderResource = $this->_getProjectProfileResource($profile, 
            $projectProviderName);
        return $projectProviderResource instanceof Zend_Tool_Project_Profile_Resource;
    }
    
    private function _isActionSupportedByProjectProvider(Zend_Tool_Project_Profile $profile, 
        $projectProviderName, $actionName)
    {
        $projectProviderResource = $this->_getProjectProfileResource($profile, 
            $projectProviderName);
        $projectProviderAttributes = $projectProviderResource->getContext()
                                                             ->getPersistentAttributes();
        return in_array($actionName, explode(',', $projectProviderAttributes['actionNames']));
    }
    
    private function _getProjectProfileResource(Zend_Tool_Project_Profile $profile, 
        $projectProviderName)
    {
        $profileSearchParams[] = 'ProjectProvidersDirectory';
        $profileSearchParams['ProjectProviderFile'] = 
            array('projectProviderName' => strtolower($projectProviderName));
        return $profile->search($profileSearchParams);  
    }

    public function importSpecials($csvFile, $env = 'development')
    {
        $relatedTablename = 'specials';
        
        if (!$this->_isProjectProviderSupportedInProject($profile, __CLASS__)) {
            throw new Exception("ProjectProvider Csv is not supported in this project.");
        }
        if (!$this->_isActionSupportedByProjectProvider($profile, __CLASS__, __FUNCTION__)) {
            $exceptionMessage = "Action 'importSpecials' is not supported by "
                . "the Csv ProjectProvider in this project.";
            throw new Exception($exceptionMessage);
        }

        if (!file_exists($csvFile)) {
            throw new Exception("Given csv-file '{$csvFile}' doesn't exist.");
        }
        
        $importEnvironment = trim($env);
        if ($importEnvironment !== 'development' && $importEnvironment !== 'production') {
            throw new Exception("Unsupported environment '{$importEnvironment}' provided.");
        }
        
        $csvHandle = fopen($csvFile, "r");
        
        if (!$csvHandle) {
            throw new Exception("Unable to open given csv-file '{$csvFile}'.");
        }
        
        $config = new Zend_Config_Ini('./application/configs/application.ini', 
            $importEnvironment);
        $db = Zend_Db::factory($config->database);

        $db->query("TRUNCATE TABLE {$relatedTablename}");
        echo "Truncated the project '{$relatedTablename}' database table." . PHP_EOL;
        
        $rowCount = $insertCount = 0;
        
        while (($csvLine = fgetcsv($csvHandle)) !== false) {
            if ($rowCount > 0) {
                $insertRow = array(
                    'product_name' => $csvLine[0],
                    'product_image_path' => $csvLine[1],
                    'price' => $csvLine[2],
                    'special_until' => $csvLine[3]
                );
                $db->insert($relatedTablename, $insertRow);
                ++$insertCount;
            }
            ++$rowCount;
        }
        fclose($csvHandle);
        $importMessage = "Imported {$insertCount} rows into the project "
            . "'{$relatedTablename}' database table.";
        echo $importMessage;
    }
    ...
}

Making providers and actions pretendable

To make project specific providers its actions pretendable and thereby providing some kind of user documentation the provider classes have to implement a marker interface called Zend_Tool_Framework_Provider_Pretendable. For making a action of a provider pretendable and giving some feedback to the user, the request is checked if the action has been issued in the pretend mode; which is possible by adding -p option to the issued zf command line client command. The next code snippet shows how the above stated Csv provider and its importSpecials action is made pretendable.

<?php

require_once 'Zend/Tool/Project/Provider/Abstract.php';
require_once 'Zend/Tool/Project/Provider/Exception.php';

class Csv extends Zend_Tool_Project_Provider_Abstract implements 
    Zend_Tool_Framework_Provider_Pretendable
{

    public function importSpecials($csvFile, $env = 'development')
    {
        ...
        
        if ($this->_registry->getRequest()->isPretend()) {
            $pretendMessage = "I would import the specials data provided in {$csvFile} "
                . "into the project '{$relatedTablename}' database table.";
            echo $pretendMessage;
        } else {
            ...   
        }
    }
    ...
}

Using project specific providers

To use the bundled up capabilities of project specific providers, these have to made accessable to the zf command line client by putting them in the include_path. Currently I discovered no best practice for doing so only for single project scopes and simply added the path to the project to my php.ini and thereby global include_path; another approach might be to add the project name as a prefix to the Provider. After doing so it's possible to get an overview of all with the Zend_Tool_Project shipped providers plus the project specific providers and their offered actions by issuing the zf --help command as shown in the next screenshot. To ensure that project specific providers and its actions are only runnable in projects which support them, it is necessary to check if these and the offered action exists as resources in the project its profile .zfproject.xml file as shown in the implementation of the importSpecials action in one of above code snippets.

As shown in the previous screenshot the first character of the project specific providers are omitted, this is another minor bug which might be fixed in one of the forthcoming Zend Framework releases. The current workaround for this issue is simply to type the command exactly as shown in the help. The outro screenshot shows how the import-specials action of the project specific Csv provider is issued against the zf command line client and its provided user feedback after an successfull import against the projects development database.

Testing Phing buildfiles with PHPUnit

2009-05-10T14:15:00.003Z

While transforming some of the Ant buildfile refactorings described in Julian Simpson's seminal essay into a Phing context, it felt plainly wrong that I didn't have any tests for the buildfile to back me up on obtaining the pristine behaviour throughout the process. While Ant users can rely on an Apache project called AntUnit there are currently no tailor-made tools available for testing or verifying Phing buildfiles. Therefor I took a weekend off, locked myself in the stuffy lab, and explored the abilities to test Phing buildfiles respectively their included properties, targets and tasks with the PHPUnit testing framework. In case you'd like to take a peek at the emerged lab jottings, keep on scanning.

Introducing the buildfile under test

The buildfile that will be used as an example is kept simple, and contains several targets ranging from common ones like initializing the build environment by creating the necessary directories to more specific ones like pulling an external artifact from GitHub. To get an overview of the buildfile under test have a look at the following listing.

<?xml version="1.0" encoding="UTF-8"?>
<project name="test-example" default="build" basedir=".">

<property name="project.basedir"
          value="." override="true" />
<property name="github.repos.dir"
          value="${project.basedir}/build/github-repos" override="true" />

<target name="clean" depends="clean-github-repos"
        description="Removes runtime build artifacts">
  <delete dir="${project.basedir}/build" includeemptydirs="true"
          verbose="false" failonerror="true" />
  <delete dir="${project.basedir}/build/reports"
          includeemptydirs="true" verbose="false" failonerror="true" />
</target>

<target name="clean-github-repos" description="Removes runtime build artifacts">
  <delete dir="${github.repos.dir}" includeemptydirs="true" failonerror="true" />
</target>

<target name="-log-build" description="A private target which should only be invoked internally">
  <!-- omitted -->
</target>

<target name="build" depends="clean" description="Builds the distributable product">
  <!-- omitted -->
</target>

<target name="database-setup" description="Sets up the database structure">
  <!-- omitted -->
</target>

<target name="init" description="Initalizes the build by creating directories etc">
  <mkdir dir="${project.basedir}/build/logs/performance/" />
  <mkdir dir="${project.basedir}/build/doc" />
  <mkdir dir="${project.basedir}/build/reports/phploc" />
</target>

<target name="init-ad-hoc-tasks"
        description="Initalizes the ad hoc tasks for reusability in multiple targets">      
  <adhoc-task name="github-clone"><![CDATA[
      class Github_Clone extends Task {
        private $repository = null;
        private $destDirectory = null;

        function setRepos($repository) {
            $this->repository = $repository;
        }
        function setDest($destDirectory) {
            $this->destDirectory = $destDirectory;
        }
        function main() {
            // Get project name from repos Uri
            $projectName = str_replace('.git', '',
                substr(strrchr($this->repository, '/'), 1));

            $gitCommand = 'git clone ' . $this->repository . ' ' .
                $this->destDirectory . '/' . $projectName;

            exec(escapeshellcmd($gitCommand), $output, $return);

            if ($return !== 0) {
                throw new BuildException('Git clone failed');
            }
            $logMessage = 'Cloned Git repository ' . $this->repository .
                ' into ' . $this->destDirectory . '/' . $projectName;
            $this->log($logMessage);
        }
      }
  ]]></adhoc-task>

  <echo message="Intialized github-clone ad hoc task." />
</target>

<target name="github" depends="init-ad-hoc-tasks, clean-github-repos"
        description="Clones given repositories from GitHub">
  <github-clone repos="git://github.com/raphaelstolt/phploc-phing.git"
                dest="${github.repos.dir}" />
</target>
</project>

Testing the buildfile

All tests for the buildfile under test will be bundled, like 'normal' tests, in a class i.e. BuildfileTest extending the PHPUnit_Framework_TestCase class. When testing buildfiles it's possible to build some tests around the actual buildfile XML structure, by utilizing the xpath method of PHP's SimpleXMLElement class and asserting against the XPath query results, or around the dispatching of specific targets and asserting against the expected build artifacts. Furthermore these two identified groups, structure and artifact, can be used to organize the accumulating tests via PHPUnit's @group annotation.

To be able to dispatch specific build targets and feed them with properties if necessary I additionally developed a very basic build runner shown in the next code listing.

<?php
class Phing_Buildfile_Runner {

    private $_buildfilePath = null;

    public function __construct($buildfilePath) {
        if (!file_exists($buildfilePath)) {
            throw new Exception("Buildfile '{$buildfilePath}' doesn't exist");
        }
        $this->buildfilePath = realpath($buildfilePath);
    }
    public function runTarget($targets = array(), $properties = array()) {
        $runTargetCommand = "phing "
                          . "-f {$this->buildfilePath} ";
        if (count($targets) > 0) {
            foreach ($targets as $target) {
                $runTargetCommand.= $target . " ";
            }
        }
        if (count($properties) > 0) {
            foreach ($properties as $property => $value) {
                $runTargetCommand.= "-D{$property}={$value} ";
            }       
        }
        exec(escapeshellcmd($runTargetCommand), $output, $return);
        return array('output' => $output, 'return' => $return);
    }
}

Out of the box PHPUnit's assertion pool provides all the utilities to test buildfiles; although it would be cleaner to create domain specfic assertions for this testing domain this technique will be ignored for the sake of brevity.

After an initial 1000ft view on how to test buildfiles let's jump into the actual testing of a structural aspect of the buildfile under test. The test to come shows how to verify that a clean target is defined for playing along in the build orchestra by querying a XPath expression against the buildfile XML and asserting that a result is available.

/**
* @test
* @group structure
*/
public function buildfileShouldContainACleanTarget() {
    $xml = new SimpleXMLElement($this->_buildfileXml);
    $cleanElement = $xml->xpath("//target[@name='clean']");
    $this->assertTrue(count($cleanElement) > 0,
        "Buildfile doesn't contain a clean target");
}

The next artifactual test raises the bar an inch, by verifying that the defined init target of the build does initialize the build environment correctly, or to pick up the orchestra metaphor again that the specific instrument plays along and holds the directed tone. Therefor the build runner executes the target and afterwards asserts a list of expected artifacts against the current state of the build process.

/**
* @test
* @group artifact
*/
public function initTargetShouldCreateInitialBuildArtifacts() {
    $this->_isTearDownNecessary = true;
    $this->_buildfileRunner->runTarget(array('init'));
    $expectedInitArtifacts = array(
        "{$this->_buildfileBasedir}/build",
        "{$this->_buildfileBasedir}/build/logs/performance/",
        "{$this->_buildfileBasedir}/build/doc",
        "{$this->_buildfileBasedir}/build/reports"
    );

    foreach ($expectedInitArtifacts as $artifact) {
        $this->assertFileExists($artifact,
            "Expected file '{$artifact}' doesn't exist");
    }
}

The next code listing shows the whole picture of the BuildfileTest class containing additional test methods verifying different aspects of the buildfile under test and also the innards of the setup and teardown method.

The main assignment of the setup method is to load the XML of the buildfile under test and to intialize the build runner so an instance is available for an use in artifactual tests. The teardown method its sole responsibility is to reset the build state by running the clean target of the buildfile.

<?php
require_once 'PHPUnit/Framework.php';
require_once 'Phing/Buildfile/Runner.php';

class ExampleBuildfileTest extends PHPUnit_Framework_TestCase {
    
    protected $_buildfileXml = null;
    protected $_buildfileName = null;
    protected $_buildfileBasedir = null;
    protected $_buildfileRunner = null;
    protected $_isTearDownNecessary = false;

    protected function setUp() {
        $this->_buildfileName = realpath('../../build.xml');        
        $this->_buildfileBasedir = dirname($this->_buildfileName);
        $this->_buildfileXml = file_get_contents($this->_buildfileName);
        $this->_buildfileRunner = new Phing_Buildfile_Runner(
            $this->_buildfileName);
    }
    
   protected function tearDown() {
        if ($this->_isTearDownNecessary) {
            $this->_buildfileRunner->runTarget(array('clean'));
        }
    }
    
    /**
     * @test
     * @group structure
     */
    public function targetBuildShouldBeTheDefaultTarget() {
        $xml = new SimpleXMLElement($this->_buildfileXml);
        $xpath = "//@default";
        $defaultElement = $xml->xpath($xpath);
        $this->assertSame('build', trim($defaultElement[0]->default), 
            "Buildfile doesn't have a default target named 'build'");
    }
    /**
     * @test
     * @group structure
     */
    public function propertyGithubReposDirShouldBeSet() {
        $xml = new SimpleXMLElement($this->_buildfileXml);
        $xpath = "//property[@name='github.repos.dir']/@value";
        $valueElement = $xml->xpath($xpath);
        $this->assertTrue($valueElement[0] instanceof SimpleXMLElement, 
            "Buildfile doesn't contain a 'github.repos.dir' property");
        $this->assertGreaterThan(1, strlen($valueElement[0]->value));
    }
    /**
     * @test
     * @group structure
     */
    public function buildfileShouldContainACleanTarget() {
        $xml = new SimpleXMLElement($this->_buildfileXml);
        $cleanElement = $xml->xpath("//target[@name='clean']");
        $this->assertTrue(count($cleanElement) > 0, 
            "Buildfile doesn't contain a clean target");
    }
    /**
     * @test
     * @group structure
     */
    public function targetLogBuildShouldBeAPrivateOne() {
        $xml = new SimpleXMLElement($this->_buildfileXml);
        $nameElement = $xml->xpath("//target[@name='-log-build']");
        $this->assertTrue(count($nameElement) > 0, 
            'Log build target is not a private target');
    }
    /**
     * @test
     * @group structure
     */
    public function targetBuildShouldDependOnCleanTarget() {
        $xml = new SimpleXMLElement($this->_buildfileXml);
        $xpath = "//target[@name='build']/@depends";
        $dependElement = $xml->xpath($xpath);
        $this->assertTrue(count($dependElement) > 0, 
            'Target build contains no depends attribute');
        $dependantTasks = array_filter(explode(' ', 
            trim($dependElement[0]->depends)
        ));        
        $this->assertContains('clean', $dependantTasks, 
            "Target build doesn't depend on the clean target");
    }
    /**
     * @test
     * @group structure
     */
    public function allDefinedTargetsShouldHaveADescriptionAttribute() {
        $xml = new SimpleXMLElement($this->_buildfileXml);
        $xpath = "//target";
        $targetElements = $xml->xpath($xpath);
        $describedTargetElements = array();
        foreach ($targetElements as $index => $targetElement) {
            $targetDescription = trim($targetElement->attributes()->description); 
            if ($targetDescription !== '') {
                $describedTargetElements[] = $targetDescription;
            }
        }
        $this->assertEquals(count($targetElements), 
            count($describedTargetElements), 
                'Description not for all targets set');
    }
    /**
     * @test
     * @group structure
     */
    public function githubCloneAdhocTaskShouldBeDefined() {
        $xml = new SimpleXMLElement($this->_buildfileXml);
        $xpath = "//target[@name='init-ad-hoc-tasks']/adhoc-task";
        $adhocElement = $xml->xpath($xpath);
        $this->assertSame('github-clone', 
            trim($adhocElement[0]->attributes()->name), 
                "Ad hoc task 'github-clone' isn't defined");
    }
    /**
     * @test 
     * @group artifact
     */
    public function initTargetShouldCreateInitialBuildArtifacts() {
        $this->_isTearDownNecessary = true;
        $this->_buildfileRunner->runTarget(array('init'));

        $expectedInitArtifacts = array(
            "{$this->_buildfileBasedir}/build", 
            "{$this->_buildfileBasedir}/build/logs/performance/", 
            "{$this->_buildfileBasedir}/build/doc",
            "{$this->_buildfileBasedir}/build/reports"
        );

        foreach ($expectedInitArtifacts as $artifact) {
            $this->assertFileExists($artifact, 
                "Expected file '{$artifact}' doesn't exist");
        }
    }
    /**
     * @test
     * @group artifact
     */
    public function sqlFilesForDatabaseSetupTargetShouldBeAvailable() {
        $expectedSqlFiles = array(
            "{$this->_buildfileBasedir}/sqlfiles", 
            "{$this->_buildfileBasedir}/sqlfiles/session-storage.sql", 
            "{$this->_buildfileBasedir}/sqlfiles/acl.sql", 
            "{$this->_buildfileBasedir}/sqlfiles/log.sql"
        );

        foreach ($expectedSqlFiles as $sqlFile) {
            $this->assertFileExists($sqlFile, "SQL file '{$sqlFile}' doesn't exist");
        }
    }
    /**
     * @test
     * @group artifact
     */
    public function githubTargetShouldFetchExpectedRepository() {
        $this->_isTearDownNecessary = true;
        $this->_buildfileRunner->runTarget(array('github'));
        $expectedGitRepository = "{$this->_buildfileBasedir}/build/"
                               . "github-repos/phploc-phing/.git";
        $this->assertFileExists($expectedGitRepository, 
            "Github target doesn't fetch the expected 'phploc-phing' repository");
    }
}

The outro screenshot shows the above stated test class run against the example buildfile on a Mac OS X system utilizing the --colors option; which by the way comes in really handy in combination with Stakeout.rb during the process of refactoring or extending/creating buildfiles the test-driven way.

Creating and using Phing ad hoc tasks

2009-04-18T00:48:00.006Z

Sometimes there are build scenarios where you'll badly need a functionality, like adding a MD5 checksum file to a given project, that isn't provided neither by the available Phing core nor the optional tasks. Phing supports developers with two ways for extending the useable task pool: by writing 'outline' tasks that will end up in a directory of the Phing installation or by utilizing the AdhocTaskdefTask, which allows to define custom tasks in the buildfile itself. The following post will try to outline how to define and use these inline tasks, by sketching an ad hoc task that enables the build orchestra to clone Git repositories from GitHub during a hypothetical workbench setup.

Creating the inline/ad hoc task

The AdhocTaskdefTask expects a name attribute i.e. github-clone for the XML element which will later referr to the ad hoc task and a CDATA section hosting the task implementation. Similar to 'outline' tasks the ad hoc task extends Phing's Task class, configures the task via attributes and holds the logic to perform. Unfortunately inline task implementations don't allow to require or include external classes available in the include_path, like Zend_Http_Client which I initially tried to use for an example task fetching short Urls from is.gd. This limits the available functions and classes to craft the task from to the ones built into PHP. The following buildfile snippet shows the implementation of the github-clone ad hoc task which is wrapped by a private target to encourage reusability and limit it's callability.

<target name="-init-ad-hoc-tasks" 
        description="Initializes the ad hoc task(s)">
  <adhoc-task name="github-clone"><![CDATA[
      class Github_Clone extends Task {

          private $repository = null;
          private $destDirectory = null;

          function setRepos($repository) {
              $this->repository = $repository;
          } 
          function setDest($destDirectory) {
              $this->destDirectory = $destDirectory;
          }
          function main() {
              // Get project name from repos Uri
              $projectName = str_replace('.git', '', 
                  substr(strrchr($this->repository, '/'), 1));

              $gitCommand = 'git clone ' . $this->repository . ' ' . 
                  $this->destDirectory . '/' . $projectName;

              exec(escapeshellcmd($gitCommand), $output, $return);

              if ($return !== 0) {
                  throw new BuildException('Git clone failed');
              }
              $logMessage = 'Cloned Git repository ' . $this->repository . 
                  ' into ' . $this->destDirectory . '/' . $projectName;
              $this->log($logMessage);
          }
      }
  ]]></adhoc-task>
  <echo message="Initialized github-clone ad hoc task." />
</target>

Using the ad hoc task

With the ad hoc task in the place to be, it's provided functionality can now be used from any target using the tasks XML element according to the given name i.e. github-clone in the AdhocTaskdefTask element earlier and by feeding it with the required attributes i.e. repos and dest. The next snippet allows you to take a peek at the complete buildfile with the ad hoc task in action.

<?xml version="1.0" encoding="UTF-8"?>
<project name="recordshelf" default="init-work-bench" basedir=".">
  
  <property name="github.repos.dir" value="./github-repos" override="true" />

  <target name="init-work-bench" 
          depends="-init-ad-hoc-tasks, -clone-git-repos" 
          description="Initializes the hypothetical workbench">
    <echo message="Initialized workbench." />
  </target>

  <target name="-clean-git-repos" 
          description="Removes old repositories before initializing a new workbench">
    <delete dir="${github.repos.dir}" includeemptydirs="true" failonerror="true" />
  </target>

  <target name="-init-ad-hoc-tasks" 
          description="Initializes the ad hoc task(s)">
    <adhoc-task name="github-clone"><![CDATA[
        class Github_Clone extends Task {

            private $repository = null;
            private $destDirectory = null;

            function setRepos($repository) {
                $this->repository = $repository;
            } 
            function setDest($destDirectory) {
                $this->destDirectory = $destDirectory;
            }
            function main() {
                // Get project name from repos Uri
                $projectName = str_replace('.git', '', 
                    substr(strrchr($this->repository, '/'), 1));

                $gitCommand = 'git clone ' . $this->repository . ' ' . 
                    $this->destDirectory . '/' . $projectName;

                exec(escapeshellcmd($gitCommand), $output, $return);

                if ($return !== 0) {
                    throw new BuildException('Git clone failed');
                }
                $logMessage = 'Cloned Git repository ' . $this->repository . 
                    ' into ' . $this->destDirectory . '/' . $projectName;
                $this->log($logMessage);
            }
        }
    ]]></adhoc-task>
    <echo message="Initialized github-clone ad hoc task." />
  </target>
  
  <target name="-clone-git-repos" depends="-clean-git-repos"
          description="Clones the needed Git repositories from GitHub">
    <github-clone repos="git://github.com/abc/abc.git" 
                  dest="${github.repos.dir}" />
    <github-clone repos="git://github.com/xyz/xyz.git" 
                  dest="${github.repos.dir}" />
  </target>
    
</project>

Favouring inline over 'outline' tasks?

The one big advantage of using inline tasks over 'outline' tasks is that they are distributed with the buildfile and are instantly available without the need to modify the Phing installation. Some severe disadvantages of inline tasks are the limitation to use only the core PHP functions and classes for the implementation, the introduction of an additional hurdle to verify the task behaviour via PHPUnit as it's located in a CDATA section of the buildfile and the fact that the use of several inline tasks will blow up the buildfile, and thereby obfuscate the build flow.

Regrettably Phing doesn't provide an import task like Ant which might enable a refactoring to pull the ad hoc task definitions into a seperate XML file and include them at buildtime; in case you might have some expertise or ideas for a suitable workaround hit me with a comment. So far I tried to get it working, with no success, by utilizing Phing's PhingTask and XML's external entities declaration.

Using Haml & Sass from a Rake task

2009-03-31T14:02:00.061Z

Some time ago I had the 'lightning' idea to implement another Rake automation to support my current blogging workflow, which at the moment consists of finding a sparkling idea to blog about, write it out in WriteRoom and refine the post in TextMate before publishing. As this process was a recurring and copy & paste driven event, I strove for an automation supporting this workflow. So unsurprisingly the post will show my current solution to achieve this goal by utilizing Rake, Haml and Sass.

So what's that Haml and Sass thingy?

Haml (HTML Abstraction Markup Language) is a templating language/engine with the primary goal to make Markup DRY, beautiful and readable again. It has a very shallow learning curve and therefor is perfectly suited for programmers and designers alike. Haml is primarily targeted at making the views of Ruby on Rails, Merb or Sinatra web applications leaner, but as you will see later the Ruby implementation also can be used framework independently.

Sass (Syntactically Awesome StyleSheets) is a module which comes bundled with Haml providing a meta-language/abstraction on top of CSS sharing the same goals and advantages as Haml.

Gluing Haml and Sass into a Rake task

To get going you first have to install Haml and Sass by running the gem command shown next.

sudo gem install haml

With Haml and Sass available it's about time to identify and outline the parts you want to automate, in my case it's the creation of a WriteRoom and/or a XHTML draft document for initial editings. So the parameters to pass into the task to come are the targeted editor(s), the title of the blog post to draft and a list of associated and whitespace separated category tags.

The XHTML document skeleton content and it's inline CSS are defined each in a separate Haml and Sass template file and will be rendered into the outcoming document along with the content passed into the Rake task. While the document skeleton for the WriteRoom draft document, due to it's brevity, is defined inside of the task itself. The following snippets are showing the mentioned Haml and Sass templates for the XHTML draft output file, which are located in the same directory as the Rake file.

Haml

!!! 1.1
%html
  %head 
    %title= "#{title} - Draft"
    %style{ :type => 'text/css' }= inline_css
  %body
    %h3= title
    %h4.custom sub headline 
    %pre.consoleOutput console command
    %pre.codeSnippet code snippet
    %br/
    = "Tags: #{tags.join ', '}"

Sass

body
  :margin 5
  :line-height 1.5em
  :font small Trebuchet MS, Verdana, Arial, Sans-serif
  :color #000000
h4
  :margin-bottom 0.3em
.consoleOutput
  :padding 6px 
  :background-color #000 
  :color rgb(20, 218, 62)
  :font-size 12px
  :font-weight bolder
.codeSnippet
  :padding 3px
  :background-color rgb(243, 243, 243)
  :color rgb(93, 91, 91)
  :font-size small
  :border 1px solid #6A6565

To inject the dynamic content into the Haml template and have it rendered into the outcoming document, the values i.e. draft_title, draft_tags and draft_inline_css have to be made available to the template engine by passing them in a bundling Hash into the to_html alias method of the Haml Engine object like shown in the next Rake task.

task :default do
  Rake::Task['blog_utils:create_draft_doc'].invoke
end

namespace :blog_utils do
  
  desc 'Create a new draft document for a given title, category tags and editor'
  task :create_draft_doc, [:title, :tags, :editor] do |t, args|
    draft_title = args.title
    draft_tags = args.tags.split(' ')
    draft_target_editor = args.editor
    
    raise_message = 'No title for draft provided'
    raise raise_message if draft_title.nil?
    
    raise_message = 'No tags for draft provided'
    raise raise_message if draft_tags.nil?
    
    draft_target_editor = '*' if draft_target_editor.nil?
    
    raise_message = 'Unsupported target editor provided' 
    raise raise_message unless draft_target_editor == 'Textmate' || 
      draft_target_editor == 'Writeroom' || draft_target_editor == '*'
    
    if draft_target_editor == 'Writeroom' || draft_target_editor == '*'
      draft_output_file = draft_title.gsub(' ', '_') + '.txt'
      
      File.open(draft_output_file, 'w') do |draft_file_txt|
        draft_file_txt.puts draft_title
        draft_file_txt.puts
        draft_file_txt.puts "Tags: #{draft_tags.join ', '}"
      end
    end
    
    if draft_target_editor == 'Textmate' || draft_target_editor == '*'
      
      template_sass_content, template_haml_content = ''
      
      ['haml', 'sass'].each do |template_type|
        template = File.dirname(__FILE__) + "/draft_template.#{template_type}"
        raise_message = "#{template_type.capitalize} template '#{template}' not found"
        raise raise_message if !File.exists?(template)
        
        template_sass_content = File.read(template) if template_type === 'sass'
        template_haml_content = File.read(template) if template_type === 'haml'
      end
      
      require 'sass'
      require 'haml'

      draft_inline_css = Sass::Engine.new(template_sass_content).to_css
      draft_document_content = Haml::Engine.new(template_haml_content).to_html(
        Object.new, { :title => draft_title , :tags => draft_tags ,
          :inline_css => draft_inline_css } )
      
      draft_output_file = draft_title.gsub(' ', '_') + '.html'      
      File.open(draft_output_file, 'w') do |draft_file_html|
        draft_file_html.puts(draft_document_content)
      end
    end
    
  end
end

Easing invocation pain with alias

Now as the Rake task is implemented and waiting for demands it can be invoked by calling the task as shown in the next console snippet.

sudo rake -f $HOME/Automations/Rakefile.rb blog_utils:create_draft_doc['Title','Tag1 TagN','Editor']

As I'm not even close to being a console ninja and probably will have forgotten the task call structure before initiating the next blog post, I decided to add an easing and more memorizable alias to $HOME/.profile as shown next.

alias createdraft='sudo rake -f $HOME/Automations/Rakefile.rb blog_utils:create_draft_doc[$title,$tags,$editor]'

The created alias now allows to invoke the Rake task in a nice and easy way as shown in the next console command.

createdraft title='Using Haml & Sass from a Rake task' tags='Rake Ruby' editor='Textmate'

Taking a peek at the generated draft document

After running the described Rake task I end up with the XHTML document shown in the outro code snippet, which then can be used for the further editing process. Of course I could have setup a TextMate Snippet to get me going, but that way I would have missed the opportunity to mess around with another amazing Ruby tool.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
  <head>
    <title>Using Haml & Sass from a Rake task - Draft</title>
    <style type='text/css'>
      body {
        margin: 5;
        line-height: 1.5em;
        font: small Trebuchet MS, Verdana, Arial, Sans-serif;
        color: #000000; }

      h4 {
        margin-bottom: 0.3em; }

      .consoleOutput {
        padding: 6px;
        background-color: #000;
        color: rgb(20, 218, 62);
        font-size: 12px;
        font-weight: bolder; }
      
      .codeSnippet {
        padding: 3px;
        background-color: rgb(243, 243, 243);
        color: rgb(93, 91, 91);
        font-size: small;
        border: 1px solid #6A6565; }
    </style>
  </head>
  <body>
    <h3>Using Haml & Sass from a Rake task</h3>
    <h4>sub headline</h4>
    <pre class='consoleOutput'>console command</pre>
    <pre class='codeSnippet'>code snippet</pre>
    <br />
    Tags: Rake, Ruby
  </body>
</html>

Phplocing your projects with Phing

2009-02-22T13:35:00.007Z

When I started to play around with Ruby on Rails, my attention got somehow soon drawn to it's Rake stats task, which provides developers or more likely project managers with an overview of the actual project size. Exactly one month ago Sebastian Bergmann, of PHPUnit fame, started to implement a similar tool dubbed phploc which can give you an overview of the size for any given PHP project. As I wanted to automate the invocation of this handy tool and collect it's report output out of a Phing buildfile, I invested some time to develop a custom Phing task doing so. Thereby the following post will show you a possible implementation of this task and it's use in a buildfile.

Installing phploc

To setup phploc on your system simply install the phploc PEAR package available from the pear.phpunit.de channel as shown in the next commands. In case you already have installed PHPUnit via PEAR you can omit the channel-discover command.

sudo pear channel-discover pear.phpunit.de
sudo pear install phpunit/phploc

Implementing the phploc task

As I already blogged about developing custom Phing task I'm only going to show the actual implementation and not dive into any details; alternatively you can also grab it from this public GitHub repository.

<?php
require_once 'phing/Task.php';
require_once 'phing/BuildException.php';
require_once 'PHPLOC/Analyser.php';
require_once 'PHPLOC/Util/FilterIterator.php';
require_once 'PHPLOC/TextUI/ResultPrinter.php';

class PHPLocTask extends Task
{
    protected $suffixesToCheck = null;
    protected $acceptedReportTypes = null;
    protected $reportDirectory = null;
    protected $reportType = null;
    protected $fileToCheck = null;
    protected $filesToCheck = null;
    protected $reportFileName = null;
    protected $fileSets = null;
    
    public function init() {
        $this->suffixesToCheck = array('php');
        $this->acceptedReportTypes = array('cli', 'txt', 'xml');
        $this->reportType = 'cli';
        $this->reportFileName = 'phploc-report';
        $this->fileSets = array();
        $this->filesToCheck = array();
    }
    public function setSuffixes($suffixListOrSingleSuffix) {
        if (stripos($suffixListOrSingleSuffix, ',')) {
            $suffixes = explode(',', $suffixListOrSingleSuffix);
            $this->suffixesToCheck = array_map('trim', $suffixes);
        } else {
            array_push($this->suffixesToCheck, trim($suffixListOrSingleSuffix));
        }
    }
    public function setFile(PhingFile $file) {
        $this->fileToCheck = trim($file);
    }
    public function createFileSet() {
        $num = array_push($this->fileSets, new FileSet());
        return $this->fileSets[$num - 1];
    }
    public function setReportType($type) {
        $this->reportType = trim($type);
    }
    public function setReportName($name) {
        $this->reportFileName = trim($name);
    }
    public function setReportDirectory($directory) {
        $this->reportDirectory = trim($directory);
    }
    public function main() {       
        if (!isset($this->fileToCheck) && count($this->fileSets) === 0) {
            $exceptionMessage = "Missing either a nested fileset or the "
                . "attribute 'file' set.";
            throw new BuildException($exceptionMessage);
        }
        if (count($this->suffixesToCheck) === 0) {
            throw new BuildException("No file suffix defined.");
        }
        if (is_null($this->reportType)) {
            throw new BuildException("No report type defined.");
        }
        if (!is_null($this->reportType) && 
            !in_array($this->reportType, $this->acceptedReportTypes)) {
            throw new BuildException("Unaccepted report type defined.");
        }
        if (!is_null($this->fileToCheck) && !file_exists($this->fileToCheck)) {
            throw new BuildException("File to check doesn't exist.");
        }
        if ($this->reportType !== 'cli' && is_null($this->reportDirectory)) {
            throw new BuildException("No report output directory defined.");
        }
        if (count($this->fileSets) > 0 && !is_null($this->fileToCheck)) {
            $exceptionMessage = "Either use a nested fileset or 'file' " 
                . "attribute; not both.";
            throw new BuildException($exceptionMessage);
        }
        if (!is_null($this->reportDirectory) && !is_dir($this->reportDirectory)) {
            $reportOutputDir = new PhingFile($this->reportDirectory);
            $logMessage = "Report output directory does't exist, creating: " 
                . $reportOutputDir->getAbsolutePath() . '.';
            $this->log($logMessage);
            $reportOutputDir->mkdirs();
        }
        if ($this->reportType !== 'cli') {
            $this->reportFileName.= '.' . trim($this->reportType);
        }
        if (count($this->fileSets) > 0) {
            $project = $this->getProject();
            foreach ($this->fileSets as $fileSet) {
                $directoryScanner = $fileSet->getDirectoryScanner($project);
                $files = $directoryScanner->getIncludedFiles();
                $directory = $fileSet->getDir($this->project)->getPath();
                foreach ($files as $file) {
                    if ($this->isFileSuffixSet($file)) {
                        $this->filesToCheck[] = $directory . DIRECTORY_SEPARATOR 
                            . $file;
                    }
                }
            }
            $this->filesToCheck = array_unique($this->filesToCheck);
        }
        if (!is_null($this->fileToCheck)) {
            if (!$this->isFileSuffixSet($file)) {
                $exceptionMessage = "Suffix of file to check is not defined in"
                    . " 'suffixes' attribute.";
                throw new BuildException($exceptionMessage);
            }
        }
        $this->runPhpLocCheck();
    }
    protected function isFileSuffixSet($filename) {
        $pathinfo = pathinfo($filename);
        $fileSuffix = $pathinfo['extension'];
        return in_array($fileSuffix, $this->suffixesToCheck);
    }
    protected function runPhpLocCheck() {
        $files = $this->getFilesToCheck();
        $result = $this->getCountForFiles($files); 
        
        if ($this->reportType === 'cli' || $this->reportType === 'txt') {
            $printer = new PHPLOC_TextUI_ResultPrinter;
            if ($this->reportType === 'txt') {
                ob_start();
                $printer->printResult($result);
                file_put_contents($this->reportDirectory 
                    . DIRECTORY_SEPARATOR . $this->reportFileName, 
                        ob_get_contents());
                ob_end_clean();
                $reportDir = new PhingFile($this->reportDirectory);
                $logMessage = "Writing report to: " 
                    . $reportDir->getAbsolutePath() . DIRECTORY_SEPARATOR 
                        . $this->reportFileName;
                $this->log($logMessage);
            } else {
                $printer->printResult($result);
            }
        } elseif ($this->reportType === 'xml') {
            $xml = $this->getResultAsXml($result);
            $reportDir = new PhingFile($this->reportDirectory);
            $logMessage = "Writing report to: " . $reportDir->getAbsolutePath()
                . DIRECTORY_SEPARATOR . $this->reportFileName;
            $this->log($logMessage);
            file_put_contents($this->reportDirectory . DIRECTORY_SEPARATOR
                . $this->reportFileName, $xml);
        }
    }
    protected function getFilesToCheck() {
        if (count($this->filesToCheck) > 0) {
            $files = array();
            foreach ($this->filesToCheck as $file) {
                $files[] = new SPLFileInfo($file);
            }
        } elseif (!is_null($this->fileToCheck)) {
            $files = array(new SPLFileInfo($this->fileToCheck));
        }
        return $files;
    }
    protected function getCountForFiles($files) {
        $count = array('files' => 0, 'loc' => 0, 'cloc' => 0, 'ncloc' => 0,
            'eloc' => 0, 'interfaces' => 0, 'classes' => 0, 'functions' => 0);
        $directories = array();

        foreach ($files as $file) {
            $directory = $file->getPath();
            if (!isset($directories[$directory])) {
                $directories[$directory] = TRUE;
            }          
            PHPLOC_Analyser::countFile($file->getPathName(), $count);
        }
        
        if (!function_exists('parsekit_compile_file')) {
            unset($count['eloc']);
        }
        $count['directories'] = count($directories) - 1;
        return $count;
    }
    protected function getResultAsXml($result) {        
        $newline = "\n";
        $newlineWithSpaces = sprintf("\n%4s",'');
        $xml = '<?xml version="1.0" encoding="UTF-8"?>';
        $xml.= $newline . '<phploc>'; 
        
        if ($result['directories'] > 0) {
            $xml.= $newlineWithSpaces . '<directories>' . $result['directories'] . '</directories>';
            $xml.= $newlineWithSpaces . '<files>' . $result['files'] . '</files>';
        }
        $xml.= $newlineWithSpaces . '<loc>' . $result['loc'] . '</loc>';
        
        if (isset($result['eloc'])) {
            $xml.= $newlineWithSpaces . '<eloc>' . $result['eloc'] . '</eloc>';
        }
        $xml.= $newlineWithSpaces . '<cloc>' . $result['cloc'] . '</cloc>';
        $xml.= $newlineWithSpaces . '<ncloc>' . $result['ncloc'] . '</ncloc>';
        $xml.= $newlineWithSpaces . '<interfaces>' . $result['interfaces'] . '</interfaces>';
        $xml.= $newlineWithSpaces . '<classes>' . $result['classes'] . '</classes>';
        $xml.= $newlineWithSpaces . '<methods>' . $result['functions'] . '</methods>' . $newline;
        $xml.= '</phploc>';
        return $xml;
    }
}

Hooking the phploc task into Phing

To use the task in your Phing builds simply copy it into the phing/tasks/my directory and make it available via the taskdef task. The next table shows the available task attributes and the values they can take to configure it's behaviour and output. As you will see it also provides the ability to generate reports in a XML format; I chose to implement this feature to have the possibilty to transform the report results into HTML documents by applying for example a XSLT stylesheet. This way they can provide more value to non-technical project members or can be made accessible in a CI system dashboard if desired.

Name	Type	Description	Default	Required
reportType	string	The type of the report. Available types are cli\|txt\|xml.	cli	No
reportName	string	The name of the report type without a file extension.	phploc-report	No
reportDirectory	string	The directory to write the report file to.	false	Yes, when report type txt or xml is defined.
file	string	The name of the file to check.	n/a	Yes, when no nested fileset is defined.
suffixes	string	A comma-separated list of file suffixes to check.	php	No

Supported Nested Tags:

fileset

The closing buildfile extract shows an example phploc task configuration and is also available at the public GitHub repository. Happy phplocing!

<?xml version="1.0"?>
<project name="example" default="phploc" basedir=".">
    <taskdef name="phploc" classname="phing.tasks.my.PHPLocTask" />
    <target name="phploc">
      <tstamp>
        <format property="check.date.time" pattern="%Y%m%d-%H%M%S" locale="en_US"/>
      </tstamp>
      <phploc reportType="txt" reportName="${check.date.time}-report"
              reportDirectory="phploc-reports">
        <fileset dir=".">
          <include name="**/*.php" />
          <include name="*.php" />
        </fileset>
      </phploc>
    </target>
</project>

Broadcasting blog post notifications to Twitter with Ruby and Rake

2009-01-24T05:08:00.032Z

During my latest blogging absence I had some time to tinker around with Ruby. For an introductory challenge I chose to implement a real life feature which currently isn't supported by Blogger.com and screams siren-like for an one-button automation: Broadcasting the latest blog entry to my Twitter account. As I didn't want to sign up for a Twitterfeed account and couldn't resort to the Twitter Tools plugin like WordPress users, I had to perform these broadcasting steps manually, until now. To see how this repetitive and time-stealing process was transformed into a semi-automated one by utilizing Ruby, a splash of Hpricot, Ruby's excellent Twitter Api wrapper and Rake, read on my dear.

Installing the required RubyGems

Prior to diving into the implementation details of the given scenario I had to install the required RubyGems like shown in the next console snippet. The installation of the twitter gem might take a while due to it's dependency on several other gems.

sudo gem install hpricot rake twitter

Scraping the latest blog post details with Hpricot

The initial implementation step was to gather relevant metadata (Url, title and used tags) of the latest blog post. I first took the route to get it by grabbing the blog's RSS feed and extracting the metadata from there, but soon stumbled into problems getting an outdated feed from Feedburner. The next alternative was to scrape the needed metadata directly from the blog landing page. As I went this route before with the Zend_Dom_Query component of the Zend Framework I decided to use something similar from the Ruby toolbox. Some Google hops later I was sold to Hpricot, a HTML Parser for Ruby and as you can see in the first code snippet, showing an extract of the Rake file to come, this is done in just 13 lines of code.

doc = Hpricot(open(blog_landing_page, scrape_options))
latest_post_url = doc.at('h3.post-title > a')['href']
latest_post_title = doc.at('h3.post-title > a').inner_html
label_doc = Hpricot(doc.search('span.post-labels').first.to_s)
label_links = label_doc.search('span.post-labels > a').each do |label_link|
  label = label_link.inner_html.gsub(' ', '').downcase
  if label.include?('/')
    labels = label.split('/')
    labels.each { |label| last_post_labels.push(label) }
  else
    last_post_labels.push(label)
  end
end

Outstanding tasks

With the metadata available the oustanding tasks to implement were:

to get a short Url for the actual blog post by utilzing a public API of an Url shortening service i.e. is.gd
to build the tweet to broadcast by injecting the available metadata into a tweet template
to broadcast the notification tweet to the given Twitter account
to log the broadcasted blog title to prevent spamming or duplication scenarios

As a guy sold to build tools and eager to learn something new I subverted Rake, Ruby's number one build language, to glue the above mentioned tasks and their implementation together, to manage their sequential dependencies and to have a comfortable invocation interface. The nice thing about Rake is that it allows you to implement each tasks unit of work by using the Ruby language; and there is no need to follow a given structure to implement custom tasks like it's the case for custom Phing tasks. As you will see in the forthcoming complete Rakefile some of the tasks are getting quite long and complex; therefor some of them are pending candidates for Refactoring activities like for example extract task units of work into helper/worker classes.

  require 'rubygems'
  require 'hpricot'
  require 'open-uri'
  require 'twitter'

  task :default do
    Rake::Task['blog_utils:broadcast_notification'].invoke
  end

  namespace :blog_utils do

    scrape_options = { 'UserAgent' => "Ruby/#{RUBY_VERSION}" }
    blog_landing_page = 'http://raphaelstolt.blogspot.com'
    latest_post_short_url, latest_post_url, latest_post_title = nil
    notification_tweet = nil
    last_post_labels = []
    broadcast_log_file = File.dirname(__FILE__) + '/broadcasted_posts.log'
    twitter_credentials = { :user => 'raphaelstolt', :pwd => 'thatsasecret'}

    desc 'Scrape metadata of latest blog post from landing page'
    task :scrape_actual_post_metadata do
      doc = Hpricot(open(blog_landing_page, scrape_options))
      latest_post_url = doc.at('h3.post-title > a')['href']
      latest_post_title = doc.at('h3.post-title > a').inner_html
      label_doc = Hpricot(doc.search('span.post-labels').first.to_s)
      label_links = label_doc.search('span.post-labels > a').each do |label_link|
        label = label_link.inner_html.gsub(' ', '').downcase
        if label.include?('/')
          labels = label.split('/')
          labels.each { |label| last_post_labels.push(label) }
        else
          last_post_labels.push(label)
        end
      end
    end

    desc 'Shorten the Url of the latest blog post'
    task :shorten_post_url => [:scrape_actual_post_metadata] do
      raise_message = 'No Url for latest blog post available'
      raise raise_message if latest_post_url.nil?
      url_shorten_service_call = "http://is.gd/api.php?longurl=#{latest_post_url}"
      latest_post_short_url = open(url_shorten_service_call, scrape_options).read
    end

    desc 'Check if generate shorten Url references the latest blog post url'
    task :check_shorten_url_references_latest do
      url_referenced_by_short_url = nil
      open(latest_post_short_url, scrape_options) do |f|
        url_referenced_by_short_url = f.base_uri.to_s
      end 
      raise_message = "Generated short Url '#{latest_post_short_url}' does not"
      raise_message << " reference actual blog post url '#{latest_post_url}'"
      raise raise_message unless url_referenced_by_short_url.eql?(latest_post_url)
    end

    desc 'Check if latest blog post has already been broadcasted'
    task :check_logged_broadcasts do
      logged_broadcasts = []
      if  File.exist?(broadcast_log_file)
        File.open(broadcast_log_file, 'r') do |f|
          logged_broadcasts = f.readlines.collect { |line| line.chomp }
        end
      end
      raise_message = "Blog post '#{latest_post_title}' has already been "
      raise_message << "broadcasted"
      raise raise_message if logged_broadcasts.include?(latest_post_title)
    end

    desc 'Build notification tweet by injecting scraped metadata into template'
    task :build_notification_tweet => [:shorten_post_url, 
      :check_shorten_url_references_latest] do
      raise_message = 'Required metadata to build tweet is not available'
      raise raise_message if latest_post_title.nil? || latest_post_short_url.nil? 
      raise raise_message if last_post_labels.nil?

      notification_tweet = "Published a new blog post '#{latest_post_title}' "
      notification_tweet << "available at #{latest_post_short_url}."

      raise_message = 'Broadcast for latest blog post exceeds 140 characters'
      raise raise_message if notification_tweet.length > 140

      last_post_labels.each do |tag|
        notification_tweet << " ##{tag}" unless notification_tweet.length + 
          " ##{tag}".length > 140
      end
    end

    desc 'Broadcast latest blog post notification to twitter'
    task :broadcast_notification_to_twitter => [:build_notification_tweet, 
      :check_logged_broadcasts] do
      raise_message = "Notification tweet to broadcast is not available"
      raise raise_message if notification_tweet.nil?
      puts "Broadcasting '#{notification_tweet}'"
      http_auth = Twitter::HTTPAuth.new(twitter_credentials[:user], twitter_credentials[:pwd])
      Twitter::Base.new(http_auth).update(notification_tweet)
      #Twitter::Base.new(twitter_credentials[:user], twitter_credentials[:pwd]).post(notification_tweet)
      Rake::Task['blog_utils:log_broadcast_title'].invoke
    end

    desc 'Log broadcasted blog post title'
    task :log_broadcast_title do
      puts "Logging latest post title to #{broadcast_log_file}"
      File.open(broadcast_log_file, 'a') do |f|
        f.puts latest_post_title
      end
    end

  end

Putting the Rake task(s) to work

The next step was to put the Rakefile into my $HOME directory; and after publishing a new blog post I'm now able to broadcast an automated notification by firing up the console and calling the Rake task like shown next.

sudo rake -f $HOME/Automations/Rakefile.rb blog_utils:broadcast_notification

And as I'm too lazy to type this lengthy command everytime I further added an alias to the $HOME/.profile file which allows me to call the task via the associated alias i.e. blogger2twitter shown in the .profile excerpt.

alias blogger2twitter='sudo rake -f $HOME/Automations/Rakefile.rb blog_utils:broadcast_notification'

After running the Rake task against this blog post the notification gets added to the given Twitter timeline like shown in the outro image.

Installing Zend_Tool on Mac OS X

2009-01-23T13:19:00.032Z

Yesterday I decided to tiptoe into the development of custom Zend_Tool Providers as the introductional article series by Ralph Schindler motivated me to learn more about it and I already have some useful use cases on my mind. Therefor I prior had to install the Zend_Tool component and it's driving CLI scripts on my MacBook. The following brief instruction describes a possible approach that got me running in no time on a Mac OS X system. Once the Zend Framework has an official PEAR channel most of the forthcoming steps should be obsolete and entirely performed by the PEAR package installer command.

Fetching and installing the Zend_Tool component

First I tried to install the 1.8.0(devel) version of the Zend Framework via the pear.zfcampus.org PEAR channel but it currently only delivers the 1.7.3PL1(stable) package; even after switching the stability state of the PEAR config. To dodge the include_path setting hassle and for a further use when customizing other tools like Phing tasks I decided to keep the installed package.

sudo pear channel-discover pear.zfcampus.org
sudo pear install zfcampus/zf-devel

The next commands are showing the footwork I had to do to get the Zend_Tool component into the PEAR Zend Framework package installed in /opt/local/lib/php/Zend.

sudo svn co http://framework.zend.com/svn/framework/standard/incubator/library/Zend/Tool/ $HOME/Cos/Zend/Tool
sudo rsync -r --exclude=.svn $HOME/Cos/Zend/Tool /opt/local/lib/php/Zend

Putting the Zend_Tool CLI scripts to work

The next steps were to fetch the CLI scripts from the public Subversion repository and to link them into the system path /opt/local/bin as shown in the next commands.

sudo svn co http://framework.zend.com/svn/framework/standard/incubator/bin $HOME/Cos/Zend/bin
sudo ln $HOME/Cos/Zend/bin/zf.sh /opt/local/bin/zf
sudo ln $HOME/Cos/Zend/bin/zf.php /opt/local/bin/zf.php

Checking the installation

With everything hopefully in place it was time to verify the success of the installation via the below stated provider action call; and as I got the version of the installed Zend Framework as a response of the executed action/command I'm good to go.

zf show version

Rails for PHP Developers book review

2008-11-13T15:21:00.007Z

The e-book version of the Pragmatic Programmers release Rails for PHP Developers written by Derek DeVries and Mike Naberezny occupies now some of my scarce hard drive space for several months, and today I managed to hit the last page of it. In case you're interested in knowing if it's worthy to sacrifice some rare hard drive or bookshelf space for this book read on.

What's in it?

The book consists of three main parts which are addressing open-minded developers with a PHP background tempted to add the Ruby language and the thereupon built Rails 2.0 framework to their toolset.

The first part introduces the classic and nowadays omnipresent MVC pattern, the concepts and conventions of Rails by converting a simple PHP newsletter application into a Rails based one. The follow-up chapters of the first part are covering the basics of the Ruby language by looking at known PHP language features and constructs, and how they translate to their Ruby counterparts. Reading these chapters you will get a thorough understanding of the Ruby language and be able to apply unique features like blocks or the reopening of existing classes. The communicated knowledge builds the foundation to accelerate the use and understanding of the Rails framework which is covered in-depth through-out the book's second part.

While teaming up with their imaginary buddy Joe the authors walk you through building a Rails user group application. The chapters of the second part are covering a lot of ground reaching from domain modeling, putting the particular MVC parts to work, ensuring quality by utilizing the Test::Unit library to finally deploying the application into a ~~productive~~ production environment.

The first two chapters of the final and reference part cover the differences and similarities between PHP and Ruby data structures, operations and language constructs. The final chapter of the book closes with a web development specific comparision of PHP constructs and approaches to the ones used by the Rails framework. The book is accompanied by a dedicated blog and a PHP to Rails online reference to satisfy severe thirst for more knowledge.

Conclusion

The book provides interested PHP developers a thorough introduction to the Ruby language and the Rails framework in a fluent and enjoyable writing tone. By implementing the example application of the second book part any decent PHP developer will derive a solid understanding of the Rails framework, he can build upon and that puts him in the position to make reasonable judgments for using/flaming it or not. IMHO this book is so far one of the best PHP related book releases of the out fading year 2008, and can be a real motivator to extend the just gained knowledge by diving deeper into the Ruby/Rails ocean.

So be prepared to see one or another Ruby related post popping up in the future timeline of this blog; I just added another costly addiction to the medicine cupboard. Word!

Tinyizing URLs with Zend_Http_Client

2008-10-31T21:44:00.002Z

While doing some initial research for a blog related automation task to implement I learned some more about services which transform long URLs into short ones. The well-knownst of these services, due to the Twitter hype, is probably TinyURL which can be accessed via a classic webinterface or by calling a public API. In a recent blog post Dave Marshall outlined a quick workaround for tweeting via the Zend_Http_Client component which is a reasonable approach for calling services that aren't in the Zend Framework core yet like Zend_Service_Twitter or are not supported out of the box. Therefore this post will try to describe a Zend Framework way of creating tinyized URLs.

Getting tiny tiny y'all

According to Wikipedia there are numerous services available e.g. RubyUrl providing the same feature as TinyURL, so to be prepared for the future and thereby maybe violating the YAGNI principle I decided to declare a very basic interface first in case of switching the service provider someday.

<?php
/** 
 * 'Interface-level' PHPDoc Block   
 */
interface Recordshelf_Service_UrlShortener_Interface
{
    public function __construct($serviceEndpoint = '');
    public function shortenize($url);
}

The next code snippet shows the implementation for the TinyURL service programmed against the interface and hosting an additional alias method called tinyize which is simply wrapping the actual worker method. The service utilizes Zend_Http_Client by setting the endpoint of the service, transmitting a GET request parameterized with the URL to shorten against it and returning the response containing the tinyized URL.

<?php
require_once('Zend/Http/Client.php');
require_once('Recordshelf/Service/UrlShortener/Interface.php');
/** 
 * 'Class-level' PHPDoc Block   
 */
class Recordshelf_Service_TinyUrl implements
    Recordshelf_Service_UrlShortener_Interface
{
    /**
     * The service endpoint
     *
     * @var string
     */
    private $_serviceEndpoint = null;
    /**
     * Recordshelf service tinyURL constructor
     *
     * @param string $serviceEndpoint
     */
    public function __construct(
        $serviceEndpoint = 'http://tinyurl.com/api-create.php')
    {
        $this->_serviceEndpoint = $serviceEndpoint;
    }
    /**
     * Shortenizes a given Url
     *
     * @param string $url
     * @return string
     * @throws Exception
     */
    public function shortenize($url) {
        if (is_null($this->_serviceEndpoint)) {
            throw new Exception('No service endpoint set');
        }
        $client = new Zend_Http_Client($this->_serviceEndpoint);
        $client->setParameterGet('url', $url)
               ->setMethod(Zend_Http_Client::GET);
        try {
            $response = $client->request();
        } catch (Exception $e) {
            throw $e;
        }

        if (200 === $response->getStatus()) {
            return $response->getBody();
        } else {
            throw new Exception($response->getStatus() . ": " .
                $response->getMessage());
        }
    }
    /**
     * Alias method for the shortenize method
     *
     * @param string $url
     * @throws Exception
     * @see shortenize
     */
    public function tinyize($url)
    {
        return $this->shortenize($url);
    }
}

Now with everything hopefully operating smoothly it's time for a test-drive, yeah I'm lazy and cut that development approach called TDD, by creating a service instance and requesting a TinyURL for the Zend Framework website as shown in the outro listing.

<?php
$service = new Recordshelf_Service_TinyUrl();
$service->tinyize('http://framework.zend.com');
// => http://tinyurl.com/nf8kf

In case off considering or favouring a more framework independent approach there are also other blends available like one via file_get_contents or via curl. Happy tinyizing!

Getting a visualization of a Phing buildfile

2008-10-26T19:28:00.004Z

Today I spent some time to get a tool running to visualize Phing buildfiles as this can come in handy for maintaing, refactoring or extending large buildfiles. Out of the box the Phing -l option can be used to get a first overview of all available targets in a given buildfile but it doesn't untangle the target dependencies and sometimes a picture is still worth a thousand words. Luckily the Ant community already provides several tools to accomplish the visualization of Ant buildfiles, reaching from solutions that apply a Xslt stylesheet upon a given buildfile e.g. ant2dot to those ones that take a programmatically approach e.g. Grand. All these solutions utilize Graphiz to generate a graphic from a DOT file representing the buildfile structure, it's targets and their dependencies. As Phing is a very close descendant of Ant the Xslt approach was best suited and the one with the least effort because their buildfile markup is very similar. The following post will walk you through on how to get a simple Phing buildfile visualization tool running in just a few minutes.

Grabbing the Xslt file

The first step is to get the ant2dot Xslt stylesheet and put it into the same directory as the visualization buildfile and target to come. Due to the aforementioned Phing and Ant buildfile markup similarities it can be used without any modfications.

Setting up the buildfile visualization target

The next step is to create a Phing target that utilizes the Xslt task to transfrom the fed buildfile into a DOT file which gets passed further to a platform dependent Exec task handling the final transformation into a PNG image. To make the visualization target independent from the buildfile to visualize it's hosted in an own buildfile and the target accepts the buildfile to be transformed as a property passed to the Phing Cli or if none given uses the default build.xml. Further the Xslt stylesheet accepts several parameters to add extended data to the resulting DOT file/PNG image which can be set in the <param> tags of the Xslt task. For a list of possible parameters have a look at the options section of ant2dot. The following codesnippet shows the visualization buildfile and the visualize target doing the Whodini like magic.

<?xml version="1.0"?>

<project name="buildfile-visualizer" default="visualize" basedir=".">    

  <target name="visualize" 
          description="Generates a visualization(PNG image) of a given buildfile">
    <property name="buildfile" value="build.xml" />
    <property name="phing2dot.xsl" value="${project.basedir}/ant2dot.xsl" />
    <property name="dot.file" value="${buildfile}.dot" />
    <property name="png.file" value="${buildfile}.png" />
    <property name="dot.command.win" value="dot.exe -Tpng ${dot.file} -o ${png.file}" />
    <property name="dot.command.mac" value="dot -Tpng ${dot.file} -o ${png.file}" />
    <!-- Transform buildfile into DOT file -->
    <xslt file="${buildfile}" tofile="${project.basedir}/${dot.file}" 
          style="${phing2dot.xsl}" overwrite="true"> 
      <param name="graph.label" expression="${buildfile}" />
      <param name="use.target.description" expression="true" />
    </xslt>
    <!-- Generate image from DOT file -->
    <exec command="${dot.command.win}" 
          dir="${project.basedir}" os="WINNT" />
    <exec command="${dot.command.mac}" 
          dir="${project.basedir}" os="Darwin" />
    
    <delete file="${project.basedir}/${dot.file}" />
  </target>
    
</project>

Running the buildfile visualization target

Now as mostly all necessary pieces are available it's time to check if the DOT command is available on the targeted platform by running a dot(.exe) -V on the console. If it isn't available it has to be installed, this might take several minutes depending on the given platform. Finally with everything in place the visualization process/target can be kicked off by calling Phing the
following way.

triton:tmp stolt$ phing -f buildfile-visualizer.xml [-Dbuildfile=<targeted-buildfile.xml>]

The last picture shows the visualization of the simple buildfile described in the Phing Userguide but it's also possible to get a meaningful visualization of larger buildfiles like the one I currently use for setting up Zend Framework based projects.

Scraping websites with Zend_Dom_Query

2008-10-16T18:49:00.007Z

Today I stumbled upon an interesting and reportable scenario where I had to extract information of the weekly published Drum and Bass charts provided by BBC 1Xtra. As this information currently isn't available in any consumer friendly format like for example a RSS feed, I had to go that scraping route but didn't want to hustle with a regex approach. Since version 1.6.0 the Zend_Dom_Query component has been added to the framework mainly to support functional testing of MVC applications, but it also can be used for rolling custom website scrapers in a snap. Woot, perfect match!

The following code snippets are showing the Bbc_DnbCharts_Scraper class I came up with and an example of its usage. The class utilizes curl to read the website holding the desired data, which will be passed to Zend_Dom_Query to execute queries upon it. For querying the former loaded XHTML Document Object Model it's possible to either utilize XPath or CSS selectors. So I had to pick my poison, and decided to go with the CSS selectors as them were best suited for the document to query and will be more familiar to most jQuery or Prototype users. The query returns a result set of all matching DOMElements which are further unpuzzled via a private helper method returning just the desired charts data as shown in the closing listing. As you can see the implementation of the scraping can be done with a minimum of effort and these are exactly the moments I love the Zend Framework for.

<?php
require_once('Zend/Dom/Query.php');
/** 
 * 'Class-level' PHPDoc Block   
 */
class Bbc_DnbCharts_Scraper
{
    private $_url = null;
    private $_xhtml = null;

    /**
     * @param string $url
     */
    public function __construct($url)
    {
        $this->_url = $url;
    }
    /**
     * Scrapes off the drum and bass charts content from the BBC 1Xtra website.     
     *
     * @return array
     * @throws Exception
     */
    public function scrape()
    {
        try {
            $dom = new Zend_Dom_Query($this->_getXhtml());
        } catch (Exception $e) {
            throw $e;        
        }
        $results = $dom->query('div.chart div');
        $chartDetails = array();
        foreach ($results as $index => $result) {
            /* @var $result DOMElement */
            if ($result->nodeValue !== '') { //filter out <br /> element
                $chartDetails[] = $result->nodeValue;
            }
        }
        return $this->_unpuzzleChartDetails($chartDetails, true);
    }
    /**
     * Unpuzzles the chart details and groups them by their chart position, 
     * if desired with associative keys.
     *  
     * @param array $details
     * @param boolean $associative
     * @return array
     */
    private function _unpuzzleChartDetails(array $details, $associative = false)
    {
        if (0 === count($details)) {
            return array();
        } else {  
            $nextChartRank = 2;
            $charts = array();
            $groupedChartDetails = array();
            
            foreach ($details as $index => $chartDetail)
            { 
                if ($index <= $nextChartRank) {
                    $groupedChartDetails[] = $chartDetail;
                }
                if ($index == $nextChartRank) {
                    $nextChartRank+=3;
                    $charts[] = $groupedChartDetails;
                    unset($groupedChartDetails);
                }
            }
            if ($associative) {
                $associatives = array('artist', 'tune', 'label');
                foreach ($charts as $chartsIndex => $chart) {
                    unset($charts[$chartsIndex]);
                    foreach ($chart as $chartIndex => $chartDetails) {
                        $charts[$chartsIndex][$associatives[$chartIndex]] = 
                            $chartDetails;
                    }
                }
            }
            return $charts;
        }
    }
    /**
     * Gets the XHTML document via curl 
     * 
     * @return string
     * @throws Exception
     */
    private function _getXhtml()
    {
        $curl = curl_init();
        if (!$curl) {
            throw new Exception('Unable to init curl. ' . curl_error($curl));
        }
        curl_setopt($curl, CURLOPT_URL, $this->_url);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
        // Faking user agent
        curl_setopt($curl, CURLOPT_USERAGENT, 
            'Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)');
        $xhtml = curl_exec($curl);
        if (!$xhtml) {
            throw new Exception('Unable to read XHTML. ' . curl_error($curl));
        }
        curl_close($curl);
        return $xhtml; 
    }
}

// Usage demo
$scraper = new Bbc_DnbCharts_Scraper('http://www.bbc.co.uk/1xtra/drumbass/chart/');
$charts = $scraper->scrape();

The closing code snippet shows an extract of the Drum and Bass charts from BBC 1Xtra scraped off around the 16th October 2008.

Array
(
    [0] => Array
        (
            [artist] => Chase & Status Ft Plan B
            [tune] => Pieces
            [label] => Ram Records
        )

    ...
    
    [9] => Array
        (
            [artist] => Zen
            [tune] => Full Effect
            [label] => Flipmode Audio
        )

)

Creating custom PHPUnit assertions

2008-07-28T17:38:00.006+01:00

While developing PHP applications and applying developer testing the applications safety net will grow along the timeline, and as normal code, test code should be in a fresh, odour free state too. A common test code smell, amongst others, is the duplication of assertion logic which can reduce reusability, readability and thereby obscure the specific verification intention of tests. To subdue this special smell several patterns and refactorings are available to acquaint the test code with the DRY principle. So in this blog post I'd like to set the focus on some of the aspects of the Custom Assertion pattern, by showing how to create custom PHPUnit assertions, which attacks the above mentioned smell and its retroactive effects with a huge antiperspirant flagon, while also providing the chance to build a customer friendly and domain related test vocabulary.

The first introductive code snippet shows an example of unwanted code duplications and smells in a PHPUnit(i.e. version: 3.2.21) test case class spreading over several test methods. The first test code duplications smell is present when verifying that a given bag is having an expected item count and an explicit 'intent obscuration' smell can be spotted when verifying the bags stock id against an assumed convention via a 'distracting' regular expression.

<?php
require_once 'PHPUnit/Framework.php';
require_once 'Record/Bag.php';
require_once 'Record/Item.php';

class Record_Bag_Test extends PHPUnit_Framework_TestCase 
{
    private $_bag = null;
    
    protected function setUp() 
    {
        /**
         * Creates a new named bag with an unique stock id
         * in a format of AAA-NN-AA-NNNNNNNN e.g. XDS-76-YS-00000124, 
         * where A stands for an alphanumeric and N for a numeric character.
         */
        $this->_bag = new Record_Bag('Test_Bag');
    }
    
    /**
     * @test
     */
    public function bagShouldNotContainDuplicateItems() 
    {
        $this->assertTrue(0 === $this->_bag->getItemQuantity(), 
            'New bag not empty on creation.');
            
        $this->_bag->addItem(new Record_Item('Dubplate 1'));
        $this->_bag->addItem(new Record_Item('Dubplate 2'));
        $this->_bag->addItem(new Record_Item('Dubplate 2'));
        
        $this->assertTrue(2 === $this->_bag->getItemQuantity(), 
            'Bag does contain duplicated items.');
    }
    
    /**
     * @test
     */
    public function bagShouldBeReducedByOneItemAfterRemoval()
    {
        $this->assertTrue(0 === $this->_bag->getItemQuantity(), 
            'New bag not empty on creation.');

        $this->_bag->addItem(new Record_Item('Dubplate 1'));
        $this->_bag->addItem(new Record_Item('Dubplate 2'));
        $this->_bag->addItem(new Record_Item('Dubplate 3'));

        $this->_bag->removeItem('Dubplate 2');

        $this->assertTrue(2 === $this->_bag->getItemQuantity(), 
            'Former three items bag does not contain two items after removal of one.');  
    }
    
    /**
     * @test 
     */
    public function bagStockIdShouldFollowAgreedConvention()     
    {    
        $stockIdPattern = '/^[A-Z]{3}-\d{2}-[A-Z]{2}-\d{8}/U';
        $this->assertRegExp($stockIdPattern, $this->_bag->getStockId(), 
            'Stock id <string:' . $this->_bag->getStockId() 
                . '> does not follow the agreed convention.'); 
    }
    
    ....
    
    protected function tearDown() 
    {
        unset($this->_bag);
    }
}

Mechanics of rolling custom assertions

The 'Custom Assertion' pattern can be applied from the very first test code creation activities, in sense of a prefactoring, or refactored towards by extracting the assert duplications and verification intention obscurations into tailormade and intent revealing named assertions.

To define custom assertions are several approaches available, the first and easiest one is to define custom assertions merely for a single test class and make them private (inline) methods of this specific class by facading/wrapping the standard PHPUnit assertion. This approach is outlined in code snippet a).

Another approach is to create/introduce an Assert Class to promote a cleaner reusability in other test case classes or scenarios, this approach might get chosen to collect and organize the evolving domain specific assertions. You will see a code sketch of this approach in code listing b).

Other and more complex approaches would be the utilisation of PHPUnits' Constraint feature which is available since release 3.0.0 or in the near future the use of the Hamcrest test matcher features which might be available from PHPUnit 4.0.0.

Either way the purpose specific assertions should further provide a default and convention conform assertion message, which will be raised on a verification failure, and also the feature to feed in a custom one to avoid gambling annoying Assertion Roulette rounds.

a) Assert definition inside Test Case:

<?php
require_once 'PHPUnit/Framework.php';
require_once 'Record/Bag.php';
require_once 'Record/Item.php';

class Record_Bag_Test extends PHPUnit_Framework_TestCase 
{
    private $_bag = null;
    
    protected function setUp() 
    {
        $this->_bag = new Record_Bag('Test_Bag');
    }
    
    ....
    
    private function assertBagItemCount($expectedCount, $bag, 
        $message = 'Expected bag item count <integer:#1> does not match actual count of <integer:#2> items.')
    {
        if (strpos($message, '#1')) {
            $message = str_replace('#1', $expectedCount, $message);        
        }
        if (strpos($message, '#2')) {
            $message = str_replace('#2', $bag->getItemQuantity(), $message);        
        }
        $this->assertTrue($expectedCount === $bag->getItemQuantity(), $message);
    }    
}

b) Assert definition in Assert Class:

<?php
require_once 'PHPUnit/Framework/Assert.php';

class Record_Bag_Assert extends PHPUnit_Framework_Assert 
{
    /**
     * Verifies that a given bag stock id follows the agreed convention.
     *
     * @param string $stockId
     * @param string $message
     * @see Record_Bag::createUniqueStockId()
     */
    public function assertStockIdFollowsConvention($stockId, 
        $message = 'Stock id <string:##> does not follow the agreed convention.') 
    {
        if (strpos($message, '##')) {
            $message = str_replace('##', $stockId, $message);        
        }
        $stockIdPattern = '/^[A-Z]{3}-\d{2}-[A-Z]{2}-\d{8}/U';
        $this->assertRegExp($stockIdPattern, $stockId, $message);        
    }
    
    ....
    
}

Putting the custom assertions to work

Now as the tailormade assertions are available all verification work can be delegated to them the same way it would be done with any of the standard PHPUnit assertions. In case the custom assertions are hosted in an 'Assert Class' they can be required_once or loaded via __autoload() in the test setup, otherwise if they are defined inside the test case class itself they can be used like regular private methods of that class. The last code extract illustrates the use of the prior outlined 'Assert Class' assertion for verifing the stock id format alongside the use of the 'inline' custom assertion for verifying the amount of items in a given bag.

<?php
require_once 'PHPUnit/Framework.php';
require_once 'Record/Bag/Assert.php';

class Record_Bag_Test extends PHPUnit_Framework_TestCase 
{
    
    ....
    
    /**
     * @test
     */
    public function bagShouldNotContainDuplicateItems() 
    {
        $this->assertBagItemCount(0, $bag,  'New bag not empty on creation.');
            
        $this->_bag->addItem(new Record_Item('Dubplate 1'));
        $this->_bag->addItem(new Record_Item('Dubplate 2'));
        $this->_bag->addItem(new Record_Item('Dubplate 2'));
        
        $this->assertBagItemCount(2, $bag, 'Bag does contain duplicate items.');
    }
    
    /**
     * @test
     */
    public function bagShouldBeReducedByOneItemAfterRemoval()
    {
        $this->assertBagItemCount(0, $bag, 'New bag not empty on creation.');

        $this->_bag->addItem(new Record_Item('Dubplate 1'));
        $this->_bag->addItem(new Record_Item('Dubplate 2'));
        $this->_bag->addItem(new Record_Item('Dubplate 3'));

        $this->_bag->removeItem('Dubplate 2');

        $this->assertBagItemCount(2, $bag, 
            'Former three items bag does not contain two items after removal of one.');   
    }
    
    /**
     * @test 
     */
    public function bagStockIdShouldFollowAgreedConvention()     
    {    
        Record_Bag_Assert::assertStockIdFollowsConvention(
            $this->_bag->getStockId());
    }
    
    ....
    
}

Adding value through a domain specific test vocabulary

As you might have noticed the readability and intention communication of the test code has been improved significantly from the introductive code snippet towards the last one. Furthermore by distilling a ubiquitous(see Domain Driven Design book by Eric Evans) test language domain experts, which are mostly not fluent in the targeted programming language i.e. PHP, are enabled to read test code and provide valuable feedback or contribute changes to test scenarios affecting their domain.

Another common area where domain specific test vocabularies are used, by providing their own assertion and constraint sets, test case classes and additional test helpers, are extensions to xUnit frameworks e.g. DBUnit for PHPUnit or the Zend Framework MVC testing scaffold.

Six valuable Phing build file refactorings

2008-07-04T00:16:00.008+01:00

Some ~~weeks~~ months ago I finally got my hands on the ThoughtWorks Anthology and got immediately hooked on one of the featured essays called 'Refactoring Ant Build Files' contributed by Julian Simpson aka the build doctor. After absorbing and studying the provided catalogue of overall 24 refactorings, I spent some time to transform a few health-promoting ones to the Phing universe. So the following post will outline six ~~five~~ basic, but valuable Phing build file refactorings by showing the smelly example first, followed by the scentless one and a closing refactoring description.

Making build files 'first-class' codebase citizens

You might ask yourself if there even is any need to refactor and care about mostly poorly treated project artifacts like build files. Well according to the book market there are growing needs and catalogues for refactoring non-sourcecode matters like databases and nowadays even (X)HTML, and as build tools are often used to automate the whole build and delivery process of complete projects, their feed build files should be readable and clear, painless maintainable and easily customizable as the controlled project takes new directions and hurdles.

Today build files are also often used to drive the Continuous Integration(CI) process and are heavily used to run local development builds prior to commiting the finished development tasks, therefor messy and clotty build files will have a counterproductive impact on the build management lifecycle and on making required changes to it. So when striving for codebase citizen equality agree upon a build file coding standard (e.g. 5. Introduce distinct target naming or a common element indentation), reside all build files of a project in a SCM system like Subversion or Git and try not to neglect the build files constantly just because they aren't actual business logic.

Trapeze balancing without a safety net

While developing an applications business logic 'ideally' automated behaviour verifying tests are written, whether in a test-first or test-last approach, and these are building the implicit and required safety net for all follow-up refactorings. For build files there are currently no tailored testing tools/frameworks available to warrant their external behaviour during and after a refactoring, though it might be possible to create a basic safety net by using for example a combination of PHPUnit's assertFileExists and assertContains assertions. And even if there were such tools available, it's rather questionable that these would be applied to test-drive mostly simple starting and incremental evolving build files. So currently this flavour of refactoring needs to be applied with much more descipline and caution than classic sourcecode refactorings, even 'old-school' manual tests have to be run frequently and only with a proceeding practice more and more agressive refactorings will become an everyday tool. After this short note of caution, let us jump right into the refactoring catalogue extract.

1. Extract target

Take parts of a large target, declare them as independent targets and preserve dependencies by using the
target depends attribute.

Before

<target name="what-a-clew">
  
  <phplint>
    <fileset dir="${build.src}">
      <include name="**/*.php"/>
    </fileset>
  </phplint>
  
  <phpcodesniffer standard="PEAR" format="summary">
    <fileset dir="${build.src}">
      <include name="**/*.php"/>
    </fileset>
  </phpcodesniffer>
  
  <phpunit>
    <formatter todir="reports" type="xml"/>
    <batchtest>
      <fileset dir="="${build.tests}">
        <include name="**/*Test*.php"/>
      </fileset>
    </batchtest>
  </phpunit>

</target>

After:

<target name="phplint-report">
  <phplint>
    ....
  </phplint>
</target>

<target name="sniff-report" depends="phplint-report">
  <phpcodesniffer standard="PEAR" format="summary">
    ....
  </phpcodesniffer>
</target>

<target name="test-report" depends="sniff-report">
  <phpunit>
    ....
  </phpunit>
</target>

The Extract target refactoring is similar to the well-known Extract method refactoring catalogued by Martin Fowler and should be applied to unclutter long targets, which can become hard to understand and troubleshoot while maintaining or extending a build file. This refactoring is achieved by taken each atomic task (e.g. phplint) of the cluttered target and provide them each a own target (e.g. phplint-report) while the former tasks execution sequence can be obtained by utilizing the target depends attribute. You can compare this refactoring to the technique of tackling a method that's to large and infringes upon the single responsibility principle.

While twiddling with this refactoring I came up with a follow-up and hand in hand refactoring that might go by the name of Introduce facade target, which simply orchestrates the target execution sequence so you can remove the depends attribute of all orchestrated targets and thereby use them separately if needed and advisable. The following build file extract shows the result of this refactoring in action.

1.1 Introduce facade target

Provide a facade target to obtain the task execution sequence and to make each involved target a single callable unit.

After:

<target name="phplint-report">
  <phplint>
    ....
  </phplint>
</target>

<target name="sniff-report" depends="phplint-report">
  <phpcodesniffer standard="PEAR" format="summary">
    ....
  </phpcodesniffer>
</target>

<target name="test-report" depends="sniff-report">
  <phpunit>
    ....
  </phpunit>
</target>

<target name="quality-report" depends="lint-report, sniff-report, test-report" 
        description="Generates the overall projects quality report" />

2. Introduce property file

Move infrequently changing properties from the build file body to a flat file.

Before:

<property name="db.port" value="3306" />
<property name="db.name" value="example" />
<property name="db.user" value="funkdoc" />
....
<property name="runtime.property.x" value="default" />
....

After:


build.poperties file
[example properties]
db.port = 3306
db.name = example
db.user = funkdoc
....

build file
<property file="build.properties" />
<property name="runtime.property.x" value="default" />
....

The Introduce property file refactoring can be applied for moving infrequently changing or static properties out of the main build file body to raise the overall legibility and keep them distinct from runtime properties. The downside of this refactoring is a lost of property visibility and breaking up the former single build file into multiple units, which is contradictory to the third ANT best practice named 'Prefer a Single Buildfile' of an older best practice catalogue compiled by Eric M. Burke. So in this case, like in any case, you have to make your own choice based on your needs and requirements.

3. Replace comment with description

Annotate elements(targets) with the description attribute instead of XML comments.

Before:

<!-- This target runs the PHP_Codesniffer task and reports coding standard violations --!>
<target name="sniff-report">
  ....
</target>

After:

<target name="sniff-report" description="Runs the PHP_Codesniffer task and reports coding standard violations">
  ....
</target>

Often build files are accentuated with plain XML comments to retain the mechanics and purpose of build file elements(i.e. targets) and can become a diversionary/obscuring source while maintaining or extending a build file. By using the available description attribute of the target element to annotate its purpose it's possible to reduce that kind of noise and even better, if used constantly, they can provide valuable information about all accumulated targets of a build file when phing is called with the -l(ist) option. As you can see the Replace comment with description refactoring requires a minimum of effort/investment to achieve a very valuable impact.

4. Reuse elements by id

Declare an instance e.g. a fileset once and make references to it elsewhere to reduce duplication and increase clarity.

Before:

<target name="phplint-report">
  <phplint>
    <fileset dir="${build.src}">
      <include name="**/*.php"/>
    </fileset>
  </phplint>
</target> 

<target name="sniff-report" depends="phplint-report">
  <phpcodesniffer standard="PEAR" format="summary">
    <fileset dir="${build.src}">
      <include name="**/*.php"/>
    </fileset>
  </phpcodesniffer>
</target>

After:

<fileset id="src_artifacts" dir="${build.src}">
  <include name="**/*.php"/>
</fileset>

<target name="phplint-report">
  <phplint>
    <fileset refid="src_artifacts" />
  </phplint>
</target> 

<target name="sniff-report" depends="phplint-report">
  <phpcodesniffer standard="PEAR" format="summary">
    <fileset refid="src_artifacts" />
  </phpcodesniffer>
</target>

The Reuse elements by id refactoring is, as the short description states, tailor-made to increase clarity while reducing code duplication, which is when present a risk that an alternation made to one element will be skipped for the other duplicates, by declaring top-level elements once by assigning an id attribute to it and then referring to it thoughout the rest of the build file. This refactoring is best compared to the classic sourcecode refactoring called Pull Up Method also catalogued by Martin Fowler and moreover it enforces the compliance with the DRY principle by providing a single point of change for futurities alternations.

5. Introduce distinct target naming

Use a different punctuation for targets and properties to enhance readability.

Before:

<property name="example.property1" value="abc" />
<property name="example_property2" value="def" />
<property name="example-Property3"  value="ghi" />

<target name="example.target1">
   <echo msg="${example.property1}" />
   ....
</target>

<target name="example-target2">
   <echo msg="${example-Property3}" />
   ....
</target>

After:

<property name="example.property1" value="abc" />
<property name="example.property2" value="def" />
<property name="example.property3" value="ghi" />

<target name="example-target1">
   <echo msg="${example.property1}" />
   ....
</target>

<target name="example-target2">
   <echo msg="${example.property3}" />
   ....
</target>

The Introduce distinct target naming refactoring once again tackles the improvement of readability in a build file by applying a constant and different punctuation on the common elements: targets and properties. The appliance of this refactoring leaves you and coworkers with an immediate reply whether you're looking at a property value or a target and can lead towards an agreed upon in-house/project build file coding standard. For target names underscores and dashes are suitable, although dashes are preferred by me as a hypen is used when enforcing internal targets, while for the build properties dots should be considered to build namespaces and their names should 'always' be lowercased except for environment variables/properties.

In case this blog post whetted your appetite for more, heavier and here uncovered build file refactorings, you might consider picking up a copy of the ThoughtWorks Anthology book. Last but not least a shout out goes to the build doctor for the remix permission and until the next post I'm ghost like dog.

Hooking a Growl publisher plugin into Xinc

2008-04-17T00:37:00.009Z

This week I finally had the time to setup Xinc, PHP's shiny new Continuous Integration(CI) server, on my MacBook and started to fiddle with it's publisher plugins and plugin architecture. While still down with 'tool envy' influenza I recently came across some nice and inspiring blog posts from the Ruby/Rails camp, showing how to employ Growl as an useful and fun feedback radiator for test/spec results. Since then the idea of building a Growl publisher plugin for Xinc was travelling my mind repeatedly, so the following post will break this circle and show a possible approach to build such a plugin, which can be used to notify the build result for continuously integrated projects and thereby provide an on-point/immediate feedback.

Building the Growl publisher plugin

Xinc comes with an elegant plugin system, allowing you to easily role your own one. The following code shows the plugin class and is the place where the actual Growl notifications are executed/raised by calling the growlnotify CLI. The images in the public growl() method, used to accent the two main build statuses(failure and success) in the Growl notification, are borrowed from this blog post and should be located in the $HOME/Pictures directory.

<?php
/**
 * A Growl publisher plugin for Xinc
 *
 * @package Xinc.Plugin
 * @author Raphael Stolt
 * @version 2.0
 * @copyright 2008 Raphael Stolt, Constance
 * @license  http://www.gnu.org/copyleft/lgpl.html GNU/LGPL, see license.php
 */
require_once 'Xinc/Plugin/Base.php';
require_once 'Xinc/Plugin/Repos/Publisher/Growl/Task.php';

class Xinc_Plugin_Repos_Publisher_Growl extends Xinc_Plugin_Base
{
    public function validate()
    {
        return true;
    }
    public function getTaskDefinitions()
    {
        return array(new Xinc_Plugin_Repos_Publisher_Growl_Task($this));
    }
    private function _sendGrowlNotification($message, $image, $name)
    {
        $command = "growlnotify -w -m '{$message}' "
                 . "-n '{$name}' "
                 . "-p 2 --image {$image}";

        Xinc_Logger::getInstance()->info('Executed growlnotify command: ' . $command);

        exec($command, $response, $return);

        if ($return === 0) {
            return true;
        }
        return false;
    }
    public function growl(Xinc_Project &$project, $message, $buildstatus, $name = 'Xinc')
    {
        if ($buildstatus === Xinc_Build_Interface::PASSED) {
            $image = '$HOME/Pictures/pass.png';
            $buildstatus = 'PASSED';
        } elseif ($buildstatus === Xinc_Build_Interface::FAILED) {
            $image = '$HOME/Pictures/fail.png';
            $buildstatus = 'FAILED';
        }

        $project->info('Executing Growl publisher with content '
                      ."\nMessage: " . $message
                      ."\nBuildstatus: " . $buildstatus
                      ."\nImage: " . $image);

        return $this->_sendGrowlNotification($message, $image, $name);
    }
}

The next big code chunk shows the task definition of the plugin and is the place where the publisher plugin name and is acceptable and required attributes are programmaticly defined, as you can see the Growl task currently only takes a required message attribute which can be set for the Growl publisher within the Xinc project configuration file.

<?php
/**
 * A Growl publisher plugin task for Xinc
 *
 * @package Xinc.Plugin
 * @author Raphael Stolt
 * @version 2.0
 * @copyright 2008 Raphael Stolt, Constance
 * @license  http://www.gnu.org/copyleft/lgpl.html GNU/LGPL, see license.php
 */
require_once 'Xinc/Plugin/Repos/Publisher/AbstractTask.php';

class Xinc_Plugin_Repos_Publisher_Growl_Task extends Xinc_Plugin_Repos_Publisher_AbstractTask
{
    private $_message;

    public function setMessage($message)
    {
        $this->_message = $message;
    }
    public function getName()
    {
        return 'growl';
    }
    private function _isGrowlnotifyAvailable()
    {
        exec('growlnotify -v', $reponse, $return);

        if ($return === 0) {
            return true;
        }
        return false;
    }
    public function validateTask()
    {
        if (!$this->_isGrowlnotifyAvailable()) {
            $message = 'The growlnotify command seems to be not available '
                     . 'on this system';
            Xinc_Logger::getInstance()->error($message);
            throw new RuntimeException($message);
        }

        if (!isset($this->_message)) {
              $message = 'Element publisher/growl - required attribute '
                       . '\'message\' is not set';
              throw new Xinc_Exception_MalformedConfig($message);
        }
        return true;
    }
    public function publish(Xinc_Build_Interface &$build)
    {
        $statusBefore = $build->getStatus();
        $res = $this->_plugin->growl($build->getProject(), $this->_message, $build->getStatus());
        if (!$res && $statusBefore == Xinc_Build_Interface::PASSED ) {
            /**
             * Status was PASSED, but now the publish process made it fail
             */
            $build->setStatus(Xinc_Build_Interface::FAILED);
        }
    }
}

Hooking the Growl publisher plugin into the build system

To make the just crafted Growl publisher plugin available to the Xinc build system you have to add the plugin file and class name/path to the /etc/xinc/system.xml file. After restarting the Xinc server the Growl publisher should be available to use and also be listed in the section of the /var/log/xinc.log file stating all registered plugins.

The next listing shows the Growl publisher plugin added to the aforementioned XML file.

<?xml version="1.0" encoding="UTF-8"?>
<xinc>
  <configuration>
    <setting name="loglevel" value="2"/>
    <setting name="timezone" value="Europe/Berlin"/>
  </configuration>
  <plugins>
    <plugin filename="Xinc/Plugin/Repos/ModificationSet.php" classname="Xinc_Plugin_Repos_ModificationSet"/>
    ...
    <plugin filename="Xinc/Plugin/Repos/Publisher/Growl.php" classname="Xinc_Plugin_Repos_Publisher_Growl"/>
    ...
    <plugin filename="Xinc/Contrib/Warko/Plugin/ModificationSet/SvnTag.php"
            classname="Xinc_Contrib_Warko_Plugin_ModificationSet_SvnTag"/>
  </plugins>

  <engines>
    <engine classname="Xinc_Engine_Sunrise" filename="Xinc/Engine/Sunrise.php" default="default"/>
  </engines>
</xinc>

Putting the Xinc Growl publisher plugin to action

Now that the Growl publisher plugin is available it can be used in the build cycle. The following Xinc project configuration file shows the utilization of the Growl publisher plugin in both of the main publisher realms onsuccess and onfailure.

<?xml version="1.0" encoding="UTF-8"?>
<xinc engine="Sunrise">
  <project name="recordshelf">
    <configuration>
      <setting name="loglevel" value="2"/>
    </configuration>
    <property name="dir" value="${projectdir}/${project.name}" />
    <property name="build.failure.message" value="Build for project ${project.name} failed!"/>
    <schedule interval="180" />
    <modificationset>
      <svn directory="${dir}" update="true" />
    </modificationset>
    <builders>
      <phingbuilder buildfile="${dir}/build.xml" target="main"/>
    </builders>
    <publishers>
      <onfailure>
        <email to="example@example.com" subject="[${project.name}] Build failure"
               message="${build.failure.message}" />
        <growl message="${build.failure.message}" />
      </onfailure>
      <onsuccess>
        <email to="example@example.com" subject="[${project.name}] Build success"
               message="Build for project was successful" />
        <growl message="Build for project ${project.name} was successful." />
      </onsuccess>
    </publishers>
  </project>
</xinc>

The next two images are finally showing the Growl notifications for a successful and a failed build. To minimize the notification noise it's a good and common practice to only 'ring the alarm' for failed builds, which can be achieved by using the Growl publisher only in the onfailure publisher realm of the Xinc project configuration file. Nuff talk, happy Xincing!

Getting an overview of all targets accumulated in a Phing build file

2008-03-29T18:04:00.006Z

Looking for an equivalent to Ant's -p(rojecthelp) command-line option in Phing, I dug up that you can use Phing's -l(ist) option to get a quick overview of all targets hosted in a given build file. This comes in handy when you are maintaining build files or have to get a raw picture of the provided targets of a project specific build file. The following console output shows the targets hosted in a example build file. As you will see, by using the -l command-line option you get an overview of the default target, the main targets and further subtargets.

triton:work stolt$ phing -l
Buildfile: /Volumes/USB DISK/work/build.xml
Build file for recordshelf project
Default target:
-------------------------------------------------------------------------------
 help                Displays the help for this build file

Main targets:
-------------------------------------------------------------------------------
 build               Builds the project
 clean               Removes data left over by former build
 cs-coding-standard  Runs the coding standard code inspection
 help                Display the help for this build file
 init                Initializes the build process
 layout              Creates the project layout for the build
 lint-project        Lints all code artifacts
 test-components     Runs the automated component tests
 test-integration    Runs the automated integration tests
 test-units          Runs the automated unit tests

Subtargets:
-------------------------------------------------------------------------------
 build-initial-model

A target becomes a main target when it has an non-empty description attribute, otherwise it will be a subtarget. This can be used to define the visibility and thereby 'callability' of targets, similar as you would do when defining access specifiers for class members of a PHP class. Main targets would become the public targets of your build file and all subtargets could be considered as private targets, which shouldn't be called directly as they might/should be used to provide specific helper functionality to public main targets or target wrappers. To definitively veto the call to a target, which never should be run directly via the Phing CLI(e.g. phing tragetname), just define an invalid target name(i.e. -build-initial-model instead of build-initial-model) so the Phing CLI will respond with an error and thereby not run the build file. The next console output shows the Phing CLI response when calling a private target.

triton:work stolt$ phing -build-initial-model
Unknown argument: -build-initial-model
phing [options] [target [target2 [target3] ...]]
Options:
  -h -help               print this message
  -l -list               list available targets in this project
  -v -version            print the version information and exit
  -q -quiet              be extra quiet
  -verbose               be extra verbose
  -debug                 print debugging information
  -logfile <file>        use given file for log
  -logger <classname>    the class which is to perform logging
  -f -buildfile <file>   use given buildfile
  -D<property>=<value>   use value for given property
  -find <file>           search for buildfile towards the root of the
                         filesystem and use it
  -inputhandler <file>   the class to use to handle user input

Report bugs to <dev@phing.tigris.org>

This post is somehow a partial and PHP flavoured remix of a post by Julian Simpson, who runs the build doctor blog and is also the author of the 'Refactoring Ant Build Files' contribution to the upcoming ThoughtWorks Anthology book.

Sniffing refactoring needs

2008-03-11T14:30:00.001Z

While still messing around with the PHP_CodeSniffer Pear package, I took a somehow jealous 1000 feet look at some prominent code inspection tools of the Java community: PMD and Checkstyle. Browsing their available rule sets/checks I soon recognized that guaranteeing the coding standard adherence is just a partial aspect of these tools. The following post will focus on one of these additional aspects, which is finding problems related to the code size of the inspected code artifacts, by showing how to port two selected rules to sniffs for utilization with the PHP_CodeSniffer tool. These ported sniffs can be used to automatically spot obvious code smells in the code base and to signal the need to apply the appropriate and odour reducing activity known as refactoring. Further more a complete set of code size sniffs, going beyond the trageted realm of the sniffs to come, could be used to speed up the feedback loop and to reduce the effort for manual code reviews.

PMD has a rule named TooManyMethods which will fail when the inspected class is housing to much methods. In this case the class is probably breaking the Single responsibility principle and a refactoring i.e. Extract Class should be applied to reduce complexity and take along the additional advantages like an increased testability and a clear separation of concerns.

The following port of this rule simply counts the methods of the class under inspection and decides upon this count whether to raise an error, which will be reported, or not. It does so by analyzing the tokenised representation of the class under inspection and validating the relevant results against programmatically defined sniff criterions. For detailed information about how to roll your own sniffs take a look at the available tutorial of the PHP_CodeSniffer package.

<?php
/**
 * 'File-level' PHPDoc Block
 */

/**
 * This sniff counts the defined methods of a class and raises an error when
 * the configurable method amount per class is exceeded.
 *
 * An example of the targeted code size violation is:
 *
 * <code>
 *  class One
 *  {
 *      public function method1()
 *      {
 *          ...
 *      }
 *      ... // more methods
 *      public function methodN()
 *      {
 *          ...
 *      }
 *  }
 * </code>
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Raphael Stolt <raphael.stolt@gmail.com>
 * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
 * @version   Release: @package_version@
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */
class Example_Sniffs_CodeSize_ToManyMethodsSniff implements PHP_CodeSniffer_Sniff
{
    /**
     * Defines the maximum of allowed methods in a inspected class.
     *
     * @var integer
     */
    private $_maxMethodsPerClass = 10;

    /**
     * Returns the token types this sniff is interested in.
     * For an overview of available tokens take a look at the
     * PHP_CodeSniffer_Tokens class.
     *
     * @return array(int)
     */
    public function register()
    {
        return array(T_CLASS);
    }
    /**
     * Processes the tokens that this sniff is interested in.
     *
     * @param PHP_CodeSniffer_File $phpcsFile The file where the token was found.
     * @param int                  $stackPtr  The position in the stack where
     *                                        the token was found.
     *
     * @return void
     */
    public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
    {
        $classTokenIndex = $phpcsFile->findNext(array(T_CLASS), $stackPtr);
        $classNameTokenIndex = $phpcsFile->findNext(array(T_STRING), $classTokenIndex);

        $className = $phpcsFile->getTokensAsString($classNameTokenIndex, 1);

        $methodTokenIndex = $stackPtr;

        $foundMethodTokens = 0;

        // Get all methods of class and increase counter on appearance

        while ($methodTokenIndex = $phpcsFile->findNext(array(T_FUNCTION), $methodTokenIndex + 1)) {
            if ($methodNameTokenIndex = $phpcsFile->findNext(array(T_STRING), $stackPtr)) {
                $foundMethodTokens+=1;
            }
        }

        // Decide if there is a sniff violation and raise error in case of

        if ($foundMethodTokens > $this->_maxMethodsPerClass) {
            $message = "Method count in class '{$className}' exceeded "
                     . "the defined maximum of {$this->_maxMethodsPerClass}"
                     . ". Found {$foundMethodTokens} methods";
            $phpcsFile->addError($message, $stackPtr);
        }
    }
}
?>

Another rule of PMD, falling in the rule set targeting code size violations, is called ExcessiveMethodLength and can also be easily ported to a PHP_CodeSniffer sniff. A violation of this rule/sniff, by exceeding the configurable method length, indicates again the need to put on the refactoring hat for keeping the code base in a non broken window state. The suitable refactorings in this case would be Extract Method or Move Method.

<?php
/**
 * 'File-level' PHPDoc Block
 */

/**
 * This sniff counts the lines of a defined method and raises an error when
 * the configurable method loc is exceeded.
 *
 * An example of the targeted code size violation is:
 *
 * <code>
 *  class One
 *  {
 *      public function toLongMethod()
 *      {
 *          // lots of code exceeding the configurable method loc
 *      }
 *  }
 * </code>
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Raphael Stolt <raphael.stolt@gmail.com>
 * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
 * @version   Release: @package_version@
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */
class Example_Sniffs_CodeSize_MethodLengthSniff implements PHP_CodeSniffer_Sniff
{
    /**
     * Defines the maximum of allowed lines in an inspected method.
     *
     * @var integer
     */
    private $_maxMethodLoc = 100;
    /**
     * Defines whether to exclude comments from the method loc.
     *
     * @var boolean
     */
    private $_exludeComments = true;
    /**
     * Defines whether to exclude empty lines from the method loc.
     *
     * @var boolean
     */
    private $_excludeEmptyLines = true;

    /**
     * Returns the token types this sniff is interested in.
     * For an overview of available tokens take a look at the
     * PHP_CodeSniffer_Tokens class.
     *
     * @return array(int)
     */
    public function register() {
        return array(T_FUNCTION);
    }
    /**
     * Processes the tokens that this sniff is interested in.
     *
     * @param PHP_CodeSniffer_File $phpcsFile The file where the token was found.
     * @param int                  $stackPtr  The position in the stack where
     *                                        the token was found.
     *
     * @return void
     */
    public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
    {
        $tokens = $phpcsFile->getTokens();
        $methodName = $phpcsFile->getDeclarationName($stackPtr);

        $methodBeginScope = $tokens[$stackPtr]['scope_opener'] + 1;
        $methodClosingScope = $tokens[$stackPtr]['scope_closer'];

        // Get method body

        $methodBody = $phpcsFile->getTokensAsString($methodBeginScope,
            $methodClosingScope - $methodBeginScope);

        $methodLines = explode("\n", $methodBody);

        $funtionalMethodLines = array();

        if ($this->_exludeComments) {
            $commentPattern = '/^#.*' .         // Hash comment
                              '|^\/\/.*' .      // Opening comment
                              '|^\*.*' .        // Continuing multiple line comment
                              '|^\*\/' .        // Closing comment
                              '|^\/\*\*.*' .    // Opening comment/doc
                              '|^\/\*.*\*\//i'; // Single line comment
        }

        // Handle each method line

        foreach ($methodLines as $methodLine) {

            $methodLine = str_replace(array(" ", "\t", "{"), '',
                $methodLine);

            if ($this->_exludeComments) {

                preg_match($commentPattern, $methodLine, $matches);

                if (count($matches) > 0) {
                    continue;
                }
            }
            if ($this->_excludeEmptyLines) {
                if (strlen($methodLine) > 1) {
                  $funtionalMethodLines[] = $methodLine;
                }
            } else {
                $funtionalMethodLines[] = $methodLine;
            }
        }

        $methodLoc = count($funtionalMethodLines);

        // Decide if there is a sniff violation and raise error in case of

        if ($methodLoc > $this->_maxMethodLoc) {
            $message = "Method '{$methodName}' LOC exceeded the defined "
                     . "maximum of {$this->_maxMethodLoc} lines. Found "
                     . "{$methodLoc} LOC";
            $phpcsFile->addError($message, $stackPtr);
        }
    }
}
?>

In case you want to twiddle around with these exploratory sniffs you have to put the sniff definitions in the appropriate directory i.e. PEAR/PHP/CodeSniffer/Standards/Example/Sniffs/CodeSize and create a 'coding standard' i.e. PHP_CodeSniffer_Standards_Example_ExampleCodingStandard for making the sniffs runnable and available to the inspection tool.

The closing console dump shows the two previous listed code size sniffs in action and the errors raised, after sniffing obvious refactoring needs in an inspected class.

triton:tmp stolt$ phpcs --standard=Example Test.php

FILE: /Volumes/USB DISK/tmp/Test.php
--------------------------------------------------------------------------------
FOUND 2 ERROR(S) AND 0 WARNING(S) AFFECTING 2 LINE(S)
--------------------------------------------------------------------------------
 2 | ERROR | Method count in class 'Test' exceeded the defined maximum of 10.
   |       | Found 12 methods
 5 | ERROR | Method 'longMethod' LOC exceeded the defined maximum of 100 lines.
   |       | Found 120 LOC
--------------------------------------------------------------------------------

'Zend Framework Das Entwickler-Handbuch' Buch Rezension

2008-02-28T11:43:00.009Z

Yesterday I received the book 'Zend Framework Das Entwickler-Handbuch' written by Carsten Möhrke and published via Galileo Press. As the targeted audience of this book will be mainly german-speaking readers and the publisher has currently no intention to publish it in other languages, I will switch the language for this book review.

'Zend Framework Das Entwickler-Handbuch' bietet auf insgesamt 420 Seiten einen guten Einstieg in die Anwendungsentwicklung mit dem Zend Framework bis zu der Version 1.0.3. In den einführenden Kapiteln werden grundlegende Themen wie die Installation des Frameworks, die Theorie des MVC Patterns und dessen Realisierung mit den entsprechenden Komponenten des Zend Framework behandelt. Die folgenden Kapitel des Buches sind dann meist vom MVC Kontext losgelöst und bieten daher gerade für Einsteiger die Möglichkeit weitere Komponenten wie z.B. Zend_Db und Zend_Db_Table für den Datenbankzugriff oder Zend_Auth für die Benutzerauthentifikation isoliert zu erkunden und deren Prinzipien zu verstehen. Das Spektrum der im Buch behandelten Komponenten erstreckt sich von Zend_Acl bis Zend_XmlRpc und bietet somit einen guten Gesamtüberblick auf die vorhandenen und nutzbaren Funktionalitäten des Frameworks. Die einzelnen Komponenten werden dem Leser jeweils durch meist adäquate Code-Listings und die in den Kontext passende Theorie nähergebracht. Aufgrund der raschen technischen Entwicklung und dem etwas unglücklichen gewählten Veröffentlichungstermins werden Komponenten wie z.B. Zend_Layout und Zend_Form aus dem Zend Framework 1.5.0 Preview Release leider nicht behandelt.

Das Buch wendet sich meiner Meinung nach in erster Linie an Einsteiger, welche am Zend Framework interessiert sind und einen schnellen, portablen und deutschsprachigen Einstieg in dessen Magie haben wollen. Für diese Zielgruppe ist das Buch eine klare Empfehlung.

Für Leser die sich schon gute Kenntnisse im Umgang mit dem Framework erarbeitet haben und Besitzer eines permanenten Onlinezugangs sind bietet dieses Buch meiner Meinung nach leider keinen großen Mehrwert, da es ein sehr gutes und kostenloses Referenzhandbuch gibt und auftretende Detailfragen meist mittels diesem, der vorbildlichen API Dokumentation oder in letzter Instanz mit der Hilfe der rasch reagierend Mailinglist Community geklärt werden können. Für diese Zielgruppe ist meine Empfehlung es einmal Probe zu lesen und dann selbst zu entscheiden.

Als einen kaufentscheidenden Mehrwert für erfahrene Leser hätte ich mir z.B. ein grundlegendes Kapitel über das Testen von Zend Framework Anwendungen mit einem xUnit Framework z.B. PHPUnit gewünscht, dieser Aspekt wird von dem Autor leider total ausgeklammert.

Creating Zend Framework snippets for TextMate

2008-02-18T20:36:00.006Z

After finally converting to Mac OS X, I really couldn't resist to fall for the famous TextMate editor. The editor comes with a nice PHP bundle authored by Ciarán Walsh that eases the typing and creation of common language constructs like classes and control structures by entering pre-defined keys and hitting the tab key to insert and customize them. To reduce the typing effort for the most common tasks in creating a Zend Framework based application, which are creating action controllers including their hosted actions and creating new models for accessing the underlying database, I spent some minutes to figure out how to create and add these valuable snippets to the default PHP bundle.

Adding the controller and model snippets

The Bundle Editor of TextMate is a starter aid that can be used to create the intended Zend Framework snippets and categorize them. To add a new snippet simply select the PHP bundle and hit the most left button in the lower left of the Bundle Editor window. Now you are able to create new snippets, edit their content and assign an activation key to them i.e. zfc and also to define the snippet scope i.e. source.php.

To trigger the automatic insertion of the new snippet you just have to type zfc and hit the tab key in an openend PHP file. The next listing shows the snippet code for the creation of a Zend Framework action controller and as you will notice it contains several at first glance variable look-a-likes. All variables prefixed with TM are definable via the TextMate preferences while the numeric indexed variables are used to tab through the code after insertion and to modify the custom parts like the name for the controller class. They start by an index of 1 for the first tab position after the snippet insertion and end with an index of 0 for the last tab position. Thereby the first two tab strikes will allow you to modify the PHPDoc block while the third tab strike will allow you to edit the controller name e.g. News, which whould make the current code artifact your NewsController class.

/**
 * ${1:'File-level' PHPDoc Block} 
 *
 * @author  ${PHPDOC_AUTHOR:$TM_FULLNAME} <$TM_ORGANIZATION_EMAIL>
 */

/**
 * ${2:'Class-level' PHPDoc Block}
 *
 * @author  ${PHPDOC_AUTHOR:$TM_FULLNAME} <$TM_ORGANIZATION_EMAIL>
 */
class ${3:Name}Controller extends Zend_Controller_Action
{
    /**
     * ${4:'Method-level' PHPDoc Block}
     */ 
    public function ${5:name}Action()
    {
        $6
    }
    $0
}//Activation key: zfc tab

As an action contoller surely will increase all allong by several more actions the next listing shows the snippet code to add a single action to a currently opened action controller class by simply entering zfca and striking the tab key.

/**
 * ${1:'Method-level' PHPDoc Block}
 */
public function ${2:name}Action()
{
    $0
}//Activation key: zfca tab

The next ~~last valuable~~ snippet would refer to the model part of a Zend Framework application, so the listing shows a snippet for a table class, which automatically sets the table name property to the lowercased and prior entered class name. This snippet would be inserted into the current PHP file by entering the activation key zfm and striking the tab key again.

/**
 * ${1:'File-level' PHPDoc Block}
 * @author ${PHPDOC_AUTHOR:$TM_FULLNAME} <$TM_ORGANIZATION_EMAIL>
 */

/**
 * ${2:'Class-level' PHPDoc Block}
 * @author ${PHPDOC_AUTHOR:$TM_FULLNAME} <$TM_ORGANIZATION_EMAIL>
 */
class ${3:Name} extends Zend_Db_Table_Abstract
{
    protected \$_name = '${3/./\l$0/}';
}//Activation key: zfm tab

Adding a View Helper snippet

The next snippet was provided by a reader called Jeff Federmann, who contacted me via mail as Google ate his code he tried to contribute in a comment. This snippet can get you up to speed when developing custom View Helpers. The workflow for this snippet is to create a new file for the helper, saving it with a purpose indicating name, which will auto-determine the View Helper class name on code insertion, and trigger the snippet by entering the activation key i.e. zfvh plus hitting the tab again. So nuff talk. Here is the snippet contributed by Jeef.

/**
* ${1:'File-level' PHPDoc Block} 
*
* @author  ${PHPDOC_AUTHOR:$TM_FULLNAME} <$TM_ORGANIZATION_EMAIL>
*/

/**
* ${2:'Class-level' PHPDoc Block}
*
* @author  ${PHPDOC_AUTHOR:$TM_FULLNAME} <$TM_ORGANIZATION_EMAIL>
*/
class Zend_View_Helper_${3:`#!/usr/bin/env php 
$filename = $_ENV['TM_FILENAME'];
$filename = str_replace('.php', '', $filename);
echo $filename;
?>`} extends Zend_View_Helper_Abstract
{
   /**
    * ${4:'Method-level' PHPDoc Block}
    */ 
   public function ${3/./\l$0/}()
   {
       $5
   }
   $0
}

Housing the Zend Framework snippets

To finally categorize the Zend Framework snippets and avoid bloating the default PHP Bundle the Bundle Editor comes to rescue again, as it allows to add new categories to an existing bundle in which the shown snippets and other compatible and common snippets, e.g. Zend_Registry access to acquire the application's Zend_Log instance, can be housed.

Zend Framework coding standards on one page

2008-02-11T18:26:00.000Z

Before jumping into the development of a Zend Framework coding standard for the PHP_CodeSniffer Pear package, I spent some time revisiting and compiling the available Zend Framework coding standards into a handy one-paged Pdf document.

In case somebody is interrested it's available here.

PHP_CodeSniffer task is in the current Phing branch

2008-02-08T13:32:00.000Z

A few days ago I was evaluating the need for writing a Phing task for the awesome PHP_CodeSniffer Pear package and noticed that Dirk Thomas blessedly already added one to the current Phing Svn branch. That's again extending the range of available tools that PHP's Continuous Integration(CI) toolchain has to offer and I quess there are more to follow, as Manuel Pichler just announced the development start of PHP_Depend.

To get the 2.3 Phing branch including the mentioned PHP_CodeSniffer task and it's documentation simply run a svn checkout http://svn.phing.info/branches/2.3 /path/to/phing-checkout-dir and you're ready to add continuous monitoring of coding standard adherence to your builds.

For simplifying the integration of the just checked out Phing 'branch' release into an existing Pear environment you can build a new Pear package by calling the buildfile in /path/to/phing-checkout-dir/pear. The built Pear package will be located in /path/to/phing-checkout-dir/pear/build and can than be used to switch the installed Phing Pear release.

Also make sure you have installed the underlying PHP_CodeSniffer Pear package via the Pear Installer.

Although the task is very well documented the next code snippet shows the shiny PHP_CodeSniffer task in an example build file.

<?xml version="1.0"?>
<project name="example" default="build" basedir=".">

   <target name="build" depends="clean, svn-checkout, code-inspection, test">

   ...

   </target>

   ...

   <target name="code-inspection" description="runs code inspection on the stated directory">
     <phpcodesniffer standard="PEAR"
                     format="summary"
                     tabWidth="4"
                     file="/path/to/source-files"
                     allowedFileExtensions="php"/>
     </phpcodesniffer>
   </target>

</project>

Zend Framework in Action Pre-review

2007-12-03T11:40:00.000Z

For the last few days I've been reading the MEAP release of Zend Framework in Action from Rob Allen and Nick Lo published by Manning Publications and as a pre-review I d'like to share my reading experience. Currently there are 6 of totally 16 intended chapters available, to find out if them are already worth the money you might want to read further.

What's in it?
The first two chapters are introductional and outline what's in the Zend Framework and how it can support and ease the development of (enterprise) web applications. The obligatory Hello World application is used to provide a quick introduction to the MVC pattern and how it's implemented by the framework's controller system and how each part of the MVC pattern is represented in the code artifacts of a application. Next the anatomy of a Zend Framework based application (directory structure, bootstrapping and the request routing to the various components) is layed out to the reader.

After prodviding this 3,000 feet view a community application is introduced, providing the stories and models which will be implemented with the appropriate Zend Framework components and evolve with the coming close-up view chapters. The book carries on to get the guiding application initially going and introduces techniques how to unclutter views through the Two-Step View design pattern and how to build a growing safety-net for your application and it's further evolution via unit tests written in PHPUnit.

The next chapter opens the close-up views by looking at Ajax and how it fits within Zend Framework based applications. The connection of the views to the server/model code is demonstrated first via handcrafted code and next by using two common JavaScript libraries named Prototype and Yahoo! User Interface (YUI). Additional JSON, an important connector in nowadays Ajax application, is covered by taking a look at the Zend_Json component.

Next the focus descends two layers deeper into the model, hosting the specific business logic of an application, by covering the way to establish a connection to the database via the Zend_Db_Adapter and how to perform CRUD actions against it with the Zend_Db_Table component. The linking of tables together is explained by a closer look at the table relationship feature of the Zend_Db_Table component. As a very valuable goodie the authors provide their additional knowledge about testing Zend Framework models.

The last available chapter introduces the concepts of authorisation and authentication and goes on providing the needed theoretical background in addition with explanatory implementations for both scenarios.

Conclusion
As this book is co-authored by Rob Allen, who provides the very valuable introduction I assume everyone getting started with the Zend Framework has used or at least noticed, Zend Framework in Action is the more detailed and naturally matured sequel of it. Though the book isn't released yet the provided knowledge is already valueable whether for novice or more advanced learners/developers whose thirst for knowledge isn't fully covered by the Zend Framework manual. Personally I liked the fact that the authors share their knowledge about unit testing Zend Framework applications and that the reader is guided along an example application, which might motivate to further exploratory coding activities. Reading only these first available chapters leaves you waiting for the rest of it.

Utilizing designer toys as an extreme feedback device

2007-11-07T17:16:00.000Z

In response to Nick Halstead's Programming Tips Competition I dug a bit in my blog's idea queue for something related. The idea I picked includes some thoughts on how to gently prod the implementation of developer testing/specifying as an everyday team practice, assuming a head-nod/good-to-go from management. So today you won't see any code, as this is more related to the area of team building and process adoption. Instead of starting with the 'dictatorial' hammer and thereby possibly discouraging T2 developers or scaring away T3 developers, it would be wisely to use a fun and far more important attention creating approach. As this idea popped up on my mind I found a really suitable designer toy called Totem Doppelganger from Anton Ginzburg, consisting of three stackable look-a-like ghosts. I guess an excellent match to disenchant the initial 'mystics' of developer testing/specifying. As them are separable they can be used to accompany and indicate the ranged skill-development of each involved developer/team and thereby act as an extreme feedback device for both parties.

An example scenario could be:

At the beginning of process adoption every developer/team without or less previous knowledge might get two feedback devices(ghosts), which will be reduced to one on the path to the expected knowledge. One device might remain to signal the willingness to spread the gained knowledge to other struggling with adoption the practices or new team members, this tends to the direction of building a Developer Testing Master. In the case of not practicing pair-programming they can even act as a reminder to apply developer testing/specifying until it becomes a flesh-and-blood habit.