Skip to content

Add a PHPStan rule requiring methods to declare their purity - #144

Open
gnutix wants to merge 2 commits into
brick:mainfrom
gnutix:phpstan-purity-rule
Open

gnutix wants to merge 2 commits into
brick:mainfrom
gnutix:phpstan-purity-rule

Conversation

@gnutix

@gnutix gnutix commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Builds on #143: merge it first. This PR couldn't be stacked on #143, as its branch lives on my fork and a PR here can only target a branch of this repository. So #143's commit is included, and only the last commit is new: 99b278c.

A PHPStan rule that makes every new method declare its purity, so the tags from #143 do not erode.

Rule

MethodPurityRule reports any method PHPStan considers of unknown purity, if it is:

  • public;
  • or a constructor, whatever its visibility. A static factory calling a private constructor is only as pure as it is, so Duration::ofSeconds() cannot be decided while new Duration() is not.

A method satisfies it with @phpstan-pure or @phpstan-impure, or through @phpstan-all-methods-pure/-impure on its class. A void method in a pure class still needs its own tag, as PHPStan does not apply the class tag to it.

AbstractMethodPurityRule does the same for abstract and interface methods, which PHPStan reports through another node.

--fix

phpstan analyse --fix adds the missing tag, inferred from the side effects PHPStan finds in the method body:

  • a certain side effect: @phpstan-impure;
  • none: @phpstan-pure, unless the method returns void without declaring an exception;
  • only possible ones, such as a call to an untagged method: no fix. Running --fix again once the callees are tagged resolves most of those; the rest need a human.

The tag goes at the end of the doc comment, grouped and spaced the way the coding standard wants it. Run from main, --fix converges in 7 runs over about 600 methods, and ECS accepts the result.

The inference is literal, so its output is a starting point rather than the answer. Left alone on main, it makes LocalDate::of() impure because of a memoized static variable further down. #143 starts from it, then uses class-level tags and documented ignores where the literal answer is wrong.

Notes

  • MethodReturnStatementsNode has the side effects, but it keeps the method node that fixNode() needs in a private property. The rule reads that property through reflection. A PHPStan upgrade that renames it will fail loudly.
  • tools/phpstan/src is analysed too. It gets level 10, and it keeps the result cache from going stale when the rules change. The purity rules are ignored there.
  • ECS checks tools/phpstan/src.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y1vvcUHV6d9eTuxE4GW5MX

gnutix and others added 2 commits October 30, 2026 08:15
Immutable classes and enums are tagged @phpstan-all-methods-pure, with
@phpstan-impure on the methods that read the clock (now(), isFuture(),
isPast()), consume a DateTimeParseResult (from()) or return a generator
(getIterator()). The mutable classes (the clocks, Stopwatch,
DefaultClock, DateTimeParseResult, PatternParserBuilder) tag each
method.

This lets PHPStan report a discarded result, such as
`$date->plusDays(1);` on its own line, in the library and in its users'
code.

PHPStan is upgraded to 2.3.4, as earlier versions ignore
@phpstan-all-methods-pure on a method without a doc comment. It now
analyses for the PHP versions the library supports, where
DateInterval::createFromDateString() can still return false.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y1vvcUHV6d9eTuxE4GW5MX
Every public method, and every constructor whatever its visibility,
must be tagged @phpstan-pure or @phpstan-impure, or belong to a class
tagged @phpstan-all-methods-pure or @phpstan-all-methods-impure.

With --fix, the rule infers the missing tag from the side effects
PHPStan finds in the method body, and leaves the methods that call
something of unknown purity to another run or to a human. Abstract
methods have no body to infer it from, so they are reported without a
fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y1vvcUHV6d9eTuxE4GW5MX
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.

1 participant