Use DocBlox in Symfony2 for inspecting DocComment blocks

Posted on by Matthias Noback

This article is deprecated. DocBlox has been merged with phpDocumentor. I also don't recommend copying specific files from a vendor library to your project, let alone copy them to the vendor directory (like I do in this article).

I was looking for a way to automatically generate some documentation, and because all the required information was already in the DocComment blocks. I downloaded the great documentation generator DocBlox (which is a PHP application by itself) and looked in it's source code. Soon I found DocBlox's Reflection classes which are able to parse a DocComment block. So I wanted to use these classes! Here is how you can do it:

  1. Download the latest DocBlox zip file

  2. Unzip the archive

  3. Create the directory /vendor/docblox/src/DocBlox in your Symfony2 project

  4. From the archive:

    • copy /src/DocBlox/Reflection and it's contents to the directory you have just created

    • copy /src/markdown.php and the directory /src/markdown and it's contents to /src/vendor/docblox/src

    • Copy /LICENSE to /vendor/docblox

Now your directory structure should look like:

/vendor
  /docblox
    /src
      /DocBlox
        /Reflection/*
      /markdown/*
      /markdown.php
    /LICENSE

The license requires you to copy it with the code, even if you use part of it.

Now open /app/autoload.php and add the "DocBlox_" prefix to the autoloader:

$loader->registerPrefixes(array(
    'Twig_Extensions_' => __DIR__.'/../vendor/twig-extensions/lib',
    'Twig_'            => __DIR__.'/../vendor/twig/lib',
    // ...
    'DocBlox_'         => __DIR__.'/../vendor/docblox/src',
));

Also add this line to /app/autoload.php:

require_once __DIR__.'/../vendor/docblox/src/markdown.php';

This will enable you to use Markdown formatting in your DocBlocks.

The DocBlox reflection classes are now available in your project. I tested my configuration by creating the following action, which displays the type and description of it's own return value:

   /**
     * Displays it's own "return" tag
     * 
     * The "docBlox" action uses the DocBlox "DocBlock" reflection class
     * 
     * @return Symfony\Component\HttpFoundation\Response The response
     */
    public function docBloxAction()
    {
        $reflectionMethod = new \ReflectionMethod($this, 'docBloxAction');
        $docBlock = new \DocBlox_Reflection_DocBlock($reflectionMethod);

        $returns = $docBlock->getTagsByName('return');
        if (!empty($returns)) {
            $return = reset($returns); // get the first "return" tag
            /* @var $return DocBlox_Reflection_DocBlock_Tag_Return */
            $type = $return->getType();
            $description = $return->getDescription();
            return new Response(sprintf('This method returns a %s which is %s', $type, lcfirst($description)));
        }

        return new Response('No return parameter was defined');
    }

As you can see, there is a limitation to the API of DocBlox: there is no getTag() method, only a getTags() and a getTagsByName() method, that both return an array. So you will have to reduce this to one tag yourself (for example by calling reset() on the array).

When this action is called, it renders the following text:

This method returns a Symfony\Component\HttpFoundation\Response which is the response
PHP Symfony2 autoloader DocBlox reflection
Comments
This website uses MailComments: you can send your comments to this post by email. Read more about MailComments, including suggestions for writing your comments (in HTML or Markdown).
eBuildy

Very nice article, simple with a short demo code, DocBlox opens lot of new opp. for Php developpement, currently I am doing a simple services injection to use in my SF2 project (in addition of the superbe SF2 DIC configurator but with a lazy dependencies creation

Gator92

Like Symfony, it's nice that you can use DocBlox components on their own. I was looking for a way to simply parse a raw DocComments return from the naitive Reflection classes, without re-inventing the wheel. Suprisingly, Doctrine doesn't seem to seperate the parsing or tokenization in their Annotations implementation. Upon further searches, I stumbled upon DocBlox, and subsequently, your blog, thanks for posting.

Matthias Noback

Thanks! That was also a surprise to me, the Doctrine annotation reader is quite good, but only for returning objects, not for retrieving plain text values.

cordoval

maybe, maybe not, it is a task to explore it now ... open to opportunity

matthiasnoback

Thanks for your reply. I may not have been very clear about this: my use of DocBlox is not in the "official" way. I have taken part of the DocBlox codebase to inspect/reflect on my own DocComment blocks. Auto-generating documentation for your Symfony2 project is a whole different piece of cake; though I'm sure there are good resources available on the Internet.

cordoval

not sure how useful this is, I am sure it is, it is just that one cannot see it because even though it seems very interesting you set it up provide all instructions but failed to give a pretty use case or something we can reuse in our projects, how to use it, how we can generate docu for a regular sf2 project automatically, etc. If there are other tools, what are the advantages, if this can be used for other uses/libraries etc...

please install wp notify comments via email so that we can follow up, email me your reply as i will probably will not see your response here. Then I can subscribe.

Thanks