Add Psalm immutability annotations

src/Clock.php

@@ -8,6 +8,8 @@ interface Clock
 {
     /**
      * Returns the current time.
+     *
+     * @psalm-mutation-free
      */
     public function getTime() : Instant;
 }

src/Clock/OffsetClock.php

@@ -37,6 +37,9 @@ public function __construct(Clock $referenceClock, Duration $offset)
         $this->offset         = $offset;
     }
 
+    /**
+     * @psalm-mutation-free
+     */
     public function getTime() : Instant
     {
         return $this->referenceClock->getTime()->plus($this->offset);

src/Clock/ScaleClock.php

@@ -50,6 +50,9 @@ public function __construct(Clock $referenceClock, int $timeScale)
         $this->timeScale      = $timeScale;
     }
 
+    /**
+     * @psalm-mutation-free
+     */
     public function getTime() : Instant
     {
         $duration = Duration::between($this->startTime, $this->referenceClock->getTime());

src/Clock/SystemClock.php

@@ -14,8 +14,14 @@
  */
 final class SystemClock implements Clock
 {
+    /**
+     * @psalm-mutation-free
+     */
     public function getTime() : Instant
     {
+        /**
+         * @psalm-suppress ImpureFunctionCall This is how time works
+         */
         [$fraction, $epochSecond] = \explode(' ', microtime());
 
         $epochSecond    = (int) $epochSecond;

src/DateTimeException.php

@@ -14,12 +14,17 @@ class DateTimeException extends \RuntimeException
      * @param int    $value  The actual value.
      * @param int    $min    The minimum allowed value.
      * @param int    $max    The maximum allowed value.
+     *
+     * @psalm-pure
      */
     public static function fieldNotInRange(string $field, int $value, int $min, int $max) : self
     {
         return new DateTimeException("Invalid $field: $value is not in the range $min to $max.");
     }
 
+    /**
+     * @psalm-pure
+     */
     public static function unknownTimeZoneRegion(string $region) : self
     {
         return new self(\sprintf('Unknown time zone region "%s".', $region));

src/DayOfWeek.php

@@ -8,6 +8,8 @@
  * A day-of-week, such as Tuesday.
  *
  * This class is immutable.
+ *
+ * @psalm-immutable
  */
 final class DayOfWeek implements \JsonSerializable
 {
@@ -40,10 +42,15 @@ private function __construct(int $value)
      * Returns a cached DayOfWeek instance.
      *
      * @param int $value The day-of-week value, validated from 1 to 7.
+     *
+     * @psalm-pure
      */
     private static function get(int $value) : DayOfWeek
     {
-        /** @var array<int, DayOfWeek> $values */
+        /**
+         * @var array<int, DayOfWeek> $values
+         * @psalm-suppress ImpureStaticVariable only used to cache results
+         */
         static $values = [];
 
         if (! isset($values[$value])) {
@@ -61,6 +68,8 @@ private static function get(int $value) : DayOfWeek
      * @return DayOfWeek The DayOfWeek instance.
      *
      * @throws DateTimeException If the day-of-week is not valid.
+     *
+     * @psalm-pure
      */
     public static function of(int $dayOfWeek) : DayOfWeek
     {

src/DefaultClock.php

@@ -30,6 +30,9 @@ private function __construct()
 
     /**
      * Gets the default clock.
+     *
+     * @psalm-mutation-free
+     * @psalm-suppress ImpureStaticProperty
      */
     public static function get() : Clock
     {

src/Duration.php

@@ -12,6 +12,8 @@
  * Represents a duration of time measured in seconds.
  *
  * This class is immutable.
+ *
+ * @psalm-immutable
  */
 final class Duration implements \JsonSerializable
 {
@@ -145,6 +147,8 @@ public static function parse(string $text) : Duration
      *
      * @param int $seconds        The number of seconds of the duration.
      * @param int $nanoAdjustment The adjustment to the duration in nanoseconds.
+     *
+     * @psalm-pure
      */
     public static function ofSeconds(int $seconds, int $nanoAdjustment = 0) : Duration
     {
@@ -211,6 +215,8 @@ public static function ofDays(int $days) : Duration
      *
      * @param Instant $startInclusive The start instant, inclusive.
      * @param Instant $endExclusive   The end instant, exclusive.
+     *
+     * @psalm-pure
      */
     public static function between(Instant $startInclusive, Instant $endExclusive) : Duration
     {

src/Field/DayOfMonth.php

@@ -27,6 +27,8 @@ final class DayOfMonth
      * @param int|null $year        An optional year to check against, validated.
      *
      * @throws DateTimeException If the day-of-month is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $dayOfMonth, ?int $monthOfYear = null, ?int $year = null) : void
     {

src/Field/DayOfWeek.php

@@ -20,6 +20,8 @@ final class DayOfWeek
      * @param int $dayOfWeek The day-of-week to check.
      *
      * @throws DateTimeException If the day-of-week is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $dayOfWeek) : void
     {

src/Field/DayOfYear.php

@@ -21,6 +21,8 @@ final class DayOfYear
      * @param int|null $year      An optional year to check against, validated.
      *
      * @throws DateTimeException If the day-of-year is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $dayOfYear, ?int $year = null) : void
     {

src/Field/HourOfDay.php

@@ -25,6 +25,8 @@ final class HourOfDay
      * @param int $hourOfDay The hour-of-day to check.
      *
      * @throws DateTimeException If the hour-of-day is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $hourOfDay) : void
     {

src/Field/MinuteOfHour.php

@@ -25,6 +25,8 @@ final class MinuteOfHour
      * @param int $minuteOfHour The minute-of-hour to check.
      *
      * @throws DateTimeException If the minute-of-hour is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $minuteOfHour) : void
     {

src/Field/MonthOfYear.php

@@ -25,6 +25,8 @@ final class MonthOfYear
      * @param int $monthOfYear The month-of-year to check.
      *
      * @throws DateTimeException If the month-of-year is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $monthOfYear) : void
     {
@@ -40,6 +42,8 @@ public static function check(int $monthOfYear) : void
      *
      * @param int      $monthOfYear The month-of-year, validated.
      * @param int|null $year        An optional year the month-of-year belongs to, validated.
+     *
+     * @psalm-pure
      */
     public static function getLength(int $monthOfYear, ?int $year = null) : int
     {
@@ -62,6 +66,8 @@ public static function getLength(int $monthOfYear, ?int $year = null) : int
      * Returns the camel-cased English name of the given month-of-year.
      *
      * @param int $monthOfYear The month-of-year, validated.
+     *
+     * @psalm-pure
      */
     public static function getName(int $monthOfYear) : string
     {

src/Field/NanoOfSecond.php

@@ -20,6 +20,8 @@ final class NanoOfSecond
      * @param int $nanoOfSecond The nano-of-second to check.
      *
      * @throws DateTimeException If the nano-of-second is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $nanoOfSecond) : void
     {

src/Field/SecondOfDay.php

@@ -20,6 +20,8 @@ final class SecondOfDay
      * @param int $secondOfDay The second-of-day to check.
      *
      * @throws DateTimeException If the second-of-day is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $secondOfDay) : void
     {

src/Field/SecondOfMinute.php

@@ -25,6 +25,8 @@ final class SecondOfMinute
      * @param int $secondOfMinute The second-of-minute to check.
      *
      * @throws DateTimeException If the second-of-minute is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $secondOfMinute) : void
     {

src/Field/TimeZoneOffsetHour.php

@@ -25,6 +25,8 @@ final class TimeZoneOffsetHour
      * @param int $offsetHour The offset-hour to check.
      *
      * @throws DateTimeException If the offset-hour is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $offsetHour) : void
     {

src/Field/TimeZoneOffsetMinute.php

@@ -25,6 +25,8 @@ final class TimeZoneOffsetMinute
      * @param int $offsetMinute The offset-minute to check.
      *
      * @throws DateTimeException If the offset-minute is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $offsetMinute) : void
     {

src/Field/TimeZoneOffsetSecond.php

@@ -25,6 +25,8 @@ final class TimeZoneOffsetSecond
      * @param int $offsetSecond The offset-second to check.
      *
      * @throws DateTimeException If the offset-second is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $offsetSecond) : void
     {

src/Field/TimeZoneOffsetTotalSeconds.php

@@ -27,6 +27,8 @@ final class TimeZoneOffsetTotalSeconds
      * @param int $offsetSeconds The offset-seconds to check.
      *
      * @throws DateTimeException If the offset-seconds is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $offsetSeconds) : void
     {

src/Field/WeekOfYear.php

@@ -23,6 +23,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.
+     *
+     * @psalm-pure
      */
     public static function check(int $weekOfYear, ?int $year = null) : void
     {
@@ -43,6 +45,8 @@ public static function check(int $weekOfYear, ?int $year = null) : void
      * @param int $year The year, validated.
      *
      * @return bool True if 53 weeks, false if 52 weeks.
+     *
+     * @psalm-pure
      */
     public static function is53WeekYear(int $year) : bool
     {
@@ -59,6 +63,8 @@ public static function is53WeekYear(int $year) : bool
      * @param int $year The year, validated.
      *
      * @return int The number of weeks in the year.
+     *
+     * @psalm-pure
      */
     public static function getWeeksInYear(int $year) : int
     {

src/Field/Year.php

@@ -35,6 +35,8 @@ final class Year
      * @param int $year The year to check.
      *
      * @throws DateTimeException If the year is not valid.
+     *
+     * @psalm-pure
      */
     public static function check(int $year) : void
     {
@@ -45,6 +47,8 @@ public static function check(int $year) : void
 
     /**
      * @param int $year The year, validated.
+     *
+     * @psalm-pure
      */
     public static function isLeap(int $year) : bool
     {