WordPressCS 3.0.0 is now available

A wapuu in a dark grey hoodie using a silver coloured laptop with the WordPress logo on the laptop cover.
Image credits: Marktimemedia

This post announces the immediate availability of the long-awaited WordPressCS 3.0.0 release.

This is an important release which makes significant changes to improve the accuracy, performance, stability and maintainability of all sniffssniff A module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food., as well as makes WordPressCS much better at handling modern PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher.

Most rules which were proposed in the Make post from March 2020 have been added to the Coding standards guidelines.
Proposed rules which yielded a lot of discussion or to which objections were raised, have not been added.
The intention is to publish separate Make posts for each of these over time, to discuss these more controversial proposals further.

For a large number of the new rules, sniffs have been added to WordPressCS to enforce these rules.
More sniffs may be added in future WordPressCS releases to comprehensively cover the new and updated rules.

New architecture

WordPressCS previously had only one runtime dependency, which was PHP_CodeSniffer and end-users would need to manually register WordPressCS with PHP_CodeSniffer (or use a Composer pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party to do so).

As of WordPressCS 3.0.0, WordPressCS will have four run-time dependencies and because of this, Composer will be the only supported way to install WordPressCS.

Mind: it is still perfectly possible to install WordPressCS and its dependencies without using Composer. It is just not an installation method for which support will be provided.

The image shows the new architecture of WordPressCS 3.0.0.

Everything is build on top of PHP_CodeSniffer - which comes with the Generic, PEAR, PSR1, PSR2, PSR12, Squiz, and Zend standards.

On top of PHP_CodeSniffer, there is the PHPCSUtils package.

And then there are the WordPressCS and PHPCSExtra packages which both  are build on top of PHPCSUtils.

WordPressCS comes with the WordPress, WordPress-Core, WordPress-Extra and WordPress-Docs rulesets.

PHPCSExtra comes with the Universal, NormalizedArrays and Modernizer rulesets.

To the side of this stack, it shows another package: the Composer PHPCS Plugin.
This package makes sure that all external standards are automatically and correctly registered with PHP_CodeSniffer.

PHPCSUtils is a set of utility functions for use with PHP_CodeSniffer.
PHPCSExtra is an additional set of sniffs.
Composer Installer is a Composer plugin which will make sure that WordPressCS, PHPCSUtils as well as PHPCSExtra will be registered correctly with PHP_CodeSniffer.

New, non-WordPress-specific, sniffs will now be added to PHPCSExtra, while all WordPress-specific sniffs continue to be maintained in WordPressCS.
Some of the pre-existing WordPressCS sniffs, which could benefit the wider PHP community, have been removed and replaced by similar (and improved!) sniffs which were added to PHPCSExtra.

Upgrading to WordPressCS 3.0.0

WordPressCS 3.0.0 contains breaking changes, both for people using ignore annotations, people maintaining custom rulesets, as well as for sniffsniff A module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food. developers who maintain a custom PHPCSPHP Code Sniffer PHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS. standard based on WordPressCS.

Aside from the changelog, WordPressCS 3.0.0 comes with detailed upgrade guides for both end-users/ruleset maintainers as well as a separate upgrade guide for developers who have built a coding standard on top of WordPressCS.

Please read the provided documentation carefully before you upgrade.

WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. will upgrade to WordPressCS 3.0.0 in the near future as well. Follow TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. #59161 if you want to stay informed and be sure to run composer update --with-all-dependencies once the patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. has been committed to benefit from the latest & greatest sniff goodies.

Why did it take so long for this release to be “ready” ?

This release is basically the result of four big projects combined. It wasn’t necessarily the intention when work on WordPressCS 3.0.0 started that these projects would be combined into one release, but internal and external influences had an impact on timing, which made it so.

Also, please keep in mind that this project is basically maintained by a very, very small group of unpaid volunteers, who also have real jobs to do.

The four big projects we are talking about are:

  1. A big refactor.
  2. Adding new rules based on the Make post from March 2020.
  3. Making the sniffs compatible with PHP 7.4, 8.0, 8.1 and 8.2 (* 8.2 in so far currently possible as PHP_CodeSniffer doesn’t fully support all 8.2 syntaxes yet).
  4. Improving the available documentation.

Now let’s talk a little about each of these.

The refactor

WordPressCS previously had only one runtime dependency, which was PHP_CodeSniffer and end-users would need to manually register WordPressCS with PHP_CodeSniffer (or use a Composer plugin to do so).
PHP_CodeSniffer offers some limited “utility” functions for sniffs and some basic abstracts.

But… WordPressCS – and other external standards, like PHPCompatibility – wanted more utility functions and better abstracts to be available, so these projects added their own and these utilities then had to be maintained in each of those projects.

To improve this situation, it was originally proposed for the non-standard specific utilities to be added to PHP_CodeSniffer. After nearly a year of work on this, lots of discussion and waiting, it was eventually decided in the summer of 2019 that these utilities should live in a separate project.

Moving this work to a separate project was a setback and meant having to rework a lot.
This separate project was published as PHPCSUtils in January 2020.

By that time, PHP 8.0 also started to come into play and it was becoming very clear that this would involve lots of changes for Coding Standards projects and both PHP_CodeSniffer, as well as the utilities, would have to be made compatible with PHP 8.0 before a new version of WordPressCS could be released.

In practical terms, most non-WordPress-specific utility functions are now available via PHPCSUtils.
The remaining utility functions, i.e. the few exceptions + the WordPress-specific utilities, have all been moved to separate “helper” classes and traits to make the code more re-usable for sniffs not based on the WordPressCS specific base Sniff class.

New rules

The Make post from March 2020 proposed a lot of new rules, which resulted in a healthy discussion on the post and save for a few rules, most of the new rules met with approval.

This meant two things:

  1. Research needed to be done whether there were any pre-existing sniffs that could be used to implement the approved rules.
  2. For anything for which no sniff existed, a new sniff would need to be written.

A whopping 35 new sniffs were written for this release, 32 of these were added to PHPCSExtra, and 3 to WordPressCS itself.

To see a list of all the rules included in a particular standard, use:

vendor/bin/phpcs -e --standard=WordPress

(you can replace WordPress with, for instance, WordPress-Core or Universal or PSR12 to see the sniffs included in a particular standard)

Making sniffs compatible with PHP 7.4, 8.0, 8.1 (and 8.2)

Making a PHP project compatible with a new PHP version is one thing, doing so for a static analysis tool is something else altogether.

Making sniffs compatible with a new PHP version, basically involves three things:

  1. Making sure the existing code will run on the new PHP version without errors or notices.
  2. Making sure that sniffs do not throw a false positive/negative when confronted with a new syntax.
    Example: if a sniff looks for function calls to analyse and excludes method calls – function calls preceded by a -> or :: -, for PHP 8.0, these sniffs needed to be adjusted to also exclude function calls preceded by the nullsafe object operator ?->.
  3. Add explicit support for new PHP features.
    Example: if a sniff would examine the name of a class-like structure, like a class, interface, or trait, the sniff would probably benefit from new code to also examine the names of PHP 8.1 enum structures.

Now, aside from 1, for 2 and 3, WordPressCS has a BIG dependency on PHP_CodeSniffer itself as PHP_CodeSniffer needs to support the new syntaxes first before an individual sniff can start to support them.

At the time work started for WordPressCS 3.0.0, PHP_CodeSniffer didn’t fully support PHP 7.4 yet, which added quite some new syntaxes and then PHP 8.0, 8.1 and 8.2 came along adding yet even more.

PHP 7.4, 8.0, 8.1, 8.2 added more new syntaxes to PHP than all of the PHP 5 and 7 releases before it combined.

Now you may ask yourself: “Why should the sniffs take all those new PHP syntaxes into account ?” After all, WordPress still supports PHP 7.0 (PHP 5.6 prior to WP 6.3), so those syntaxes cannot be used in code written for WordPress Core…

Well, the WordPress Coding StandardsWordPress Coding Standards The Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook. May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP coding standards. are a community standard and WordPressCS codifies this into automated checks and as such, WordPressCS is not only used by WordPress Core, but also by the wider WordPress community, including agencies, plugin and theme authors etc.
And plugins and themes may have a higher minimum supported PHP version, especially when we’re talking in-company/closed source plugins and themes.

Aside from that, sooner or later, WP will raise the minimum supported PHP version to a version including these new syntaxes, so the work would need to be done anyway and it’s easier to do this when what’s changed in PHP is still fresh in our minds.

So, a new waiting game started, where PHPCS needed to be updated first, then PHPCSUtils and only then could support for the new syntaxes be added to WordPressCS.

Safe for the PHP 8.2 Disjunctive Normal Form Types, which isn’t supported yet by PHP_CodeSniffer itself, all new syntaxes which were introduced in recent PHP versions are now taken into account in all sniffs in as far as our (my) imagination reached.

If you run into a situation where a sniff appears to not be fully compatible with modern PHP syntaxes yet, please open a bug report.

Improving the documentation

PHPCS has a built-in sniff documentation feature. Until recently, WordPressCS didn’t really support this feature and WordPress sniffs didn’t provide the documentation needed.

A start was made to add documentation to sniffs during the contributor dayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. at WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Europe 2019.

This effort has continued during the WordPressCS 3.0.0 cycle and the majority of sniffs used by and provided by WordPressCS now include documentation with code samples of what a sniff expects.

To view the documentation for any of the included standards use:

vendor/bin/phpcs --generator=Text --standard=WordPress

(you can replace WordPress with, for instance, WordPress-Core or Universal or PSR12 to see the documentation for other standards)

The future of WordPressCS

While WordPressCS is currently in a good place with this release, this won’t last long with the pace at which PHP is going.

WordPressCS 3.0.0 has costs thousands of hours of work and the vast majority of work has been done by one, mostly unpaid, contributor, with code review support from two fellow maintainers.

If we are being realistic, the bus factor of WordPressCS is 1, which is the most dangerous situation for any project to be in.

A large part of the WordPress community, including WordPress Core, relies heavily on the WordPress Coding Standards for code quality and security checks and while the community has been pretty vocal with copious complaints about the delayed release, barely anyone has stepped up and actually contributed.

The majority of the work for WordPressCS requires specialized knowledge. Knowledge which can be learned with enough time investment, but in recent years nobody has stepped up to do so.

This is an unsustainable situation and it ends now.

Unless funding is found to continue maintaining WordPressCS and its dependencies, the future is bleak and maintenance will be halted.

Let this be a call to action for the corporate/agency users of WordPressCS to come together and figure out a way to fund the continued maintenance and development of WordPressCS as that one person on which the whole project, including all dependencies, leans, is done with the current status quo.

If you want to help change this situation, please reach out to the WordPressCS maintainer team (@jrf, @GaryJ, @dingo_d) via WordPress SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. to discuss.

Props to @GaryJ, @dingo_d and @milana_cap for reviewing the post before publication.

#modernizewp, #codingstandards, #php, #wpcs