14 janvier 2012

ClassGrapher



I have developped a small utility command line application able to generate simple class diagrams out of any set of namespaced PHP files. The goal being to have a quick way to figure out how some PHP classes were structured without browsing too much code. This is not very accurate but give you a quick big picture of the code structure.

The code can be found on github:
https://github.com/sixty-nine/ClassGrapher

The PHP parser

The class grapher does not use PHP reflection to gather inheritance information about the classes. Indeed, in order to work, PHP reflection needs to be able to instanciate the classes it loads. This is not possible if you have missing dependencies in your project.
The goal of the grapher was to draw the structure of any PHP files.
Thus I implemented a simple recursive parser for only the parts of the PHP language that were needed for the grapher (basically any "use", "namespace", "class" and "interface" statement).

Using composer to download vendors libraries

Composer is a PHP utility used to manage project dependencies.
See composer website.

The idea is simple.

You download the composer.phar binary to the root of your project, then create a composer.json file describing the dependencies of the project and finally run the command:

./composer.phar install

This will automatically download the dependencies as well as create an autoload file for your project.

Example of composer.json file

The grapher project uses the smyfony/console component from the Symfony2 framework. Additionnaly we would like to autoload the files of the project.

The corresponding composer.json file looks as follow:

{
    "require": {
     "symfony/console": "2.0.7"
    },

    "autoload": {
        "psr-0": {
            "LazyGuy\\ClassGrapher": "src"
        }
    }
}

This file will indicate to composer that the library "symfony/console" version "2.0.7" must be downloaded to the project directory. Furthermore any class in the namespace "LazyGuy\ClassGrapher" will be searched in the "src" directory.

Be carefull, this is JSON, you cannot add extra coma at the end of a list if there is no successor in the list (in PHP you can).

Using travis for continuous integration

Travis is a free, lovely continuous integration online service that provides seamless integration with github.

All you need to do is:
  1. Register to travis
  2. Go to github and enable the travis hook
  3. Create a .travis.yml file to indicate to travis how to run the tests of your app
This will cause any github commit in your project to trigger a build on the travis continuous integration server. Travis will run your tests in two PHP environments:
  • PHP 5.3
  • PHP 5.4

The .travis.yml file

This file must indicate to the travis server how to build your project.

In our case, travis must download the dependencies with composer and then run the tests

language: php
php:
  - 5.3
  - 5.4

before_script:
  - wget http://getcomposer.org/composer.phar
  - chmod +x composer.phar
  - ./composer.phar install

script: phpunit -c src/LazyGuy/ClassGrapher/Tests/

The language section indicates which is the language of the project. The "php" key lists the PHP versions to run the tests against. The section "before_script" tells to travis what to do before running the tests (here it will download composer and then run the install command). Finally the "script" section indicates the command to run the tests.

Once you configured travis, any commit to github will cause travis to build the project, run the tests, and report success or failure.

Isn't that lovely?