From d2a6b8f0648dd9e49a775df0e0ccc1520b6483d3 Mon Sep 17 00:00:00 2001 From: Dorian Villet Date: Fri, 30 Oct 2026 08:15:14 +0100 Subject: [PATCH 1/2] Declare the purity of every method for PHPStan 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 Claude-Session: https://claude.ai/code/session_01Y1vvcUHV6d9eTuxE4GW5MX --- src/Clock.php | 2 ++ src/Clock/FixedClock.php | 10 +++++++ src/Clock/OffsetClock.php | 2 ++ src/Clock/ScaleClock.php | 2 ++ src/DateTimeException.php | 2 ++ src/DayOfWeek.php | 4 +++ src/DefaultClock.php | 4 +++ src/Duration.php | 2 ++ src/Field/DayOfMonth.php | 4 +++ src/Field/DayOfWeek.php | 4 +++ src/Field/DayOfYear.php | 4 +++ src/Field/FractionOfSecond.php | 2 ++ src/Field/HourOfDay.php | 4 +++ src/Field/MinuteOfHour.php | 4 +++ src/Field/MonthOfYear.php | 4 +++ src/Field/NanoOfSecond.php | 4 +++ src/Field/SecondOfDay.php | 4 +++ src/Field/SecondOfMinute.php | 4 +++ src/Field/TimeZoneOffsetHour.php | 4 +++ src/Field/TimeZoneOffsetMinute.php | 4 +++ src/Field/TimeZoneOffsetSecond.php | 4 +++ src/Field/TimeZoneOffsetSign.php | 2 ++ src/Field/TimeZoneOffsetTotalSeconds.php | 4 +++ src/Field/TimeZoneRegion.php | 2 ++ src/Field/WeekOfYear.php | 4 +++ src/Field/Year.php | 4 +++ src/Instant.php | 9 ++++++ src/Interval.php | 2 ++ src/LocalDate.php | 6 ++++ src/LocalDateRange.php | 6 ++++ src/LocalDateTime.php | 10 +++++++ src/LocalTime.php | 6 ++++ src/Month.php | 2 ++ src/MonthDay.php | 6 ++++ src/Parser/DateTimeParseException.php | 2 ++ src/Parser/DateTimeParseResult.php | 9 ++++++ src/Parser/DateTimeParser.php | 2 ++ src/Parser/IsoParsers.php | 2 ++ src/Parser/PatternParser.php | 3 ++ src/Parser/PatternParserBuilder.php | 27 +++++++++++++++++ src/Period.php | 2 ++ src/Quarter.php | 4 +++ src/Stopwatch.php | 13 +++++++++ src/TimeZone.php | 2 ++ src/TimeZoneOffset.php | 4 +++ src/TimeZoneRegion.php | 4 +++ src/Utility/Math.php | 2 ++ src/Year.php | 6 ++++ src/YearMonth.php | 6 ++++ src/YearMonthRange.php | 6 ++++ src/YearWeek.php | 7 +++++ src/ZonedDateTime.php | 11 +++++++ tools/phpstan/composer.json | 2 +- tools/phpstan/phpstan.neon | 37 ++++++++++++++++++++++++ 54 files changed, 291 insertions(+), 1 deletion(-) diff --git a/src/Clock.php b/src/Clock.php index 3c16886d..7aef31e6 100644 --- a/src/Clock.php +++ b/src/Clock.php @@ -8,6 +8,8 @@ interface Clock { /** * Returns the current time. + * + * @phpstan-impure */ public function getTime(): Instant; } diff --git a/src/Clock/FixedClock.php b/src/Clock/FixedClock.php index 8ae13e0b..4c3a34ad 100644 --- a/src/Clock/FixedClock.php +++ b/src/Clock/FixedClock.php @@ -16,18 +16,26 @@ final class FixedClock implements Clock { /** * @param Instant $instant The time to set the clock at. + * + * @phpstan-pure */ public function __construct( private Instant $instant, ) { } + /** + * @phpstan-pure + */ #[Override] public function getTime(): Instant { return $this->instant; } + /** + * @phpstan-impure + */ public function setTime(Instant $instant): void { $this->instant = $instant; @@ -35,6 +43,8 @@ public function setTime(Instant $instant): void /** * Moves the clock by a number of seconds and/or nanos. + * + * @phpstan-impure */ public function move(int $seconds, int $nanos = 0): void { diff --git a/src/Clock/OffsetClock.php b/src/Clock/OffsetClock.php index 026971f7..5d07b6ab 100644 --- a/src/Clock/OffsetClock.php +++ b/src/Clock/OffsetClock.php @@ -17,6 +17,8 @@ /** * @param Clock $referenceClock The reference clock. * @param Duration $offset The offset to apply to the clock. + * + * @phpstan-pure */ public function __construct( private Clock $referenceClock, diff --git a/src/Clock/ScaleClock.php b/src/Clock/ScaleClock.php index 0a835fcd..05d09537 100644 --- a/src/Clock/ScaleClock.php +++ b/src/Clock/ScaleClock.php @@ -11,6 +11,8 @@ /** * This clock makes the time move at a given pace. + * + * @phpstan-all-methods-impure */ final readonly class ScaleClock implements Clock { diff --git a/src/DateTimeException.php b/src/DateTimeException.php index 9207418d..4edfbcf9 100644 --- a/src/DateTimeException.php +++ b/src/DateTimeException.php @@ -10,6 +10,8 @@ /** * This exception is used to indicate problems with creating, querying and manipulating date-time objects. + * + * @phpstan-all-methods-pure */ class DateTimeException extends RuntimeException { diff --git a/src/DayOfWeek.php b/src/DayOfWeek.php index a68ed4cc..7eff3677 100644 --- a/src/DayOfWeek.php +++ b/src/DayOfWeek.php @@ -9,6 +9,8 @@ /** * Represents a day-of-week such as Tuesday. + * + * @phpstan-all-methods-pure */ enum DayOfWeek: int implements JsonSerializable { @@ -24,6 +26,8 @@ enum DayOfWeek: int implements JsonSerializable * Returns the current day-of-week in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public static function now(TimeZone $timeZone, ?Clock $clock = null): DayOfWeek { diff --git a/src/DefaultClock.php b/src/DefaultClock.php index 0bf203a2..0bef4630 100644 --- a/src/DefaultClock.php +++ b/src/DefaultClock.php @@ -13,6 +13,8 @@ * This is where the default clock is set for all methods such as `now()`. * * The default clock is the system clock by default, but can be changed for testing. + * + * @phpstan-all-methods-impure */ final class DefaultClock { @@ -20,6 +22,8 @@ final class DefaultClock /** * Private constructor. This class is not instantiable. + * + * @phpstan-pure */ private function __construct() { diff --git a/src/Duration.php b/src/Duration.php index 7ff1fbb7..2a510471 100644 --- a/src/Duration.php +++ b/src/Duration.php @@ -22,6 +22,8 @@ * Represents a duration of time measured in seconds. * * This class is immutable. + * + * @phpstan-all-methods-pure */ final readonly class Duration implements JsonSerializable, Stringable { diff --git a/src/Field/DayOfMonth.php b/src/Field/DayOfMonth.php index dadde48d..9977546a 100644 --- a/src/Field/DayOfMonth.php +++ b/src/Field/DayOfMonth.php @@ -8,6 +8,8 @@ /** * The day-of-month field. + * + * @phpstan-all-methods-pure */ final class DayOfMonth { @@ -29,6 +31,8 @@ final class DayOfMonth * @throws DateTimeException If the day-of-month is not valid. * * @phpstan-assert int<1, 31> $dayOfMonth + * + * @phpstan-pure */ public static function check(int $dayOfMonth, ?int $monthOfYear = null, ?int $year = null): void { diff --git a/src/Field/DayOfWeek.php b/src/Field/DayOfWeek.php index 47e08524..5d5d0326 100644 --- a/src/Field/DayOfWeek.php +++ b/src/Field/DayOfWeek.php @@ -8,6 +8,8 @@ /** * The day-of-week field. + * + * @phpstan-all-methods-pure */ final class DayOfWeek { @@ -22,6 +24,8 @@ final class DayOfWeek * @throws DateTimeException If the day-of-week is not valid. * * @phpstan-assert int<1, 7> $dayOfWeek + * + * @phpstan-pure */ public static function check(int $dayOfWeek): void { diff --git a/src/Field/DayOfYear.php b/src/Field/DayOfYear.php index dd768472..2fe1b71b 100644 --- a/src/Field/DayOfYear.php +++ b/src/Field/DayOfYear.php @@ -8,6 +8,8 @@ /** * The day-of-year field. + * + * @phpstan-all-methods-pure */ final class DayOfYear { @@ -23,6 +25,8 @@ final class DayOfYear * @throws DateTimeException If the day-of-year is not valid. * * @phpstan-assert int<1, 366> $dayOfYear + * + * @phpstan-pure */ public static function check(int $dayOfYear, ?int $year = null): void { diff --git a/src/Field/FractionOfSecond.php b/src/Field/FractionOfSecond.php index 0222e621..dd33924d 100644 --- a/src/Field/FractionOfSecond.php +++ b/src/Field/FractionOfSecond.php @@ -10,6 +10,8 @@ * This is used together with nano-of-second: fraction-of-second is used during parsing * as its length can range anywhere from 1 to 9; the number is then padded right with * zeros to make it 9 digits long, effectively becoming a nano-of-second. + * + * @phpstan-all-methods-pure */ final class FractionOfSecond { diff --git a/src/Field/HourOfDay.php b/src/Field/HourOfDay.php index 1990b47f..9d4b9801 100644 --- a/src/Field/HourOfDay.php +++ b/src/Field/HourOfDay.php @@ -8,6 +8,8 @@ /** * The hour-of-day field. + * + * @phpstan-all-methods-pure */ final class HourOfDay { @@ -25,6 +27,8 @@ final class HourOfDay * @param int $hourOfDay The hour-of-day to check. * * @throws DateTimeException If the hour-of-day is not valid. + * + * @phpstan-pure */ public static function check(int $hourOfDay): void { diff --git a/src/Field/MinuteOfHour.php b/src/Field/MinuteOfHour.php index 79ac3b5e..1f801fba 100644 --- a/src/Field/MinuteOfHour.php +++ b/src/Field/MinuteOfHour.php @@ -8,6 +8,8 @@ /** * The minute-of-hour field. + * + * @phpstan-all-methods-pure */ final class MinuteOfHour { @@ -25,6 +27,8 @@ final class MinuteOfHour * @param int $minuteOfHour The minute-of-hour to check. * * @throws DateTimeException If the minute-of-hour is not valid. + * + * @phpstan-pure */ public static function check(int $minuteOfHour): void { diff --git a/src/Field/MonthOfYear.php b/src/Field/MonthOfYear.php index 691269ca..dff9d734 100644 --- a/src/Field/MonthOfYear.php +++ b/src/Field/MonthOfYear.php @@ -8,6 +8,8 @@ /** * The month-of-year field. + * + * @phpstan-all-methods-pure */ final class MonthOfYear { @@ -27,6 +29,8 @@ final class MonthOfYear * @throws DateTimeException If the month-of-year is not valid. * * @phpstan-assert int<1, 12> $monthOfYear + * + * @phpstan-pure */ public static function check(int $monthOfYear): void { diff --git a/src/Field/NanoOfSecond.php b/src/Field/NanoOfSecond.php index f54abb23..d1f94b8c 100644 --- a/src/Field/NanoOfSecond.php +++ b/src/Field/NanoOfSecond.php @@ -8,6 +8,8 @@ /** * The nano-of-second field. + * + * @phpstan-all-methods-pure */ final class NanoOfSecond { @@ -20,6 +22,8 @@ final class NanoOfSecond * @param int $nanoOfSecond The nano-of-second to check. * * @throws DateTimeException If the nano-of-second is not valid. + * + * @phpstan-pure */ public static function check(int $nanoOfSecond): void { diff --git a/src/Field/SecondOfDay.php b/src/Field/SecondOfDay.php index 3e088596..aa94e485 100644 --- a/src/Field/SecondOfDay.php +++ b/src/Field/SecondOfDay.php @@ -8,6 +8,8 @@ /** * The second-of-day field. + * + * @phpstan-all-methods-pure */ final class SecondOfDay { @@ -20,6 +22,8 @@ final class SecondOfDay * @param int $secondOfDay The second-of-day to check. * * @throws DateTimeException If the second-of-day is not valid. + * + * @phpstan-pure */ public static function check(int $secondOfDay): void { diff --git a/src/Field/SecondOfMinute.php b/src/Field/SecondOfMinute.php index b7b5d426..9f0d6cc2 100644 --- a/src/Field/SecondOfMinute.php +++ b/src/Field/SecondOfMinute.php @@ -8,6 +8,8 @@ /** * The second-of-minute field. + * + * @phpstan-all-methods-pure */ final class SecondOfMinute { @@ -25,6 +27,8 @@ final class SecondOfMinute * @param int $secondOfMinute The second-of-minute to check. * * @throws DateTimeException If the second-of-minute is not valid. + * + * @phpstan-pure */ public static function check(int $secondOfMinute): void { diff --git a/src/Field/TimeZoneOffsetHour.php b/src/Field/TimeZoneOffsetHour.php index 03fe6f9f..ffd876b2 100644 --- a/src/Field/TimeZoneOffsetHour.php +++ b/src/Field/TimeZoneOffsetHour.php @@ -8,6 +8,8 @@ /** * The hour part of the time-zone offset. + * + * @phpstan-all-methods-pure */ final class TimeZoneOffsetHour { @@ -25,6 +27,8 @@ final class TimeZoneOffsetHour * @param int $offsetHour The offset-hour to check. * * @throws DateTimeException If the offset-hour is not valid. + * + * @phpstan-pure */ public static function check(int $offsetHour): void { diff --git a/src/Field/TimeZoneOffsetMinute.php b/src/Field/TimeZoneOffsetMinute.php index 35e9eddd..ba5bbcb0 100644 --- a/src/Field/TimeZoneOffsetMinute.php +++ b/src/Field/TimeZoneOffsetMinute.php @@ -8,6 +8,8 @@ /** * The minute part of the time-zone offset. + * + * @phpstan-all-methods-pure */ final class TimeZoneOffsetMinute { @@ -25,6 +27,8 @@ final class TimeZoneOffsetMinute * @param int $offsetMinute The offset-minute to check. * * @throws DateTimeException If the offset-minute is not valid. + * + * @phpstan-pure */ public static function check(int $offsetMinute): void { diff --git a/src/Field/TimeZoneOffsetSecond.php b/src/Field/TimeZoneOffsetSecond.php index 066a77a0..f50ea496 100644 --- a/src/Field/TimeZoneOffsetSecond.php +++ b/src/Field/TimeZoneOffsetSecond.php @@ -8,6 +8,8 @@ /** * The second part of the time-zone offset. + * + * @phpstan-all-methods-pure */ final class TimeZoneOffsetSecond { @@ -25,6 +27,8 @@ final class TimeZoneOffsetSecond * @param int $offsetSecond The offset-second to check. * * @throws DateTimeException If the offset-second is not valid. + * + * @phpstan-pure */ public static function check(int $offsetSecond): void { diff --git a/src/Field/TimeZoneOffsetSign.php b/src/Field/TimeZoneOffsetSign.php index 01c28a63..00cfb461 100644 --- a/src/Field/TimeZoneOffsetSign.php +++ b/src/Field/TimeZoneOffsetSign.php @@ -6,6 +6,8 @@ /** * The time-zone offset sign, '+', '-', 'Z' or 'z'. + * + * @phpstan-all-methods-pure */ final class TimeZoneOffsetSign { diff --git a/src/Field/TimeZoneOffsetTotalSeconds.php b/src/Field/TimeZoneOffsetTotalSeconds.php index 3ef0d3d2..9af9b822 100644 --- a/src/Field/TimeZoneOffsetTotalSeconds.php +++ b/src/Field/TimeZoneOffsetTotalSeconds.php @@ -10,6 +10,8 @@ * The total number of seconds in a time-zone offset, from -64800 to 64800 (-18:00 to +18:00). * * The offset is relative to UTC/Greenwich. + * + * @phpstan-all-methods-pure */ final class TimeZoneOffsetTotalSeconds { @@ -27,6 +29,8 @@ final class TimeZoneOffsetTotalSeconds * @param int $offsetSeconds The offset-seconds to check. * * @throws DateTimeException If the offset-seconds is not valid. + * + * @phpstan-pure */ public static function check(int $offsetSeconds): void { diff --git a/src/Field/TimeZoneRegion.php b/src/Field/TimeZoneRegion.php index 1719498d..74498f70 100644 --- a/src/Field/TimeZoneRegion.php +++ b/src/Field/TimeZoneRegion.php @@ -6,6 +6,8 @@ /** * The time-zone region, such as 'Europe/London'. + * + * @phpstan-all-methods-pure */ final class TimeZoneRegion { diff --git a/src/Field/WeekOfYear.php b/src/Field/WeekOfYear.php index e2ef6051..e7575f3b 100644 --- a/src/Field/WeekOfYear.php +++ b/src/Field/WeekOfYear.php @@ -11,6 +11,8 @@ /** * The week-of-year field. + * + * @phpstan-all-methods-pure */ final class WeekOfYear { @@ -29,6 +31,8 @@ final class WeekOfYear * @param int|null $year An optional year to check against, validated. * * @throws DateTimeException If the week-of-year is not valid. + * + * @phpstan-pure */ public static function check(int $weekOfYear, ?int $year = null): void { diff --git a/src/Field/Year.php b/src/Field/Year.php index 32833829..b945ea34 100644 --- a/src/Field/Year.php +++ b/src/Field/Year.php @@ -8,6 +8,8 @@ /** * The proleptic year field. + * + * @phpstan-all-methods-pure */ final class Year { @@ -35,6 +37,8 @@ final class Year * @param int $year The year to check. * * @throws DateTimeException If the year is not valid. + * + * @phpstan-pure */ public static function check(int $year): void { diff --git a/src/Instant.php b/src/Instant.php index 34fadda9..e52803ea 100644 --- a/src/Instant.php +++ b/src/Instant.php @@ -22,6 +22,8 @@ * Instant represents the computer view of the timeline. It unambiguously represents a point in time, * without any calendar concept of date, time or time zone. It is not very meaningful to humans, * but can be converted to a `ZonedDateTime` by providing a time zone. + * + * @phpstan-all-methods-pure */ final readonly class Instant implements JsonSerializable, Stringable { @@ -73,6 +75,9 @@ public static function epoch(): Instant return $epoch ??= new Instant(0, 0); } + /** + * @phpstan-impure + */ public static function now(?Clock $clock = null): Instant { if ($clock === null) { @@ -291,6 +296,8 @@ public function isBetweenExclusive(Instant $from, Instant $to): bool * Returns whether this instant is in the future, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public function isFuture(?Clock $clock = null): bool { @@ -301,6 +308,8 @@ public function isFuture(?Clock $clock = null): bool * Returns whether this instant is in the past, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public function isPast(?Clock $clock = null): bool { diff --git a/src/Interval.php b/src/Interval.php index d6a2a305..549cd96a 100644 --- a/src/Interval.php +++ b/src/Interval.php @@ -13,6 +13,8 @@ * The end instant is always greater than or equal to the start instant. * * This class is immutable. + * + * @phpstan-all-methods-pure */ final readonly class Interval implements JsonSerializable, Stringable { diff --git a/src/LocalDate.php b/src/LocalDate.php index cc5336b3..384822ef 100644 --- a/src/LocalDate.php +++ b/src/LocalDate.php @@ -28,6 +28,8 @@ * A date without a time-zone in the ISO-8601 calendar system, such as `2007-12-03`. * * This class is immutable. + * + * @phpstan-all-methods-pure */ final readonly class LocalDate implements JsonSerializable, Stringable { @@ -119,6 +121,8 @@ public static function ofYearDay(int $year, int $dayOfYear): LocalDate /** * @throws DateTimeException If the date is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): LocalDate { @@ -214,6 +218,8 @@ public static function ofEpochDay(int $epochDay): LocalDate * Returns the current date in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public static function now(TimeZone $timeZone, ?Clock $clock = null): LocalDate { diff --git a/src/LocalDateRange.php b/src/LocalDateRange.php index 64b77f4e..23aa435e 100644 --- a/src/LocalDateRange.php +++ b/src/LocalDateRange.php @@ -25,6 +25,8 @@ * in the range, while `count()` returns the total number of dates contained in the range. * * @template-implements IteratorAggregate + * + * @phpstan-all-methods-pure */ final readonly class LocalDateRange implements IteratorAggregate, Countable, JsonSerializable, Stringable { @@ -62,6 +64,8 @@ public static function of(LocalDate $start, LocalDate $end): LocalDateRange * * @throws DateTimeException If the date range is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): LocalDateRange { @@ -215,6 +219,8 @@ public function toPeriod(): Period * Returns an iterator for all the dates contained in this range. * * @return Generator + * + * @phpstan-impure */ #[Override] public function getIterator(): Generator diff --git a/src/LocalDateTime.php b/src/LocalDateTime.php index 927910b1..26bef393 100644 --- a/src/LocalDateTime.php +++ b/src/LocalDateTime.php @@ -22,6 +22,8 @@ * A date-time without a time-zone in the ISO-8601 calendar system, such as 2007-12-03T10:15:30. * * This class is immutable. + * + * @phpstan-all-methods-pure */ final readonly class LocalDateTime implements JsonSerializable, Stringable { @@ -54,6 +56,8 @@ public static function of(int $year, int|Month $month, int $day, int $hour = 0, * Returns the current local date-time in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public static function now(TimeZone $timeZone, ?Clock $clock = null): LocalDateTime { @@ -63,6 +67,8 @@ public static function now(TimeZone $timeZone, ?Clock $clock = null): LocalDateT /** * @throws DateTimeException If the date-time is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): LocalDateTime { @@ -695,6 +701,8 @@ public function isAfterOrEqualTo(LocalDateTime $that): bool * Returns whether this LocalDateTime is in the future, in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public function isFuture(TimeZone $timeZone, ?Clock $clock = null): bool { @@ -705,6 +713,8 @@ public function isFuture(TimeZone $timeZone, ?Clock $clock = null): bool * Returns whether this LocalDateTime is in the past, in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public function isPast(TimeZone $timeZone, ?Clock $clock = null): bool { diff --git a/src/LocalTime.php b/src/LocalTime.php index 25a71562..9d124e16 100644 --- a/src/LocalTime.php +++ b/src/LocalTime.php @@ -29,6 +29,8 @@ * A time without a time-zone in the ISO-8601 calendar system, such as 10:15:30. * * This class is immutable. + * + * @phpstan-all-methods-pure */ final readonly class LocalTime implements JsonSerializable, Stringable { @@ -102,6 +104,8 @@ public static function ofSecondOfDay(int $secondOfDay, int $nanoOfSecond = 0): L /** * @throws DateTimeException If the time is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): LocalTime { @@ -150,6 +154,8 @@ public static function fromNativeDateTime(DateTimeInterface $dateTime): LocalTim * Returns the current local time in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public static function now(TimeZone $timeZone, ?Clock $clock = null): LocalTime { diff --git a/src/Month.php b/src/Month.php index 4c2973e4..2d7cd97a 100644 --- a/src/Month.php +++ b/src/Month.php @@ -9,6 +9,8 @@ /** * Represents a month-of-year such as January. + * + * @phpstan-all-methods-pure */ enum Month: int implements JsonSerializable { diff --git a/src/MonthDay.php b/src/MonthDay.php index 5a105313..1f8d9f3e 100644 --- a/src/MonthDay.php +++ b/src/MonthDay.php @@ -16,6 +16,8 @@ /** * A month-day in the ISO-8601 calendar system, such as `--12-03`. + * + * @phpstan-all-methods-pure */ final readonly class MonthDay implements JsonSerializable, Stringable { @@ -55,6 +57,8 @@ public static function of(int|Month $month, int $day): MonthDay /** * @throws DateTimeException If the month-day is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): MonthDay { @@ -86,6 +90,8 @@ public static function parse(string $text, ?DateTimeParser $parser = null): Mont * Returns the current month-day in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public static function now(TimeZone $timeZone, ?Clock $clock = null): MonthDay { diff --git a/src/Parser/DateTimeParseException.php b/src/Parser/DateTimeParseException.php index 422e81c9..7732d93a 100644 --- a/src/Parser/DateTimeParseException.php +++ b/src/Parser/DateTimeParseException.php @@ -8,6 +8,8 @@ /** * Exception thrown when a parse error occurs. + * + * @phpstan-all-methods-pure */ final class DateTimeParseException extends DateTimeException { diff --git a/src/Parser/DateTimeParseResult.php b/src/Parser/DateTimeParseResult.php index 7122baba..0c046da5 100644 --- a/src/Parser/DateTimeParseResult.php +++ b/src/Parser/DateTimeParseResult.php @@ -17,6 +17,9 @@ final class DateTimeParseResult */ private array $fields = []; + /** + * @phpstan-impure + */ public function addField(string $name, string $value): void { $this->fields[$name][] = $value; @@ -24,6 +27,8 @@ public function addField(string $name, string $value): void /** * Returns whether this result has at least one value for the given field. + * + * @phpstan-pure */ public function hasField(string $name): bool { @@ -38,6 +43,8 @@ public function hasField(string $name): bool * @return string The value for this field. * * @throws DateTimeParseException If the field is not present in this set. + * + * @phpstan-impure */ public function getField(string $name): string { @@ -52,6 +59,8 @@ public function getField(string $name): string /** * Returns the first value for the given field, or an empty string if not present. + * + * @phpstan-impure */ public function getOptionalField(string $name): string { diff --git a/src/Parser/DateTimeParser.php b/src/Parser/DateTimeParser.php index 6227bc30..2c0bd644 100644 --- a/src/Parser/DateTimeParser.php +++ b/src/Parser/DateTimeParser.php @@ -15,6 +15,8 @@ interface DateTimeParser * @return DateTimeParseResult The parse result. * * @throws DateTimeParseException If the given text could not be parsed. + * + * @phpstan-pure */ public function parse(string $text): DateTimeParseResult; } diff --git a/src/Parser/IsoParsers.php b/src/Parser/IsoParsers.php index 81f835a8..be6ef82d 100644 --- a/src/Parser/IsoParsers.php +++ b/src/Parser/IsoParsers.php @@ -20,6 +20,8 @@ /** * Provides ISO 8601 parser implementations. + * + * @phpstan-all-methods-pure */ final class IsoParsers { diff --git a/src/Parser/PatternParser.php b/src/Parser/PatternParser.php index 4fc4e9f4..66ab7d4d 100644 --- a/src/Parser/PatternParser.php +++ b/src/Parser/PatternParser.php @@ -11,6 +11,8 @@ /** * Matches a regular expression pattern to a set of date-time fields. + * + * @phpstan-all-methods-pure */ final readonly class PatternParser implements DateTimeParser { @@ -52,6 +54,7 @@ public function parse(string $text): DateTimeParseResult foreach ($this->fields as $field) { if (isset($matches[$index]) && $matches[$index] !== '') { + // @phpstan-ignore impure.methodCall (the result was created just above) $result->addField($field, $matches[$index]); } diff --git a/src/Parser/PatternParserBuilder.php b/src/Parser/PatternParserBuilder.php index 1be3bce2..1c78b7d6 100644 --- a/src/Parser/PatternParserBuilder.php +++ b/src/Parser/PatternParserBuilder.php @@ -27,6 +27,9 @@ final class PatternParserBuilder */ private array $stack = []; + /** + * @phpstan-impure + */ public function append(PatternParser $parser): self { $this->pattern .= $parser->getPattern(); @@ -35,6 +38,9 @@ public function append(PatternParser $parser): self return $this; } + /** + * @phpstan-impure + */ public function appendLiteral(string $literal): self { $this->pattern .= preg_quote($literal, '/'); @@ -42,6 +48,9 @@ public function appendLiteral(string $literal): self return $this; } + /** + * @phpstan-impure + */ public function appendCapturePattern(string $pattern, string $field): self { $this->pattern .= '(' . $pattern . ')'; @@ -50,6 +59,9 @@ public function appendCapturePattern(string $pattern, string $field): self return $this; } + /** + * @phpstan-impure + */ public function startOptional(): self { $this->pattern .= '(?:'; @@ -58,6 +70,9 @@ public function startOptional(): self return $this; } + /** + * @phpstan-impure + */ public function endOptional(): self { if (array_pop($this->stack) !== 'O') { @@ -69,6 +84,9 @@ public function endOptional(): self return $this; } + /** + * @phpstan-impure + */ public function startGroup(): self { $this->pattern .= '(?:'; @@ -77,6 +95,9 @@ public function startGroup(): self return $this; } + /** + * @phpstan-impure + */ public function endGroup(): self { if (array_pop($this->stack) !== 'G') { @@ -88,6 +109,9 @@ public function endGroup(): self return $this; } + /** + * @phpstan-impure + */ public function appendOr(): self { $this->pattern .= '|'; @@ -95,6 +119,9 @@ public function appendOr(): self return $this; } + /** + * @phpstan-pure + */ public function toParser(): PatternParser { if ($this->stack !== []) { diff --git a/src/Period.php b/src/Period.php index c01c21e6..78efaa49 100644 --- a/src/Period.php +++ b/src/Period.php @@ -18,6 +18,8 @@ * A date-based amount of time in the ISO-8601 calendar system, such as '2 years, 3 months and 4 days'. * * This class is immutable. + * + * @phpstan-all-methods-pure */ final readonly class Period implements JsonSerializable, Stringable { diff --git a/src/Quarter.php b/src/Quarter.php index b10d5574..6030b798 100644 --- a/src/Quarter.php +++ b/src/Quarter.php @@ -9,6 +9,8 @@ /** * Represents a quarter-of-year. + * + * @phpstan-all-methods-pure */ enum Quarter: int implements JsonSerializable { @@ -36,6 +38,8 @@ enum Quarter: int implements JsonSerializable * Returns the current quarter in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public static function now(TimeZone $timeZone, ?Clock $clock = null): self { diff --git a/src/Stopwatch.php b/src/Stopwatch.php index 976f6490..bb4ede6c 100644 --- a/src/Stopwatch.php +++ b/src/Stopwatch.php @@ -25,6 +25,8 @@ final class Stopwatch /** * @param Clock|null $clock An optional clock to use. + * + * @phpstan-impure */ public function __construct(?Clock $clock = null) { @@ -40,6 +42,8 @@ public function __construct(?Clock $clock = null) * Starts the timer. * * If the timer is already started, this method does nothing. + * + * @phpstan-impure */ public function start(): void { @@ -52,6 +56,8 @@ public function start(): void * Stops the timer and returns the lap duration. * * If the timer is already stopped, this method does nothing, and returns a zero duration. + * + * @phpstan-impure */ public function stop(): Duration { @@ -70,12 +76,17 @@ public function stop(): Duration /** * Returns the time this stopwatch has been started at, or null if it is not running. + * + * @phpstan-pure */ public function getStartTime(): ?Instant { return $this->startTime; } + /** + * @phpstan-pure + */ public function isRunning(): bool { return $this->startTime !== null; @@ -86,6 +97,8 @@ public function isRunning(): bool * * This includes the times between previous start() and stop() calls if any, * as well as the time since the stopwatch was last started if it is running. + * + * @phpstan-impure */ public function getElapsedTime(): Duration { diff --git a/src/TimeZone.php b/src/TimeZone.php index 07267702..35851119 100644 --- a/src/TimeZone.php +++ b/src/TimeZone.php @@ -17,6 +17,8 @@ * * * `TimeZoneOffset` represents a fixed offset from UTC such as `+02:00`. * * `TimeZoneRegion` represents a geographical region such as `Europe/London`. + * + * @phpstan-all-methods-pure */ abstract class TimeZone implements Stringable { diff --git a/src/TimeZoneOffset.php b/src/TimeZoneOffset.php index 34f8c5e0..aa1a0305 100644 --- a/src/TimeZoneOffset.php +++ b/src/TimeZoneOffset.php @@ -13,6 +13,8 @@ /** * A time-zone offset from Greenwich/UTC, such as `+02:00`. + * + * @phpstan-all-methods-pure */ final class TimeZoneOffset extends TimeZone { @@ -98,6 +100,8 @@ public static function utc(): TimeZoneOffset /** * @throws DateTimeException If the offset is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): TimeZoneOffset { diff --git a/src/TimeZoneRegion.php b/src/TimeZoneRegion.php index b4eb1bbe..77afafcc 100644 --- a/src/TimeZoneRegion.php +++ b/src/TimeZoneRegion.php @@ -15,6 +15,8 @@ /** * A geographical region where the same time-zone rules apply, such as `Europe/London`. + * + * @phpstan-all-methods-pure */ final class TimeZoneRegion extends TimeZone { @@ -48,6 +50,8 @@ public static function of(string $id): TimeZoneRegion /** * @throws DateTimeException If the region is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): TimeZoneRegion { diff --git a/src/Utility/Math.php b/src/Utility/Math.php index a88804a7..e9f22d90 100644 --- a/src/Utility/Math.php +++ b/src/Utility/Math.php @@ -13,6 +13,8 @@ * Internal utility class for calculations on integers. * * @internal + * + * @phpstan-all-methods-pure */ final class Math { diff --git a/src/Year.php b/src/Year.php index e626825d..7979322e 100644 --- a/src/Year.php +++ b/src/Year.php @@ -19,6 +19,8 @@ /** * Represents a year in the proleptic calendar. + * + * @phpstan-all-methods-pure */ final readonly class Year implements JsonSerializable, Stringable { @@ -46,6 +48,8 @@ public static function of(int $year): Year /** * @throws DateTimeException If the year is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): Year { @@ -76,6 +80,8 @@ public static function parse(string $text, ?DateTimeParser $parser = null): Year * Returns the current year in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public static function now(TimeZone $timeZone, ?Clock $clock = null): Year { diff --git a/src/YearMonth.php b/src/YearMonth.php index 6b0f0ddd..68c2b827 100644 --- a/src/YearMonth.php +++ b/src/YearMonth.php @@ -20,6 +20,8 @@ /** * Represents the combination of a year and a month. + * + * @phpstan-all-methods-pure */ final readonly class YearMonth implements JsonSerializable, Stringable { @@ -56,6 +58,8 @@ public static function of(int $year, int|Month $month): YearMonth /** * @throws DateTimeException If the year-month is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): YearMonth { @@ -87,6 +91,8 @@ public static function parse(string $text, ?DateTimeParser $parser = null): Year * Returns the current year-month in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public static function now(TimeZone $timeZone, ?Clock $clock = null): YearMonth { diff --git a/src/YearMonthRange.php b/src/YearMonthRange.php index 6e527b64..e57b4d3f 100644 --- a/src/YearMonthRange.php +++ b/src/YearMonthRange.php @@ -22,6 +22,8 @@ * in the range, while `count()` returns the total number of year-months contained in the range. * * @template-implements IteratorAggregate + * + * @phpstan-all-methods-pure */ final readonly class YearMonthRange implements IteratorAggregate, Countable, JsonSerializable, Stringable { @@ -59,6 +61,8 @@ public static function of(YearMonth $start, YearMonth $end): YearMonthRange * * @throws DateTimeException If the year-month range is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): YearMonthRange { @@ -145,6 +149,8 @@ public function contains(YearMonth $yearMonth): bool * Returns an iterator for all the year-months contained in this range. * * @return Generator + * + * @phpstan-impure */ #[Override] public function getIterator(): Generator diff --git a/src/YearWeek.php b/src/YearWeek.php index 27ee89b5..150cf6f4 100644 --- a/src/YearWeek.php +++ b/src/YearWeek.php @@ -19,6 +19,8 @@ /** * Represents the combination of a year and a week. + * + * @phpstan-all-methods-pure */ final readonly class YearWeek implements JsonSerializable, Stringable { @@ -51,6 +53,8 @@ public static function of(int $year, int $week): YearWeek /** * @throws DateTimeException If the year-week is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): YearWeek { @@ -78,6 +82,9 @@ public static function parse(string $text, ?DateTimeParser $parser = null): Year return YearWeek::from($parser->parse($text)); } + /** + * @phpstan-impure + */ public static function now(TimeZone $timeZone, ?Clock $clock = null): YearWeek { return LocalDate::now($timeZone, $clock)->getYearWeek(); diff --git a/src/ZonedDateTime.php b/src/ZonedDateTime.php index 28f2a822..67c3d407 100644 --- a/src/ZonedDateTime.php +++ b/src/ZonedDateTime.php @@ -29,6 +29,8 @@ * * A ZonedDateTime can be viewed as a LocalDateTime along with a time zone * and targets a specific point in time. + * + * @phpstan-all-methods-pure */ final readonly class ZonedDateTime implements JsonSerializable, Stringable { @@ -145,6 +147,8 @@ public static function ofInstant(Instant $instant, TimeZone $timeZone): ZonedDat * Returns the current date-time in the given time-zone, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public static function now(TimeZone $timeZone, ?Clock $clock = null): ZonedDateTime { @@ -158,6 +162,8 @@ public static function now(TimeZone $timeZone, ?Clock $clock = null): ZonedDateT * * @throws DateTimeException If the zoned date-time is not valid. * @throws DateTimeParseException If required fields are missing from the result. + * + * @phpstan-impure */ public static function from(DateTimeParseResult $result): ZonedDateTime { @@ -713,6 +719,8 @@ public function isBetweenExclusive(ZonedDateTime $from, ZonedDateTime $to): bool * Returns whether this ZonedDateTime is in the future, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public function isFuture(?Clock $clock = null): bool { @@ -723,6 +731,8 @@ public function isFuture(?Clock $clock = null): bool * Returns whether this ZonedDateTime is in the past, according to the given clock. * * If no clock is provided, the system clock is used. + * + * @phpstan-impure */ public function isPast(?Clock $clock = null): bool { @@ -747,6 +757,7 @@ public function toNativeDateTime(): DateTime assert($nativeDateTime !== false); + // @phpstan-ignore impure.methodCall (the DateTime was created just above) $nativeDateTime->setTimezone($this->timeZone->toNativeDateTimeZone()); return $nativeDateTime; diff --git a/tools/phpstan/composer.json b/tools/phpstan/composer.json index 1eade3bd..4ca1c336 100644 --- a/tools/phpstan/composer.json +++ b/tools/phpstan/composer.json @@ -1,5 +1,5 @@ { "require": { - "phpstan/phpstan": "2.1.42" + "phpstan/phpstan": "2.3.4" } } diff --git a/tools/phpstan/phpstan.neon b/tools/phpstan/phpstan.neon index c8940fe6..2e604b91 100644 --- a/tools/phpstan/phpstan.neon +++ b/tools/phpstan/phpstan.neon @@ -1,5 +1,42 @@ parameters: level: 10 checkUninitializedProperties: true + phpVersion: + min: 80200 + max: 80699 paths: - ../../src + ignoreErrors: + # The methods below are pure as far as their callers can tell, which PHPStan cannot see. + + # A static variable memoizes a value that never changes + - + identifier: impure.static + path: ../../src/* + + # parse() hands from() the result it has just created, so from() consuming it has no effect outside + - + message: '#^Impure call to method Brick\\DateTime\\\w+::from\(\) in pure method Brick\\DateTime\\\w+::parse\(\)\.$#' + identifier: impure.methodCall + path: ../../src/* + + # PHPStan counts any call to a void method as impure, even to a validator that it accepts as pure + - + message: '#^Impure call to method Brick\\DateTime\\Field\\\w+::check\(\) in pure method #' + identifier: impure.methodCall + path: ../../src/* + + # Each parser is built with a builder created on the spot + - + identifier: impure.methodCall + path: ../../src/Parser/IsoParsers.php + + # getId() caches the ID it computes + - + identifier: impure.propertyAssign + path: ../../src/TimeZoneOffset.php + + # PHPStan does not know whether these native functions and classes are pure + - + message: '#^Possibly impure (call to function (assert|preg_match)\(\)|instantiation of class Date\w+|call to method Date\w+::\w+\(\)) in pure method #' + path: ../../src/* From 99b278c163443a495468d52507899f8d7bb47dab Mon Sep 17 00:00:00 2001 From: Dorian Villet Date: Fri, 30 Oct 2026 08:16:21 +0100 Subject: [PATCH 2/2] Add a PHPStan rule requiring methods to declare their purity 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 Claude-Session: https://claude.ai/code/session_01Y1vvcUHV6d9eTuxE4GW5MX --- .gitignore | 1 + tools/ecs/ecs.php | 1 + tools/phpstan/composer.json | 5 + tools/phpstan/phpstan.neon | 10 + .../phpstan/src/AbstractMethodPurityRule.php | 52 +++++ tools/phpstan/src/MethodPurityRule.php | 183 ++++++++++++++++++ 6 files changed, 252 insertions(+) create mode 100644 tools/phpstan/src/AbstractMethodPurityRule.php create mode 100644 tools/phpstan/src/MethodPurityRule.php diff --git a/.gitignore b/.gitignore index f71c6556..6eb4049a 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,4 @@ /tools/phpstan/* !/tools/phpstan/composer.json !/tools/phpstan/phpstan.neon +!/tools/phpstan/src/ diff --git a/tools/ecs/ecs.php b/tools/ecs/ecs.php index ef3c7dfa..b5181a70 100644 --- a/tools/ecs/ecs.php +++ b/tools/ecs/ecs.php @@ -16,6 +16,7 @@ [ $libRootPath . '/src', $libRootPath . '/tests', + $libRootPath . '/tools/phpstan/src', __FILE__, ], ); diff --git a/tools/phpstan/composer.json b/tools/phpstan/composer.json index 4ca1c336..5b714c67 100644 --- a/tools/phpstan/composer.json +++ b/tools/phpstan/composer.json @@ -1,5 +1,10 @@ { "require": { "phpstan/phpstan": "2.3.4" + }, + "autoload": { + "psr-4": { + "Brick\\DateTime\\PHPStan\\": "src/" + } } } diff --git a/tools/phpstan/phpstan.neon b/tools/phpstan/phpstan.neon index 2e604b91..4669c503 100644 --- a/tools/phpstan/phpstan.neon +++ b/tools/phpstan/phpstan.neon @@ -6,7 +6,13 @@ parameters: max: 80699 paths: - ../../src + - src ignoreErrors: + # The purity rules are for the library's API, not for these rules + - + identifier: brick.methodPurity + path: src/* + # The methods below are pure as far as their callers can tell, which PHPStan cannot see. # A static variable memoizes a value that never changes @@ -40,3 +46,7 @@ parameters: - message: '#^Possibly impure (call to function (assert|preg_match)\(\)|instantiation of class Date\w+|call to method Date\w+::\w+\(\)) in pure method #' path: ../../src/* + +rules: + - Brick\DateTime\PHPStan\AbstractMethodPurityRule + - Brick\DateTime\PHPStan\MethodPurityRule diff --git a/tools/phpstan/src/AbstractMethodPurityRule.php b/tools/phpstan/src/AbstractMethodPurityRule.php new file mode 100644 index 00000000..9d425fc0 --- /dev/null +++ b/tools/phpstan/src/AbstractMethodPurityRule.php @@ -0,0 +1,52 @@ + + */ +final class AbstractMethodPurityRule implements Rule +{ + #[Override] + public function getNodeType(): string + { + return InClassMethodNode::class; + } + + #[Override] + public function processNode(Node $node, Scope $scope): array + { + $method = $node->getMethodReflection(); + + if ($node->getOriginalNode()->stmts !== null || ! $method->isPublic() || ! $method->isPure()->maybe()) { + return []; + } + + return [ + RuleErrorBuilder::message(sprintf( + 'Abstract method %s::%s() must declare its purity with @phpstan-pure or @phpstan-impure.', + $node->getClassReflection()->getDisplayName(), + $method->getName(), + )) + ->identifier('brick.methodPurity') + ->tip('@phpstan-all-methods-pure or @phpstan-all-methods-impure on the class also does it, except for a void method in a pure class.') + ->build(), + ]; + } +} diff --git a/tools/phpstan/src/MethodPurityRule.php b/tools/phpstan/src/MethodPurityRule.php new file mode 100644 index 00000000..a4b83ceb --- /dev/null +++ b/tools/phpstan/src/MethodPurityRule.php @@ -0,0 +1,183 @@ + + */ +final class MethodPurityRule implements Rule +{ + #[Override] + public function getNodeType(): string + { + return MethodReturnStatementsNode::class; + } + + #[Override] + public function processNode(Node $node, Scope $scope): array + { + $method = $node->getMethodReflection(); + + if (! $this->isRequired($method) || ! $method->isPure()->maybe()) { + return []; + } + + $error = RuleErrorBuilder::message(sprintf( + 'Method %s::%s() must declare its purity with @phpstan-pure or @phpstan-impure.', + $node->getClassReflection()->getDisplayName(), + $method->getName(), + )) + ->identifier('brick.methodPurity') + ->tip('@phpstan-all-methods-pure or @phpstan-all-methods-impure on the class also does it, except for a void method in a pure class.'); + + $classMethod = $this->getClassMethod($node); + $tag = $this->inferTag($node, $classMethod); + + if ($tag === null) { + return [$error->build()]; + } + + return [ + $error->fixNode($classMethod, function (ClassMethod $classMethod) use ($tag): ClassMethod { + $this->addTag($classMethod, $tag); + + return $classMethod; + })->build(), + ]; + } + + private function isRequired(PhpMethodFromParserNodeReflection $method): bool + { + return $method->isPublic() || strtolower($method->getName()) === '__construct'; + } + + private function inferTag(MethodReturnStatementsNode $node, ClassMethod $classMethod): ?string + { + $impurePoints = $node->getImpurePoints(); + + foreach ($impurePoints as $impurePoint) { + if ($impurePoint->isCertain()) { + return '@phpstan-impure'; + } + } + + if ($impurePoints !== []) { + return null; + } + + $returnsVoid = $classMethod->returnType instanceof Node\Identifier + && $classMethod->returnType->toLowerString() === 'void'; + + if (! $returnsVoid || $classMethod->name->toLowerString() === '__construct') { + return '@phpstan-pure'; + } + + // A void method without side effects can still validate its arguments, which PHPStan accepts as pure only when + // it declares what it throws. + $throwType = $node->getMethodReflection()->getThrowType(); + + return $throwType !== null && ! $throwType->isVoid()->yes() ? '@phpstan-pure' : '@phpstan-impure'; + } + + /** + * Adds the tag at the end of the doc comment, separated from what precedes it as the coding standard wants it. + */ + private function addTag(ClassMethod $classMethod, string $tag): void + { + $doc = $classMethod->getDocComment(); + + if ($doc === null) { + $classMethod->setDocComment(new Doc("/**\n * " . $tag . "\n */")); + + return; + } + + // The reformatted text has its indentation removed, and the printer indents it again. + $text = $doc->getReformattedText(); + + if (preg_match('/^\/\*\*(.*?)\*\/$/', $text, $matches) === 1) { + $text = "/**\n * " . trim($matches[1]) . "\n */"; + } + + $lines = explode("\n", $text); + $closing = array_pop($lines); + + $lastLine = ''; + + foreach ($lines as $line) { + $line = trim(ltrim(trim($line), '/*')); + + if ($line !== '') { + $lastLine = $line; + } + } + + // The coding standard lists the @phpstan-assert tags as a group, but not the other @phpstan- tags, which it + // keeps together with the purity tag. + $joinsLastGroup = str_starts_with($lastLine, '@phpstan-') && ! str_starts_with($lastLine, '@phpstan-assert'); + + if ($lastLine !== '' && ! $joinsLastGroup) { + $lines[] = ' *'; + } + + $lines[] = ' * ' . $tag; + $lines[] = $closing; + + $classMethod->setDocComment(new Doc(implode("\n", $lines))); + } + + /** + * Returns the method node that the fix must edit. + * + * MethodReturnStatementsNode carries the impure points, but keeps the method node it was built from private, and + * a fix can only edit the node from the parsed file. + */ + private function getClassMethod(MethodReturnStatementsNode $node): ClassMethod + { + $property = new ReflectionProperty(MethodReturnStatementsNode::class, 'classMethod'); // @phpstan-ignore phpstanApi.runtimeReflection (PHPStan's own node, not the analysed code) + $classMethod = $property->getValue($node); + assert($classMethod instanceof ClassMethod); + + return $classMethod; + } +}