[Summary view]

Differences Between: [Versions 310 and 311] [Versions 310 and 400] [Versions 310 and 401] [Versions 310 and 402] [Versions 310 and 403]

   1  <?php
   2  /**
   3   * @link    http://github.com/myclabs/php-enum
   4   * @license http://www.opensource.org/licenses/mit-license.php MIT (see the LICENSE file)
   5   */
   6  
   7  namespace MyCLabs\Enum;
   8  
   9  /**
  10   * Base Enum class
  11   *
  12   * Create an enum by implementing this class and adding class constants.
  13   *
  14   * @author Matthieu Napoli <matthieu@mnapoli.fr>
  15   * @author Daniel Costa <danielcosta@gmail.com>
  16   * @author Mirosław Filip <mirfilip@gmail.com>
  17   *
  18   * @psalm-template T
  19   * @psalm-immutable
  20   */
  21  abstract class Enum implements \JsonSerializable
  22  {
  23      /**
  24       * Enum value
  25       *
  26       * @var mixed
  27       * @psalm-var T
  28       */
  29      protected $value;
  30  
  31      /**
  32       * Store existing constants in a static cache per object.
  33       *
  34       *
  35       * @var array
  36       * @psalm-var array<class-string, array<string, mixed>>
  37       */
  38      protected static $cache = [];
  39  
  40      /**
  41       * Creates a new value of some type
  42       *
  43       * @psalm-pure
  44       * @param mixed $value
  45       *
  46       * @psalm-param static<T>|T $value
  47       * @throws \UnexpectedValueException if incompatible type is given.
  48       */
  49      public function __construct($value)
  50      {
  51          if ($value instanceof static) {
  52             /** @psalm-var T */
  53              $value = $value->getValue();
  54          }
  55  
  56          if (!$this->isValid($value)) {
  57              /** @psalm-suppress InvalidCast */
  58              throw new \UnexpectedValueException("Value '$value' is not part of the enum " . static::class);
  59          }
  60  
  61          /** @psalm-var T */
  62          $this->value = $value;
  63      }
  64  
  65      /**
  66       * @psalm-pure
  67       * @return mixed
  68       * @psalm-return T
  69       */
  70      public function getValue()
  71      {
  72          return $this->value;
  73      }
  74  
  75      /**
  76       * Returns the enum key (i.e. the constant name).
  77       *
  78       * @psalm-pure
  79       * @return mixed
  80       */
  81      public function getKey()
  82      {
  83          return static::search($this->value);
  84      }
  85  
  86      /**
  87       * @psalm-pure
  88       * @psalm-suppress InvalidCast
  89       * @return string
  90       */
  91      public function __toString()
  92      {
  93          return (string)$this->value;
  94      }
  95  
  96      /**
  97       * Determines if Enum should be considered equal with the variable passed as a parameter.
  98       * Returns false if an argument is an object of different class or not an object.
  99       *
 100       * This method is final, for more information read https://github.com/myclabs/php-enum/issues/4
 101       *
 102       * @psalm-pure
 103       * @psalm-param mixed $variable
 104       * @return bool
 105       */
 106      final public function equals($variable = null): bool
 107      {
 108          return $variable instanceof self
 109              && $this->getValue() === $variable->getValue()
 110              && static::class === \get_class($variable);
 111      }
 112  
 113      /**
 114       * Returns the names (keys) of all constants in the Enum class
 115       *
 116       * @psalm-pure
 117       * @psalm-return list<string>
 118       * @return array
 119       */
 120      public static function keys()
 121      {
 122          return \array_keys(static::toArray());
 123      }
 124  
 125      /**
 126       * Returns instances of the Enum class of all Enum constants
 127       *
 128       * @psalm-pure
 129       * @psalm-return array<string, static>
 130       * @return static[] Constant name in key, Enum instance in value
 131       */
 132      public static function values()
 133      {
 134          $values = array();
 135  
 136          /** @psalm-var T $value */
 137          foreach (static::toArray() as $key => $value) {
 138              $values[$key] = new static($value);
 139          }
 140  
 141          return $values;
 142      }
 143  
 144      /**
 145       * Returns all possible values as an array
 146       *
 147       * @psalm-pure
 148       * @psalm-suppress ImpureStaticProperty
 149       *
 150       * @psalm-return array<string, mixed>
 151       * @return array Constant name in key, constant value in value
 152       */
 153      public static function toArray()
 154      {
 155          $class = static::class;
 156  
 157          if (!isset(static::$cache[$class])) {
 158              $reflection            = new \ReflectionClass($class);
 159              static::$cache[$class] = $reflection->getConstants();
 160          }
 161  
 162          return static::$cache[$class];
 163      }
 164  
 165      /**
 166       * Check if is valid enum value
 167       *
 168       * @param $value
 169       * @psalm-param mixed $value
 170       * @psalm-pure
 171       * @return bool
 172       */
 173      public static function isValid($value)
 174      {
 175          return \in_array($value, static::toArray(), true);
 176      }
 177  
 178      /**
 179       * Check if is valid enum key
 180       *
 181       * @param $key
 182       * @psalm-param string $key
 183       * @psalm-pure
 184       * @return bool
 185       */
 186      public static function isValidKey($key)
 187      {
 188          $array = static::toArray();
 189  
 190          return isset($array[$key]) || \array_key_exists($key, $array);
 191      }
 192  
 193      /**
 194       * Return key for value
 195       *
 196       * @param $value
 197       *
 198       * @psalm-param mixed $value
 199       * @psalm-pure
 200       * @return mixed
 201       */
 202      public static function search($value)
 203      {
 204          return \array_search($value, static::toArray(), true);
 205      }
 206  
 207      /**
 208       * Returns a value when called statically like so: MyEnum::SOME_VALUE() given SOME_VALUE is a class constant
 209       *
 210       * @param string $name
 211       * @param array  $arguments
 212       *
 213       * @return static
 214       * @psalm-pure
 215       * @throws \BadMethodCallException
 216       */
 217      public static function __callStatic($name, $arguments)
 218      {
 219          $array = static::toArray();
 220          if (isset($array[$name]) || \array_key_exists($name, $array)) {
 221              return new static($array[$name]);
 222          }
 223  
 224          throw new \BadMethodCallException("No static method or enum constant '$name' in class " . static::class);
 225      }
 226  
 227      /**
 228       * Specify data which should be serialized to JSON. This method returns data that can be serialized by json_encode()
 229       * natively.
 230       *
 231       * @return mixed
 232       * @link http://php.net/manual/en/jsonserializable.jsonserialize.php
 233       * @psalm-pure
 234       */
 235      public function jsonSerialize()
 236      {
 237          return $this->getValue();
 238      }
 239  }