PEAR coding standard Sublime Text snippets

Having recently installed PHP Code Sniffer plugin for Sublime Text one of the first “problems” I had was that my favourite documentation plugin so far, DocBlockr, did not produce documentation comment blocks adhering to my chosen coding standard.
I’ve adopted a mixed coding standard using PSR2 for the code itself and PEAR standards when it comes to documenting files and classes.
I’ve written some simple Sublime Text snippets to be able to consistently produce those properly formatted comments and made a little modification to the the default DocBlockr comment template to make it produce the right kind of comment blocks.

File comment block

Through trial and error I’ve been able to produce a proper file comment block and this is the end result

<?php
/**
 * A basic View controller implementation
 *
 * @category Frameworks
 * @package  TAD\MVC\Controllers
 * @author   theAverageDev (Luca Tumedei) <luca@theaveragedev.com>
 * @license  http://www.gnu.org/licenses/gpl.html GNU GPL
 * @link     (http://theaveragedev.local theAverageDev.com)
 */
...

where the snippet is now filled with my data. Creating snippets in Sublime Text is as easy as it can get and it really took just 20 minutes or so of fiddling to ge the job done. The snippet code itself is

<snippet>
<content><![CDATA[
/**
 * ${TM_FILENAME/(.*)[.](.*)/$1/g} class
 *
 * @category ${1:Category}
 * @package  ${2:Package}
 * @author   ${3:Author Name} <${5:author.email@example.com}>
 * @license  ${4:http://www.gnu.org/licenses/gpl.html GNU GPL}
 * @link     ${5:http://example.com}
 */
]]></content>
    <tabTrigger>filedoc</tabTrigger>
    <scope>source.php</scope>
    <description>The PSR-compatible file comment block, put it right after the opening php tag</description>
</snippet>

I’m using the file name minus the extension to default the file name to the name of the class I will define in it; since I stick to the one class, one file habit that works for me. I’ve hardwired all values save for the @category and @package ones in the actual implementation but the one above is a more general-purpose and reusable snippet that can be copied and pasted around.

Class comment block

The class comment block is almost the same as the one above in format and contents and have adjusted just some fields.

<snippet>
<content><![CDATA[
/**
 * Class ${TM_FILENAME/(.*)[.](.*)/$1/g} responsibility is to ${1:do stuff}
 *
 * @category ${2:Category}
 * @package  ${3:Package}
 * @author   ${4:Author Name} <${5:author.email@example.com}>
 * @license  ${5:http://www.gnu.org/licenses/gpl.html GNU GPL}
 * @link     ${6:http://example.com}
 */
]]></content>
    <tabTrigger>classdoc</tabTrigger>
    <scope>source.php</scope>
    <description>The PSR-compatible class comment block, put it before the class declaration</description>
</snippet>

Function comment block

Since DocBlockr does an excellent job in its commenting action the only change I’ve needed until now to satisfy PSR2 requirements is to add the following option in Sublime Text User Settings

"jsdocs_spacer_between_sections": true

and that will satisfy PSR requirements about functions comment blocks.

My code sniffer configuration

I actually run the code sniffer using the PSR2 standard in conjunction with PHP Coding standards fixer to cut the chore of having to manually fix the code to a minimum. Since PHP Code Sniffer plugin comes with the option to do so on every save I’ve chosen to do.