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/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/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 1eade3bd..5b714c67 100644 --- a/tools/phpstan/composer.json +++ b/tools/phpstan/composer.json @@ -1,5 +1,10 @@ { "require": { - "phpstan/phpstan": "2.1.42" + "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 c8940fe6..4669c503 100644 --- a/tools/phpstan/phpstan.neon +++ b/tools/phpstan/phpstan.neon @@ -1,5 +1,52 @@ parameters: level: 10 checkUninitializedProperties: true + phpVersion: + min: 80200 + 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 + - + 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/* + +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; + } +}