Adding PHPDocumentor (Sami) via Composer

In a previous article I demonstrated setting up a Silex project via composer. In addition to setting up PHPUnit I also mentioned how to get Codesniffer working to PSR2 coding standards. I figured a nice addition to that would be setting up PHPDocumentor.

Note: Using a document generator infers that you need documentation. If you’ve already got code and no documentation then it’s probably worth highlighting that some would say you are doing something wrong. Arguably, you should always have some documentation explaining what the API endpoints need to be, and what they should return. For the purposes of this article I shall assume that you’re like me – and want to create some pretty doucmentation automagically.

I’ve actually opted to use Sami over phpDocumentor2 – for reasons that phpDocumentor seemed to not fully support composer when Silex was installed (conflicting dependencies). There is also the addition that Sami is from Fabien Potencier of Sensio Labs, who wrote Silex.

Getting Started

Okay, so let’s dive right in – I’m assuming you’ve already got the application running from my previous article mentioned above.

Edit your composer.json:

{
    "minimum-stability": "dev",
    "require": {
        "silex/silex": "1.0.*@dev"
    },
    "autoload": {
        "psr-0": {"DVO": "src/"}
    },
    "require-dev": {
        "phpunit/phpunit": "3.7.*",
        "squizlabs/php_codesniffer": "1.*",
        "sami/sami" : "*",
    }
}

Now give composer a little nudge:

$ composer update --dev

Very quickly you can verify that Sami has been installed correctly:

$ ./vendor/bin/sami.php

If that spits out some useful help information then you’re onto a winner. The next step is to create a config file; I’ve gone for a basic implemtation just to get it up and running.

Create a config directory and create a new file called sami.php with the following:

<?php

return new Sami\Sami(__DIR__.'/../src/', array(
    'build_dir' => __DIR__.'/../build/sami/documentation',
    'cache_dir' => __DIR__.'/../build/sami/cache',
));

Give it another whirl:

$ ./vendor/bin/sami.php update config/sami.php

How easy was that? You will see it has dumped a bunch of stuff in the build/sami folder. You can easily browse the documentation and/or setup a vhost to share.

Nice and simple. Let me know if you have any thoughts/feedback.

Bobby (@bobbyjason)

Be Sociable, Share!
Share

Leave a Reply

Your email address will not be published. Required fields are marked *