Skip to content

Introduce PHP_CodeSniffer ruleset based on PSR12 #204

Merged
antecedent merged 2 commits intomasterfrom
feature/enforce-code-style-psr12
Mar 30, 2026
Merged

Introduce PHP_CodeSniffer ruleset based on PSR12 #204
antecedent merged 2 commits intomasterfrom
feature/enforce-code-style-psr12

Conversation

@jrfnl
Copy link
Copy Markdown
Collaborator

@jrfnl jrfnl commented Mar 30, 2026

Introduce PHP_CodeSniffer ruleset based on PSR12

Follow-up on PRs #200, #201, #202 and #203.

This commit introduces PHP_CodeSniffer (PHPCS) as the tooling to enforce code style consistency for the Patchwork codebase.

Notes:

  • As discussed in PHP 8.5 | Prevent some "Using null as an array offset" deprecation notices #180, the ruleset is based on PSR-12.
    At a later point in time, we may want to update that to PERCS (once available), but that's not that relevant for this codebase as the rule additions in PERCS are mostly related to new PHP syntax, which can't be used in this codebase at this time anyway due to the PHP 7.1 minimum.
  • Additionally, the PHPCompatibility package, an external ruleset for PHPCS, has been added at the 10.0.0-alpha2 release to detect PHP cross-version compatibility issues.
    While this is an alpha release, I'd still recommend using it over the last stable release as a) it's pretty damn stable anyway and b) it has much much more detection of issues than any previous release.
  • For PHPCS to recognize the external PHPCompatibility ruleset, the dealerdirect/phpcodesniffer-composer-installer composer plugin needs permission to run. This has been granted.

Ruleset specific notes:

  • At this time, only the .php files can be checked. .phpt files cannot be analyzed at this time by PHPCS. An issue is open about this upstream and if that ever gets addressed, we could consider scanning the .phpt test files too.
  • The test fixtures are explicitly excluded from the scans as those may contain code written in a non-compliant way explicitly to trigger a specific test situation and we don't want to limit the test fixtures in what can be tested.
  • There are two sniffs, both related to file organisation, which have been explicitly excluded.
    Whether or not this codebase should follow the "one class per file", PSR-4 and "no side-effects" rules is a different conversation and should be discussed separately. This should not block this PR, which is why I've excluded the rules for the time being.
    This is related to the work previously started in Clean class and function files as per PSR-4 #98.
  • Additionally, I've made some selective exclusions (= exclude a specific sniff for one specific file), where the changes PSR12 expects would lead to breaking changes otherwise.
    It could be considered to address these in a future major release, but making these changes at this time is incompatible with Semver.
  • I've also elected to make the line length rule a little more lenient.

Includes:

  • A GitHub Actions workflow job to enforce the code style on all pushes and pull requests.
    When the workflow runs for a pull request, code style violations will be shown in the PR code view via inline annotations using the cs2pr tool.
  • Some simple Composer scripts to make it straight-forward for contributors to know what CI checks are being run and how to run these locally.
  • Excluding the PHPCS ruleset file from being included in distribution archives.
  • Git-ignoring typical PHPCS ruleset overload files (which can be used by devs locally to try additional rules).

PHPCS: add some targetted inline ignore annotations

  • CallRerouting: I've verified that the issue flagged will not occur.
  • Namespaces: I've verified that the issue flagged will not occur.
  • RedefinitionOfNew: I've elected not to address the line length issue for this code snippet.

Note: I've verified that the CI job correctly fails when there are CS violations: https://github.com/antecedent/patchwork/actions/runs/23746720708/job/69177215774

jrfnl added 2 commits March 30, 2026 15:16
Follow-up on PRs 200, 201, 202 and 203.

This commit introduces [PHP_CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer) (PHPCS) as the tooling to enforce code style consistency for the Patchwork codebase.

Notes:
* As discussed in 180, the ruleset is based on [PSR-12](https://www.php-fig.org/psr/psr-12/).
    At a later point in time, we may want to update that to PERCS (once available), but that's not that relevant for this codebase as the rule additions in PERCS are mostly related to new PHP syntax, which can't be used in this codebase at this time anyway due to the PHP 7.1 minimum.
* Additionally, the [PHPCompatibility](https://github.com/PHPCompatibility/PHPCompatibility) package, an external ruleset for PHPCS, has been added at the 10.0.0-alpha2 release to detect PHP cross-version compatibility issues.
    While this is an alpha release, I'd still recommend using it over the last stable release as a) it's pretty damn stable anyway and b) it has much much more detection of issues than any previous release.
* For PHPCS to recognize the external PHPCompatibility ruleset, the `dealerdirect/phpcodesniffer-composer-installer` composer plugin needs permission to run. This has been granted.
* Also note that PHPCS is allowed at version 3 and 4. This is because v4 has a PHP 7.2 minimum (v3 PHP 5.4), which would otherwise impede running of our tests on PHP 7.1.

Ruleset specific notes:
* At this time, only the `.php` files can be checked. `.phpt` files cannot be analyzed at this time by PHPCS. An issue is open about this upstream and if that ever gets addressed, we could consider scanning the `.phpt` test files too.
* The test fixtures are explicitly excluded from the scans as those may contain code written in a non-compliant way explicitly to trigger a specific test situation and we don't want to limit the test fixtures in what can be tested.
* There are two sniffs, both related to file organisation, which have been explicitly excluded.
    Whether or not this codebase should follow the "one class per file", PSR-4 and "no side-effects" rules is a different conversation and should be discussed separately. This should not block this PR, which is why I've excluded the rules for the time being.
    This is related to the work previously started in 98.
* Additionally, I've made some selective exclusions (= exclude a specific sniff for one specific file), where the changes PSR12 expects would lead to breaking changes otherwise.
    It could be considered to address these in a future major release, but making these changes at this time is incompatible with Semver.
* I've also elected to make the line length rule a little more lenient.

Includes:
* A GitHub Actions workflow job to enforce the code style on all pushes and pull requests.
    When the workflow runs for a pull request, code style violations will be shown in the PR code view via inline annotations using the `cs2pr` tool.
* Some simple Composer scripts to make it straight-forward for contributors to know what CI checks are being run and how to run these locally.
* Excluding the PHPCS ruleset file from being included in distribution archives.
* Git-ignoring typical PHPCS ruleset overload files (which can be used by devs locally to try additional rules).

A
* `CallRerouting`: I've verified that the issue flagged will not occur.
* `Namespaces`: I've verified that the issue flagged will not occur.
* `RedefinitionOfNew`: I've elected not to address the line length issue for this code snippet.
@jrfnl jrfnl added this to the 2.2 Next milestone Mar 30, 2026
@antecedent antecedent merged commit 448f1a3 into master Mar 30, 2026
26 checks passed
@antecedent antecedent deleted the feature/enforce-code-style-psr12 branch March 30, 2026 18:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants