Merge pull request #97 from gnutix/add-more-psalm-annotations

Add @psalm-* annotations for better static analysis (compatible with PHPStan too)

src/DayOfWeek.php

@@ -226,6 +226,8 @@ public function minus(int $days): DayOfWeek
 
     /**
      * Serializes as a string using {@see DayOfWeek::toString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -234,6 +236,8 @@ public function jsonSerialize(): string
 
     /**
      * Returns the capitalized English name of this day-of-week.
+     *
+     * @psalm-return non-empty-string
      */
     public function toString(): string
     {

src/Duration.php

@@ -466,6 +466,8 @@ public function abs(): Duration
      * @param Duration $that The other duration to compare to.
      *
      * @return int [-1,0,1] If this duration is less than, equal to, or greater than the given duration.
+     *
+     * @psalm-return -1|0|1
      */
     public function compareTo(Duration $that): int
     {
@@ -756,6 +758,8 @@ public function toNanosPart(): int
 
     /**
      * Serializes as a string using {@see Duration::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -772,6 +776,8 @@ public function jsonSerialize(): string
      * The hours, minutes and seconds will all have the same sign.
      *
      * Note that multiples of 24 hours are not output as days to avoid confusion with Period.
+     *
+     * @psalm-return non-empty-string
      */
     public function toISOString(): string
     {
@@ -817,6 +823,8 @@ public function toISOString(): string
 
     /**
      * {@see Duration::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function __toString(): string
     {

src/Instant.php

@@ -238,6 +238,8 @@ public function getNano(): int
      * Compares this instant with another.
      *
      * @return int [-1,0,1] If this instant is before, on, or after the given instant.
+     *
+     * @psalm-return -1|0|1
      */
     public function compareTo(Instant $that): int
     {
@@ -368,6 +370,8 @@ public function toDecimal(): string
 
     /**
      * Serializes as a string using {@see Instant::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -376,6 +380,8 @@ public function jsonSerialize(): string
 
     /**
      * Returns the ISO 8601 representation of this instant.
+     *
+     * @psalm-return non-empty-string
      */
     public function toISOString(): string
     {
@@ -384,6 +390,8 @@ public function toISOString(): string
 
     /**
      * {@see Instant::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function __toString(): string
     {

src/Interval.php

@@ -140,6 +140,8 @@ public function isEqualTo(Interval $that): bool
 
     /**
      * Serializes as a string using {@see Interval::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -148,6 +150,8 @@ public function jsonSerialize(): string
 
     /**
      * Returns the ISO 8601 representation of this interval.
+     *
+     * @psalm-return non-empty-string
      */
     public function toISOString(): string
     {
@@ -156,6 +160,8 @@ public function toISOString(): string
 
     /**
      * {@see Interval::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function __toString(): string
     {

src/LocalDate.php

@@ -591,6 +591,8 @@ public function minusDays(int $days): LocalDate
      * Returns -1 if this date is before the given date, 1 if after, 0 if the dates are equal.
      *
      * @return int [-1,0,1] If this date is before, on, or after the given date.
+     *
+     * @psalm-return -1|0|1
      */
     public function compareTo(LocalDate $that): int
     {
@@ -771,6 +773,8 @@ public function toNativeDateTimeImmutable(): DateTimeImmutable
 
     /**
      * Serializes as a string using {@see LocalDate::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -779,6 +783,8 @@ public function jsonSerialize(): string
 
     /**
      * Returns the ISO 8601 representation of this date.
+     *
+     * @psalm-return non-empty-string
      */
     public function toISOString(): string
     {
@@ -799,6 +805,8 @@ public function toISOString(): string
 
     /**
      * {@see LocalDate::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function __toString(): string
     {

src/LocalDateRange.php

@@ -239,6 +239,8 @@ public function count(): int
 
     /**
      * Serializes as a string using {@see LocalDateRange::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -262,6 +264,8 @@ public function toNativeDatePeriod(): DatePeriod
 
     /**
      * Returns the ISO 8601 representation of this date range.
+     *
+     * @psalm-return non-empty-string
      */
     public function toISOString(): string
     {
@@ -270,6 +274,8 @@ public function toISOString(): string
 
     /**
      * {@see LocalDateRange::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function __toString(): string
     {

src/LocalDateTime.php

@@ -659,6 +659,8 @@ public function minusNanos(int $nanos): LocalDateTime
      * @param LocalDateTime $that The date-time to compare to.
      *
      * @return int [-1,0,1] If this date-time is before, on, or after the given date-time.
+     *
+     * @psalm-return -1|0|1
      */
     public function compareTo(LocalDateTime $that): int
     {
@@ -738,6 +740,8 @@ public function toNativeDateTimeImmutable(): DateTimeImmutable
 
     /**
      * Serializes as a string using {@see LocalDateTime::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -746,6 +750,8 @@ public function jsonSerialize(): string
 
     /**
      * Returns the ISO 8601 representation of this date time.
+     *
+     * @psalm-return non-empty-string
      */
     public function toISOString(): string
     {
@@ -754,6 +760,8 @@ public function toISOString(): string
 
     /**
      * {@see LocalDateTime::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function __toString(): string
     {

src/LocalTime.php

@@ -527,6 +527,8 @@ public function minusNanos(int $nanos): LocalTime
      * @param LocalTime $that The time to compare to.
      *
      * @return int [-1,0,1] If this time is before, on, or after the given time.
+     *
+     * @psalm-return -1|0|1
      */
     public function compareTo(LocalTime $that): int
     {
@@ -643,6 +645,8 @@ public function toNativeDateTimeImmutable(): DateTimeImmutable
 
     /**
      * Serializes as a string using {@see LocalTime::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -661,6 +665,8 @@ public function jsonSerialize(): string
      * The format used will be the shortest that outputs the full value of
      * the time where the omitted parts are implied to be zero.
      * The nanoseconds value, if present, can be 0 to 9 digits.
+     *
+     * @psalm-return non-empty-string
      */
     public function toISOString(): string
     {
@@ -674,6 +680,8 @@ public function toISOString(): string
 
     /**
      * {@see LocalTime::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function __toString(): string
     {

src/Month.php

@@ -201,6 +201,8 @@ public function minus(int $months): Month
 
     /**
      * Serializes as a string using {@see Month::toString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -209,6 +211,8 @@ public function jsonSerialize(): string
 
     /**
      * Returns the capitalized English name of this Month.
+     *
+     * @psalm-return non-empty-string
      */
     public function toString(): string
     {

src/MonthDay.php

@@ -133,6 +133,8 @@ public function getDayOfMonth(): int
      * Returns -1 if this date is before the given date, 1 if after, 0 if the dates are equal.
      *
      * @return int [-1,0,1] If this date is before, on, or after the given date.
+     *
+     * @psalm-return -1|0|1
      */
     public function compareTo(MonthDay $that): int
     {
@@ -243,6 +245,8 @@ public function atYear(int $year): LocalDate
 
     /**
      * Serializes as a string using {@see MonthDay::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -251,6 +255,8 @@ public function jsonSerialize(): string
 
     /**
      * Returns the ISO 8601 representation of this month-day.
+     *
+     * @psalm-return non-empty-string
      */
     public function toISOString(): string
     {
@@ -263,6 +269,8 @@ public function toISOString(): string
 
     /**
      * {@see MonthDay::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function __toString(): string
     {

src/Period.php

@@ -379,6 +379,8 @@ public function toNativeDateInterval(): DateInterval
 
     /**
      * Serializes as a string using {@see Period::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -387,6 +389,8 @@ public function jsonSerialize(): string
 
     /**
      * Returns the ISO 8601 representation of this period.
+     *
+     * @psalm-return non-empty-string
      */
     public function toISOString(): string
     {
@@ -411,6 +415,8 @@ public function toISOString(): string
 
     /**
      * {@see Period::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function __toString(): string
     {

src/TimeZone.php

@@ -93,6 +93,9 @@ public static function fromNativeDateTimeZone(DateTimeZone $dateTimeZone): TimeZ
      */
     abstract public function toNativeDateTimeZone(): DateTimeZone;
 
+    /**
+     * @psalm-return non-empty-string
+     */
     public function __toString(): string
     {
         return $this->getId();

src/Year.php

@@ -178,6 +178,8 @@ public function minus(int $years): Year
      * @param Year $that The year to compare to.
      *
      * @return int [-1, 0, 1] If this year is before, equal to, or after the given year.
+     *
+     * @psalm-return -1|0|1
      */
     public function compareTo(Year $that): int
     {
@@ -284,6 +286,8 @@ public function toLocalDateRange(): LocalDateRange
 
     /**
      * Serializes as a string using {@see Year::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function jsonSerialize(): string
     {
@@ -292,6 +296,8 @@ public function jsonSerialize(): string
 
     /**
      * Returns the ISO 8601 representation of this year.
+     *
+     * @psalm-return non-empty-string
      */
     public function toISOString(): string
     {
@@ -307,6 +313,8 @@ public function toISOString(): string
 
     /**
      * {@see Year::toISOString()}.
+     *
+     * @psalm-return non-empty-string
      */
     public function __toString(): string
     {