Merge pull request #112 from iFixit/clarify-psalm-types

Clarify psalm types

Author: mnapoli

src/Enum.php

@@ -31,6 +31,7 @@ abstract class Enum implements \JsonSerializable
     /**
      * Store existing constants in a static cache per object.
      *
+     *
      * @var array
      * @psalm-var array<class-string, array<string, mixed>>
      */
@@ -39,26 +40,30 @@ abstract class Enum implements \JsonSerializable
     /**
      * Creates a new value of some type
      *
+     * @psalm-pure
      * @param mixed $value
      *
-     * @psalm-param T $value
-     * @psalm-suppress InvalidCast
+     * @psalm-param static<T>|T $value
      * @throws \UnexpectedValueException if incompatible type is given.
      */
     public function __construct($value)
     {
         if ($value instanceof static) {
+           /** @psalm-var T */
             $value = $value->getValue();
         }
 
         if (!$this->isValid($value)) {
+            /** @psalm-suppress InvalidCast */
             throw new \UnexpectedValueException("Value '$value' is not part of the enum " . static::class);
         }
 
+        /** @psalm-var T */
         $this->value = $value;
     }
 
     /**
+     * @psalm-pure
      * @return mixed
      * @psalm-return T
      */
@@ -79,6 +84,7 @@ public function getKey()
     }
 
     /**
+     * @psalm-pure
      * @psalm-suppress InvalidCast
      * @return string
      */
@@ -93,6 +99,7 @@ public function __toString()
      *
      * This method is final, for more information read https://github.com/myclabs/php-enum/issues/4
      *
+     * @psalm-pure
      * @psalm-param mixed $variable
      * @return bool
      */
@@ -106,6 +113,8 @@ final public function equals($variable = null): bool
     /**
      * Returns the names (keys) of all constants in the Enum class
      *
+     * @psalm-pure
+     * @psalm-return list<string>
      * @return array
      */
     public static function keys()
@@ -116,12 +125,15 @@ public static function keys()
     /**
      * Returns instances of the Enum class of all Enum constants
      *
+     * @psalm-pure
+     * @psalm-return array<string, static>
      * @return static[] Constant name in key, Enum instance in value
      */
     public static function values()
     {
         $values = array();
 
+        /** @psalm-var T $value */
         foreach (static::toArray() as $key => $value) {
             $values[$key] = new static($value);
         }
@@ -133,6 +145,8 @@ public static function values()
      * Returns all possible values as an array
      *
      * @psalm-pure
+     * @psalm-suppress ImpureStaticProperty
+     *
      * @psalm-return array<string, mixed>
      * @return array Constant name in key, constant value in value
      */
@@ -153,7 +167,7 @@ public static function toArray()
      *
      * @param $value
      * @psalm-param mixed $value
-     *
+     * @psalm-pure
      * @return bool
      */
     public static function isValid($value)
@@ -166,7 +180,7 @@ public static function isValid($value)
      *
      * @param $key
      * @psalm-param string $key
-     *
+     * @psalm-pure
      * @return bool
      */
     public static function isValidKey($key)
@@ -197,6 +211,7 @@ public static function search($value)
      * @param array  $arguments
      *
      * @return static
+     * @psalm-pure
      * @throws \BadMethodCallException
      */
     public static function __callStatic($name, $arguments)
@@ -215,6 +230,7 @@ public static function __callStatic($name, $arguments)
      *
      * @return mixed
      * @link http://php.net/manual/en/jsonserializable.jsonserialize.php
+     * @psalm-pure
      */
     public function jsonSerialize()
     {