New Universal.DeclareStatements.DeclareStatementsStyle sniff

[dingo-d]

This sniff will check the declare statements for a specific coding style.

By default, the style of the declare statement is without braces and will be applied for all the directives (strict_types, ticks, encoding).

The sniff can be configured to require or disallow braces (except for the strict_types), and selectively select for which directive the selected style should be enforced (ticks, encoding).

• Includes tests
• Includes documentation
• Includes metrics

[jrfnl]

Reviewed during pair programming session in which the review comments were discussed (which is why they are sometimes a bit shorthand).

Additional remarks/things to think over:

• If there is a declare statement with multiple directives and those directive have different requirements, i.e, strict_types: disallow and ticks set to require: how should this be handled by the sniff ?

For potentially adding fixers - helpful link: https://pear.php.net/package/PHP_CodeSniffer/docs/3.5.4/apidoc/PHP_CodeSniffer/Fixer.html

General remark: in the sniffs, everything which gets a docblock ought to get a @since tag in this repo (can't be enforced yet as there's no good sniff for it, but will be enforced in the future).
For the tests, just the @since at class level is fine.

[jrfnl]

Some ideas we discussed about adding metrics:

metric name "Declare statement modus"

values:

• block mode
• single-line

alternative style values:

• implode(', ', $directiveStrings) . block mode
• implode(', ', $directiveStrings) . single line mode

[dingo-d]

I've reworked the sniff and tests, but still need to work on the fixer and metrics.

Also, I expect there will be some remarks on the PR, those are definitely welcomed 🙂

[jrfnl]

FYI: I'm moving this PR out of the 1.0.0-alpha4 milestone as I'm hoping to release over the next few days.

[dingo-d]

@jrfnl I've added some metrics, but I'm unsure if this is correct.

When I run the report for metrics, I get correct percentages per file (all adds up to 100%) but I'm not sure if I'm doing it right, as in one file (3rd test file) I have multiple block directives. Some are ok, some are not, and the 2 are ok, but for some reason they are being counted as separate directives, and the type isn't correctly recognized:

vendor/bin/phpcs --standard=universal --sniffs=universal.declarestatements.blockmode Universal/Tests/DeclareStatements/BlockModeUnitTest.3.inc -sp --report=info

E 1 / 1 (100%)

PHP CODE SNIFFER INFORMATION REPORT
----------------------------------------------------------------------
Declare directive scope: Block [10/10, 100%]

Declare directive type: encoding [4/4, 100%]

----------------------------------------------------------------------
Time: 12.06 secs; Memory: 6MB

When debugging, the value is different (first encoding then ticks) but only encoding is reported.

I wanted to group the types, and they seem to be correctly recognized when they are on their own.

I still need to check if there are any fixable errors. The only fixable case I can think of could be if there is only one directive in the declare statement that is using block mode when it shouldn't. And then I need to be careful to correctly replace the closer, add semicolon, etc.

Edit:

I tried to add the fixer, but I got stuck, as there are tons of whitespace edge cases that can trip me up. I did save my WIP for the fixer in another branch so I may play with it later, but for now I'm not sure it's worth the time spent 🤷🏼‍♂️