PHP_CodeSniffer: one year in
Published on December 1, 2024 by jrf
Today marks the one year anniversary since I took on - and took over - as the maintainer of the PHP_CodeSniffer project.
As you may have noticed, this is the first newsletter to funders of this project as I generally prefer to let my code do the talking.
Still, I figured it might be a good idea to highlight to you what has been achieved over the past year and to show you that the funding you have provided to the PHP_CodeSniffer project has been put to good use.
Since I took over, I have released 11 new versions of PHP_CodeSniffer. We're currently at version 3.11.1, with the 3.11.2 release around the corner.
Those of you who have followed the project closely, will have noticed that a lot of the changes over the past year have focused largely on improving the end-user experience, which has the added benefit of reducing support requests.
Some of the most significant improvements from the past year:
As you may have noticed, this is the first newsletter to funders of this project as I generally prefer to let my code do the talking.
Still, I figured it might be a good idea to highlight to you what has been achieved over the past year and to show you that the funding you have provided to the PHP_CodeSniffer project has been put to good use.
Since I took over, I have released 11 new versions of PHP_CodeSniffer. We're currently at version 3.11.1, with the 3.11.2 release around the corner.
Those of you who have followed the project closely, will have noticed that a lot of the changes over the past year have focused largely on improving the end-user experience, which has the added benefit of reducing support requests.
Some of the most significant improvements from the past year:
- Runtime support for PHP 8.2, 8.3 and 8.4.
- Syntax support for PHP 8.2 and 8.3.
- Improved help screen.
- Improvements to the helpfulness of error messages.
- New feature to allow for deprecating sniffs with end-user notification, but without failing builds.
- Significant increase in the available sniff specific documentation.
- Improvements to the output of the sniff documentation display (`--generator`) option (ongoing).
- Continued efforts to reduce fixer conflicts.
- PHAR releases are now not only signed, but their provenance can now also be attested via the GitHub CLI tool.
- Three new sniffs (first ones since 2021).
- Performance improvements and a new Performance report to discover "slow" sniffs.
- Developer happiness: sniff tests can now run on PHPUnit 8 and 9, which also benefits various external standards.
Additionally, the following improvements are expected to land soon:
- Preventing "hiding one error behind another" when displaying error messages to the end-user (upcoming).
- New feature to allow for showing deprecations (and other hints and warnings) regarding a user's ruleset file (upcoming).
Aside from immediate improvements to the end-user experience, these changes are also intended to set us up for making the transition to PHP_CodeSniffer 4.0 - once available - a much smoother and more straight-forward experience for the users, as, in contrast to before, we'll now be able to signal most, if not all, upcoming changes to users in a way that allows them to get ready.
Some of the changes which were made have been slow going, as these needed to touch parts of the code base which weren't covered by tests and mostly only had minimal documentation of the intentions behind the code, which meant there was a high risk of breaking things.
To allow for safely making these changes, significant effort has been poured into improving and expanding the test suite and into safeguarding package stability by increasing the checks which are being run in CI.
Code coverage via tests has increased by over 10% in one year's time, which is a truly momentous effort for a code base with this much history.
These test improvements should allow for more rapid development in the future, as the chances of breaking things will be significantly reduced.
All of these changes are paving the way for PHP_CodeSniffer 4.0.
What's expected for PHP_CodeSniffer 4.0 ?
The PHP_CodeSniffer 4.0 release will largely focus on reducing technical debt and setting PHP_CodeSniffer up for the future.
As was mostly already announced before I took over, in PHP_CodeSniffer 4.0:
- Support will be dropped for PHP < 7.2.
- The default standard which will be used when none is provided, will change from PEAR to PSR12.
- Ruleset processing will change to read rules from top to bottom instead of in defined groups.
- Status, debug and progress information will be send to STDERR instead of STDOUT.
- Support for scanning JavaScript and CSS files will be dropped as there are much better, more language specific tools available nowadays for JavaScript and CSS.
- The MySource standard and all its sniffs will be removed.
- Previously deprecated features, like use of the old-style `@codingStandard` annotation syntax and the use of comma-separated strings to set a value for an array property via a ruleset, will be removed.
Additionally, various changes will be made which will also impact developers of external standards, like changes in how certain PHP constructs are tokenized and more strictly enforcing the expectations on sniffs in external standards.
Altogether, these changes will reduce technical debt even further and again, are intended to improve the end-user experience by reducing edge-case bugs and unexpected failures.
While I can't make any hard promises for the timeline of the 4.0 release, it will be the first priority for the project in 2025.
The PHP_CodeSniffer 4.0 release will know an RC period and I highly encourage maintainers of external standards and power-users to use this RC period to test the release.
The PHP_CodeSniffer 4.0 release will be accompanied by both an end-user upgrade guide, as well as a developer upgrade guide, to ease the transition. This is, of course, next to the user-focused changelog you've come to expect of PHP_CodeSniffer anyway.
Once PHP_CodeSniffer 4.0 has been released, attention will switch to focus on adding support for the new syntaxes which have been introduced in PHP 8.4.
The sheer amount and the complexity of these new PHP 8.4 syntaxes, means that it will take a huge amount of effort to bring support for these to a tokenizer based tool like PHP_CodeSniffer and your continued support will be needed to make this happen.
Other things of note
- Work has started on creating a PERCS package, which will hold an external PHP_CodeSniffer standard for each tagged release of the PER Coding Standards. This work is currently being spearheaded by three volunteers with guidance by me.
- With the story of the abandonment of PHP_CodeSniffer last year as an example, I've been trying to kick start conversations about succession management in open source software and the need for structural funding of maintainers by speaking at various conferences.
In total, I've spoken at 6 conferences this year, with a seventh, SymfonyCon, still coming up later this week.
If you are involved with a conference and would like me to speak, feel free to reach out.
Here are some links to videos of these talks:- Resurrecting the Dead
- Sustainable Open Source is the Future (together with the amazing Joost de Valk).
- The Composer Installer plugin for PHP_CodeSniffer crossed the 100 million downloads threshold earlier this year.
- PHPCompatibility `develop` can detect nearly all deprecations which were added in PHP 8.4.
Unfortunately, the work on the main PHP_CodeSniffer package has meant that I haven't been able to spend enough time on PHPCompatibility to get it to the next stable release yet, but that will hopefully change at some point.
Community
While the work on PHP_CodeSniffer is nearly a full-time job for me by now, I didn't do all of this alone and I would like to thank the following people for their contributions in making this happen (in alphabetic order): Michał Bundyra, Remi Collet, Tim Düsterhus, Bartosz Dziewoński, Przemek Hernik, Lucas Hoffmann, Brad Jorsch, Ferdinand Kuhl, Jay McPartland, Joachim Noreiko, João Pedro Oliveira, Rodrigo Primo, Klaus Purer, Bill Ruddock, Danny van der Sluijs, Marek Štípek, Alexander Turek, Dan Wallis, Denis Žoljom.
If I look at the community interaction with the new repository, I get the feeling that there are still lots of people unaware of the change of repository and management, but I also see people slowly finding their way to the new repository.
One initiative of note to get the community around PHP_CodeSniffer more involved, as well as to recognize the importance of external standards and integrations to the PHP_CodeSniffer eco-system, is the introduction of a "Community cc list".
This list allows for maintainers of external standards and integrators to be pinged for their opinion on, and to increase awareness about, (breaking) change proposals which may impact them, without them having to watch all activity in the repo.
This list is open to all and anyone interested can add or remove themselves from this list via a PR.
Significant effort has also been put into expanding the CONTRIBUTING guide to make it more straight-forward for new and existing contributors to get started and to increase the likelihood of their contribution(s) being accepted.
The project can definitely still use more contributors. The issue list contains numerous tasks looking for people to pick them up, like creating a website for the project, which would be a great next step in the user-focused improvements.
No project is an island
PHP_CodeSniffer is part of a larger landscape of PHP code quality projects and is deeply embedded in the PHP ecosphere. This has recently been recognized by the PHP project itself, with PHP_CodeSniffer being one of only 7 projects which are now formally allowed for all purpose use in the PHP Project.
As part of my role as leadership of the PHP_CodeSniffer project, I have also been interacting with the PHP project itself, with Phive, PHPStan, Composer, PHPUnit and other projects.
- I spoke up about the impact the PHP 8.4 property hook feature will have on tokenizer-based projects on PHP Internals. My analysis of the shortcomings of and problems with the proposal, unfortunately, had little effect.
- I discovered an undocumented tokenizer change in PHP 8.3. This change has now been documented in the PHP project, but is an awkward change all the same and the discussion regarding the discovery may yet lead to further changes in PHP itself.
Support for this change was added to PHP_CodeSniffer in the 3.11.0 release. - Both other contributors, as well as I myself, have interacted on numerous occasions with the FIG PER CS project to either suggest further improvements to the standard and/or ask for clarifications of the existing standards.
- Lastly, I have contributed numerous essential fixes to other projects which are used by the packages in the PHPCSStandards organization. These fixes end up benefitting the whole PHP community.
Let's make it a great 2025!
Recent attacks on open source, like the XZ-Utils debacle, highlight the importance of continued maintenance of open source projects, being able to trust maintainers and being mindful with opening up a project to a wider pool of maintainers, no matter how high the need.
A tool like PHP_CodeSniffer which literally rewrites code in hundred thousands of other projects is typically a tool which needs a high awareness of the attack surface it presents.
I feel privileged to have your support and trust to allow me to fulfill this role for PHP_CodeSniffer.
Recent developments such as the wider adoption of the Open Source Pledge give me hope that we may finally reach an era where funding of open source is normalized as the responsible, good business practice, which it is. But I also fear we still have a long way to go.
So, I'd like to encourage all of you to proudly show off the example you are setting by funding PHP_CodeSniffer and to challenge other companies to follow in your footsteps. And not just by funding PHP_CodeSniffer, but by supporting all open source projects which your - and their - business rely on.
I thank you again for your support for PHP_CodeSniffer and I wish you all happy holidays and a productive and open 2025!
Smile,
Juliette Reinders Folmer
https://github.com/jrfnl
https://github.com/PHPCSStandards
https://github.com/PHPCompatibility
https://opencollective.com/php_codesniffer
Follow the project on @phpcs on Mastodon or @PHP_CodeSniffer on X or watch releases on GitHub to stay up to date.