Skip to content

Declare the purity of every method for PHPStan - #143

Open
gnutix wants to merge 1 commit into
brick:mainfrom
gnutix:phpstan-purity-annotations
Open

gnutix wants to merge 1 commit into
brick:mainfrom
gnutix:phpstan-purity-annotations

Conversation

@gnutix

@gnutix gnutix commented Oct 30, 2026

Copy link
Copy Markdown
Contributor

Every method of the library now tells PHPStan whether it is pure, so that PHPStan can catch a discarded result, in the library and in its users' code:

$date->plusDays(1); // Call to method LocalDate::plusDays() on a separate line has no effect.

Change

  • Immutable classes and enums are tagged @phpstan-all-methods-pure, with @phpstan-impure only on the methods that:
    • read the clock: now(), isFuture(), isPast();
    • consume a DateTimeParseResult: from(), as getField() shifts the values off the result;
    • return a generator: getIterator() on the ranges.
  • The mutable classes tag each method: getters are pure, mutators and clock reads impure. That covers the clocks, Stopwatch, DefaultClock, DateTimeParseResult and PatternParserBuilder. Clock::getTime() is impure, while FixedClock::getTime() is pure.
  • The Field\*::check() validators are @phpstan-pure. PHPStan accepts that on a void method that declares @throws.

Some methods are pure as far as their callers can tell, though PHPStan cannot see it. The errors that shows are ignored in phpstan.neon, each with the reason:

  • a static variable memoizing a constant (Duration::zero(), IsoParsers::localDate()…);
  • parse() handing from() the result it has just created;
  • TimeZoneOffset::getId() caching the ID it computes;
  • IsoParsers and PatternParser::parse() mutating a builder or result they created on the spot (the latter, and ZonedDateTime::toNativeDateTime(), as inline ignores);
  • natives PHPStan has no purity data for: preg_match(), assert(), DateTime*, DateInterval, DatePeriod;
  • calls to the check() validators, which PHPStan counts as impure because they return void, although it accepts them as pure.

Tooling

  • PHPStan goes from 2.1.42 to 2.3.4. Before 2.3, @phpstan-all-methods-pure was ignored for callers of a method without a doc comment of its own, so $instant->getNano() still looked possibly impure.
  • PHPStan now analyses for PHP 8.2 to 8.6 (phpVersion range) instead of the PHP running it. Otherwise 2.3.4 reports the assert() in Period::toNativeDateInterval() as always true, since DateInterval::createFromDateString() only stopped returning false in PHP 8.3.

No CHANGELOG entry; I'll leave the wording to you.

A follow-up PR adds a PHPStan rule that keeps these tags from going missing on new methods (its --fix produced the per-method tags here).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y1vvcUHV6d9eTuxE4GW5MX

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
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