From d2a6b8f0648dd9e49a775df0e0ccc1520b6483d3 Mon Sep 17 00:00:00 2001 From: Dorian Villet Date: Fri, 30 Oct 2026 08:15:14 +0100 Subject: [PATCH] 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/*