Customising or creating a special rule for function comments?

[aGiqs]

Hi,

Thank you for PHP_CodeSniffer tool! It is very helpful and flexible!

I'd like to create a special check for docblocks of all controller actions.

I wonder if something like this already exists:

Let's say I have an action declaration like 'public function indexAction()'.
So its regex identifier would be '[a-z0-9]Action' in this case.
Then I want to find out, if a line 'request paramerter' exists in the action PhpDocs (docblocks).
If not, a warning/error should be reported.

So a valid action would look like this:
e.g:

/**
 * Index action
 * 
 * request parameters: none
 *
 * @return void
 */
public indexAction()
{
    // ...
}

Are there any way to solve this task by customising Squiz.Commenting.FunctionComment (or any other) rule
( without extending/overwriting the original class code )?

I mean something like this:

<rule ref="Squiz.Commenting.FunctionComment">
   <properties>
        <property name="specialMethods" type="array">
            <element value="[a-z0-9]Action">
                <property name="findExpression" value="request parameters"/>
            </element>
        </property>
    </properties>
</rule>

Please, schare your ideas and especially solutions if you've already faced such kind of problem.

[gsherwood]

Are there any way to solve this task by customising Squiz.Commenting.FunctionComment (or any other) rule
( without extending/overwriting the original class code )?

No, the sniff has no settings for this. A new sniff would need to be written for this, but the use case is so specific that I don't think it would make it back into the core.

[aGiqs]

Thanx for your prompt answer.. Yes, you are right it's quite specific. I just had a slight hope, that there are some settings that I haven't found yet.. :-) I'll try then to extend an existing FunctionComment sniff ..

[aGiqs]

Hi again,

I've created a Sniff. The Sniff is placed together with my customized ruleset outside the PHP_CodeSniffer repository.
Everything works when I run phpcs checks and I get CS errors if the expression that should be in doc-block is missing.

I also have a class property in my sniff, which I would like to customize in the ruleset.
This way:

class ActionParamsSniff
    implements Sniff
{
    /**
     * String to search.
     *
     * @var string
     */
    public $expression = 'request params';

<rule ref="Customised.Commenting.ActionParams">
    <properties>
        <!-- The expression to search in action doc-block -->
        <property name="expression" value="my new expression to search" />
    </properties>
</rule>

My problem ist that the expression value in the ruleset is not passed to the class property.

Could you give me a tip how it should be configured, so it would be passed to the class?

[jrfnl]

@aGiqs Is your custom sniff in a standard and does the standard follow the (strict) directory layout and naming conventions for external standards ? See: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial

If not, chances are that the sniff name vs class matching will not work, which results in exactly the behaviour you are seeing.

[aGiqs]

Oh, I've found it !
The structure was right.

Customised/Sniffs/Commenting/ActionParamsSniff.php
Customised/ruleset.xml

But I used the wrong namespace in my ActionParamsSniff:
namespace PHP_CodeSniffer\Standards\PEAR\Sniffs\Commenting;

I've changed it to:
namespace PHP_CodeSniffer\Standards\Customised\Sniffs\Commenting;

And it works :-)

Thanx a lot for Your HELP!