I feel that I’m lucky that I work for a company and on projects that allow to control code style. In my opinion, having a unified code style might look like a bureaucracy but it greatly simplifies the reading of the code. And remember, we read the code 80% of the time.
So, as we as a team are working on WordPress plugins (WPForms and WP Mail SMTP, with 2+ with 1+ millions of active installs respectively) it’s logical that we inherit WordPress Coding Standards (WPCS).
WordPress Coding Standards structure
WPCS consists of one main
WordPress ruleset, which implements own sniffs and imports 3 other rulesets:
WordPress-Extra. Those 3 are modifying certain rules bundled with phpcs tool (
PSR* family of rules).
Those WordPress-specific rules are tailored to WordPress core in lots of places, and that creates an issue. Some great rules are excluded in
WordPress-Docs for example, and they are rather helpful: require a full stop
. at the end of the phpdoc
@param description, or the need to start that description with a capital letter. WordPress has in its source files some specific array descriptions, that violate those rules, and thus WP core contributors decided to exclude them. That’s the WP core use case, and it is helpful when you write the code for the WordPress core.
But here at WPForms, we have a bit different code style rules, and I decided to find a way how to change that behavior without removing the dependency of the
WordPress-Docs ruleset. I needed to include some of those excluded rules, like
Here’s how the inheritance looks:
WPForms > WordPress > WordPress-Docs > Squiz.*
Include PHPCS rules
It took me a while to understand, that when you
exclude certain rules, you are actually setting its
0. So checks are still run, they are just not displayed. You can read a bit more about
severity here in the Annotated Ruleset wiki article.
After looking at the phpcs parser of those
severity XML properties, I got the idea of how to include rules, that were excluded by WordPress Coding Standards (or any other standards):
<rule ref="Squiz.Commenting.FunctionComment.ParamCommentNotCapital"> <severity>5</severity> </rule>
You just raise the severity back to its default value (
5) in your own
ruleset.xml file. After that when you run
phpcs --standard=YourStandard .
the tool will start notifying you about code style violations, that were excluded in your parent ruleset, but re-enabled in your own ruleset.