Skip to content

v2.0.0: build every set on PER Coding Style 3.0 and easy-coding-standard 13 - #41

Merged
rugbymauri merged 12 commits into
mainfrom
feat/ecs-13
Nov 16, 2026
Merged

rugbymauri merged 12 commits into
mainfrom
feat/ecs-13

Conversation

@rugbymauri

@rugbymauri rugbymauri commented Sep 7, 2026 •

Copy link
Copy Markdown
Collaborator

refs: #36

Summary

This branch becomes v2.0.0 of the whatwedo coding standard. Two changes make it a major:
the base standard moves from PSR-12 to PER Coding Style 3.0, and symplify/easy-coding-standard
goes from 12 to 13
(bundling php-cs-fixer 3.95.24 and PHP_CodeSniffer 4.0.4). Both reformat code
that passed under v1, so the first run in a consuming project produces a large diff.

Alongside that, the shipped sets move to ECS's fluent config format and can now be referenced
through WhatwedoSets class constants instead of a vendor path, ten overrides that held back rules
of the sets are gone, and seven rules leave the standard — two of them because they were defective.

Rule balance

v1.3.2 v2.0.0 Δ
Active rules 107 175 +68
Skipped rules 32 3 −29
ECS sets used 3 2 (+1 internal) −1
ECS version 12.6.2 ^13 major

The +68 has two separate causes, isolated by measuring three configs with the same command:

Measurement Active rules
v1.3.2 config on ECS 12.6.2 107
the same, unchanged config on ECS 13 162
this branch's config on ECS 13 175

So the dependency update alone accounts for +60/−5, and the config changes in this branch
for +20/−7. The old config still loads under ECS 13, which is what makes the split measurable
rather than guessed.

Breaking changes

  • PSR-12 → PER-CS 3.0 as the base of every set. 43 of the 48 PSR-12 rules are identical in
    PER-CS, 3 more come from COMMON. The single rule PER-CS does not cover,
    DeclareParenthesesFixer, is registered explicitly in the common set so the switch does not
    lose it. VisibilityRequiredFixer disappears — it is a @deprecated proxy onto
    ModifierKeywordsFixer, which PER-CS brings with the same default (const, method, property).
  • ECS 12 → 13. The refreshed sets report additional findings on code that passed before,
    above all through the ~20 new Symplify commenting fixers pulled in by DOCBLOCK and SPACES.
    Pipelines fail until vendor/bin/ecs check --fix has been run once.
  • Ten overrides that held back rules of the sets are gone — nine skips and one narrowing
    configuration. What that changes in checked code: casts are spaced ((int) $x), comparisons drop
    the Yoda order ($x === null, and an existing null === $x is rewritten), $i ++ becomes
    $i++, broken PHPDoc inline tags are normalised (@{TAG} to {@TAG}), @return null and
    @subpackage are dropped, a blank line follows the namespace statement, every call in a method
    chain is indented to one level, and every operator in a multiline expression moves to the beginning of the continuation line, where the
    previous only_booleans setting limited that to && and ||.

Most visible reformatting on the first run: trailing commas in multiline argument and parameter
lists (now also match and destructuring), fn() instead of fn (), ?int instead of ? int,
Foo::bar without spaces around ::, single-line empty bodies, chained-call indentation,
multiline operators at the beginning of the line, Yoda comparisons rewritten, a blank line after
namespace, and docblock cleanup.

Rules that leave the standard

Seven of the rules v1 registered are no longer active. Two of them were defective on a PHP 8.3+
code base, and both defects shipped in v1.3.2, which is why they are typed fix:.

Rule Why
NoNullableBooleanTypeFixer Defect. Risky fixer that rewrites ?bool to bool and leaves the body untouched, so ecs --fix turns working tri-state code into a TypeError on the next call with null. ECS has no --allow-risky gate anywhere in its source, so it cannot be tamed by configuration.
FileCommentSniff Defect. Hardcoded to Squiz Pty Ltd: rewrites @copyright 2026 whatwedo GmbH to @copyright 2026 Squiz Pty Ltd (ABN 77 084 670 600) and asks for @author Squiz Pty Ltd <products@squiz.net>. A file with a /** */ header also never converged — after --fix the sniff still reported MissingPackageTag, MissingSubpackageTag, PackageTagOrder and SpacingAfterOpen, none of them fixable.
FunctionCommentThrowTagSniff Sees one method body at a time, so the @throws tags it demands are incomplete and it misses the ones that matter. PHPStan answers the same question from the call chain.
ClassCommentSniff Registered with .Missing skipped, so it never asked for a class docblock — it only policed the shape of the ones that exist, which the sets cover for every other docblock.
PhpdocVarAnnotationCorrectOrderFixer Redundant: Symplify's SwitchedTypeAndNameFixer from the DOCBLOCK set already turns /** @var $cache array */ into /** @var array $cache */.
ForbiddenAnnotationsSniff Takes the annotations it rejects from a configured list whose default is empty, and it was registered without configuration — it never forbade anything.
VisibilityRequiredFixer @deprecated proxy onto ModifierKeywordsFixer, which PER-CS brings with the same default.

Three skips remain, all of them deliberate style decisions rather than workarounds:
IsNullFixer, NotOperatorWithSuccessorSpaceFixer and PhpdocNoAliasTagFixer, plus
ValidClassNameSniff restricted to **/whatwedo*.php.

What does not break

  • Consumers keep their ecs.php. Both sets([<path>]) in the old callable format and
    withSets([<path>]) in the fluent format load the new set files; verified against a probe
    project with each style. WhatwedoSets is an addition, not a replacement.
  • php: >=7.4 stays. ECS 13.3.2 itself only requires php >=7.2, and both custom-fixer
    packages allow ^7.4 || ^8.0.
  • Symfony projects keep $a.$b. The ConcatSpaceFixer override with spacing: none is
    deliberate — the Symfony coding standard concatenates without spaces where the ECS sets use one —
    and now carries a comment saying so, so it does not get "cleaned up" next time.
  • Imports stay alphabetical. The PER_CS set sets sort_algorithm: none because PER-CS leaves
    import order open; the common set pins it back to alpha, which the whatwedo standard has always
    used.
  • @template and @implements are safe. ClassCommentSniff.TagNotAllowed warns on every tag
    it sees, but that code proved unreachable in the shipped combination — and the sniff is gone now
    anyway.

For reviewers — commit by commit

Thirteen commits, each of which passes vendor/bin/ecs check on its own (verified per commit, not
only at the tip).

Commit What to look at
style(fixer): align dump fixer file header… The standard strips @author, so the upstream attribution moves into the docblock text.
chore(deps)!: update to symplify/easy-coding-standard ^13 The version caps ECS 12 needed on kubawerlos/php-cs-fixer-custom-fixers and slevomat/coding-standard are lifted.
docs(readme): rework the install and usage section --dev install, the set to reference per project type, ecs.php in the fluent format.
refactor(config): move the shipped sets to the ECS fluent config format Behaviour-neutral: 162 active rules before and after. Drops CLEAN_CODE (imported by COMMON in full) and 17 skips that targeted rules no ECS 13 set ships any more.
feat(config): reference the shipped sets through WhatwedoSets constants New whatwedo\PhpCodingStandard\Set\WhatwedoSets with COMMON, SYMFONY, WORDPRESS and the internal RULES.
feat(config)!: build every set on PER-CS 3.0 instead of PSR-12 The headline change; splits the own rules into config/whatwedo-rules.php, loaded last so they win over the base set.
docs: declare the paths to check in ecs.php __DIR__-relative paths, so vendor/bin/ecs check needs no directory argument.
feat(config)!: let the sets apply the rules we had suppressed The ten dropped overrides. Two said nothing to begin with: the NoExtraBlankLinesFixer skip had no effect (PER_CS narrows that fixer to blank lines between imports, which NoBlankLineBetweenImportsFixer already removes), and the position set next to only_booleans was the php-cs-fixer default.
refactor(config): drop the registrations that have no effect Three no-ops: AssignmentInConditionSniff registered and skipped in the same file, the redundant @var order fixer, the unconfigured forbidden-annotations sniff. Results unchanged.
fix(config): keep enum cases at the top of the enum The configured element order for OrderedClassElementsFixer never listed case, and every type the list omits is sorted to the end — so --fix moved the cases of a correct enum below its methods. Fixed by dropping the own order entirely rather than patching it: PER_CS configures the fixer as order => ['use_trait'], which sorts trait imports up and leaves the rest of the class alone. The cost: the order of properties, constants and methods is no longer enforced.
fix(config): keep the nullability of bool types The ?bool → bool TypeError, see the table above.
fix(config): keep the copyright of the file header The Squiz copyright rewrite and the non-convergence, see the table above.
feat(config): leave the docblock checks to phpstan and the sets Drops the two Squiz commenting sniffs (@throws, class docblock style).

Ordering note: the ECSConfigBuilder always processes sets → paths → skip → rules →
rulesWithConfiguration, regardless of call order in the file. Own rules therefore always win over
the sets, and skips apply wherever they stand.

Open points

  • LanguageConstructSpacingSniff does not show up as active in the shipped set combination even
    though SpacesLevel references it (PHPCS 4 moved it from Squiz to Generic). Worth a check if
    we want the rule.
  • config/whatwedo-rules.php and WhatwedoSets::RULES exist to run one rule list on two base sets.
    With PER-CS as the only base, the split has lost its purpose and could be folded back into
    whatwedo-common.php.
  • NoImportFromGlobalNamespaceFixer stays, so \DateTimeImmutable is written inline rather than
    imported. That is a style decision, not a necessity — flagging it because on PHP 8.3+ it also
    covers \Stringable, \JsonException and \SensitiveParameter.
  • The README rewrite dropped the previous "Without custom configuration" section and the skip()
    example. There is now no example for excluding rules or files — worth a follow-up if we want that
    back.
  • Before tagging: CHANGELOG.md's ## [Unreleased] becomes ## [2.0.0]. The releases v1.3.1
    and v1.3.2 are tagged but never made it into the changelog.

How the numbers were produced

  1. composer.json from 681fe9a in a separate directory, composer update (resolves ECS 12.6.2),
    then vendor/bin/ecs list-checkers with the common config of that tag.
  2. The same old config file, loaded with this branch's ECS 13 (ecs list --config).
  3. ecs list --config config/whatwedo-common.php on this branch.
  4. From each output only the active checkers (everything before "checkers are skipped"), deduplicated
    and compared with comm. Deduplication matters: ecs list prints one line per registration, and
    23 classes are registered by more than one set (OrderedImportsFixer four times, ArraySyntaxFixer
    three), so at the tip the raw line count is 200 against 175 distinct rules.
  5. Rule configurations read via reflection over ECSConfig::$checkerConfiguration, since
    ecs list only prints class names.

@rugbymauri rugbymauri self-assigned this Sep 7, 2026
@rugbymauri rugbymauri changed the title Der whatwedo-Standard läuft auf symplify/easy-coding-standard 13 Run the whatwedo standard on symplify/easy-coding-standard 13 Sep 7, 2026
@rugbymauri
rugbymauri force-pushed the feat/ecs-13 branch 3 times, most recently from ec70d32 to df6ebb1 Compare September 9, 2026 12:02
@rugbymauri rugbymauri changed the title Run the whatwedo standard on symplify/easy-coding-standard 13 v2.0.0: build every set on PER Coding Style 3.0 and easy-coding-standard 13 Sep 9, 2026
@rugbymauri
rugbymauri force-pushed the feat/ecs-13 branch 4 times, most recently from e8f5c69 to 7907aa8 Compare September 9, 2026 15:07
Comment thread config/whatwedo-common.php Resolved

@tuxes3 tuxes3 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

der ecs check sollte im ci auf sich selber laufen.


MethodChainingNewlineFixer ist eine grosse Änderung, ist aber nicht dokumentiert.

Comment thread config/whatwedo-common.php Resolved
Comment thread src/Fixer/DumpFixer.php Resolved
Comment thread composer.json Resolved
Comment thread composer.json Resolved
Comment thread CHANGELOG.md Resolved

@tuxes3 tuxes3 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rugbymauri change the version pin in composer.json and we ready to merge

Comment thread composer.json Resolved
Comment thread CHANGELOG.md Resolved
The upstream attribution now lives in the class docblock text instead of an
`@author` annotation, which the standard strips on `--fix`.

Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
ECS 13 bundles php-cs-fixer 3.95 and PHP_CodeSniffer 4, which lifts the version
caps on kubawerlos/php-cs-fixer-custom-fixers and slevomat/coding-standard again.

BREAKING CHANGE: after updating, run `vendor/bin/ecs check --fix` once — the
refreshed rule set reports additional findings on code that passed under ECS 12,
so pipelines fail until the new findings are fixed.

refs: #36
Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
Install with `--dev`, since a coding standard is never needed at runtime, and pick
the Symfony, WordPress or common set from a single list, shown as the `ecs.php`
fluent config format ECS expects.

refs: #36
Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
ECS 13 deprecates the `return function (ECSConfig $ecsConfig): void {}` format the
sets used and warns on every run; consumers may keep either style. The move also
drops `SetList::CLEAN_CODE`, already imported by `SetList::COMMON` in full, and 17
skips for rules no ECS 13 set ships any more — the effective checker list stays at
162 active rules, verified with `ecs list` on every config.

Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
`WhatwedoSets::COMMON`, `::SYMFONY` and `::WORDPRESS` carry the paths to the shipped
sets, so an `ecs.php` names a class constant instead of a vendor path that breaks
silently on a rename; passing the file path keeps working. Both examples now declare
the directories to check as `__DIR__`-relative paths, so `vendor/bin/ecs check` needs
no directory argument and works from any working directory.

refs: #36
Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
PER Coding Style 3.0 is the successor of PSR-12, so every set now builds on
`SetList::PER_CS` plus the two points it leaves to the caller, `declare()`
parentheses and alphabetically sorted imports. The whatwedo rules move into one
file loaded last, where they give up the ten overrides that held back rules the
sets ship and every sniff and fixer that rewrote correct code: the Squiz file and
class comment sniffs, the `@throws` sniff PHPStan answers from the call chain, the
risky `?bool` fixer, and the class element order that moved enum cases below the
methods.

BREAKING CHANGE: run `vendor/bin/ecs check --fix` once after the update — the first
run reformats existing code, most visibly by adding trailing commas to multiline
argument and parameter lists, spacing casts and rewriting Yoda comparisons. The
order of properties, constants and methods is no longer enforced.

refs: #36
Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
`^13` also resolves the earlier 13.x patches, on which the shipped sets are neither
developed nor run. Requiring the current 13.3.2 as the minimum keeps a fresh install
on the same php-cs-fixer and PHP_CodeSniffer versions the sets are verified against,
instead of silently landing on an older 13.0 or 13.1 patch.

The `>=7.4` floor outlived the versions it was written for in the same way: every
whatwedo project that consumes this standard runs on PHP 8.2 or newer, and the sets
are neither run nor verified on anything older. The dependencies would still install
on 7.4, so the floor is set here on purpose rather than inherited.

BREAKING CHANGE: a project on PHP 7.4, 8.0 or 8.1 no longer resolves this package and
stays on the previous release.

refs: #36
Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
A fluent chain is no longer split onto one call per line and re-indented, so a short
`$this->foo()->bar()` stays on one line and a deliberately wrapped builder chain keeps
its own breaks.

refs: #36
Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
The Symfony set now normalises the indentation, spacing and array assignments inside
Doctrine annotations, which until now were left untouched in projects that still carry
mapping or validation in docblocks rather than attributes.

BREAKING CHANGE: run `vendor/bin/ecs check --fix` once after the update — the first run
reformats existing Doctrine annotations.

refs: #36
Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
Allow only patch updates of slevomat/coding-standard, kubawerlos/php-cs-fixer-custom-fixers and symplify/easy-coding-standard so a new upstream minor release cannot change the formatting result without a release of this package.

Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>
Run `make ecs` on pushes to main and on pull requests and fail the build when ECS would change a file.

Signed-off-by: Maurizio Monticelli <maurizio@whatwedo.ch>

@tuxes3 tuxes3 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rugbymauri ok...

Ich Persönlich bin der Meinung wir sollten ~ verwenden. Wir hatten schon Probleme damit, siehe zB diesen commit: 3b1a66f

Man kann es aber einfach im Projekt blockieren, somit ok. Aber überleg es dir doch nochmals 👍

@rugbymauri
rugbymauri merged commit cb02c89 into main Nov 16, 2026
2 checks passed
@rugbymauri
rugbymauri deleted the feat/ecs-13 branch November 16, 2026 09:17
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