give / src / Framework / Support / ValueObjects / BaseEnum.php

BaseEnum.php in GiveWP – Donation Plugin and Fundraising Platform 4.16.8.1, at src/Framework/Support/ValueObjects/BaseEnum.php

327 lines 8.5 KB

Raw Download Zip

1	<?php
2
3	namespace Give\Framework\Support\ValueObjects;
4
5	/**
6	* @since 3.17.0
7	*
8	* This is a fork of the myclabs/php-enum library 1.8.4 with the Stringable interface removed.
9	*
10	* In GiveWP, we have php constraints based on WordPress requirements and our customers that do not always allow us to use the latest version of php and therefore this package.
11	* At the time of this fork we are bound to php 7.2 while the package requires php 7.3. One day we will use native PHP enums in php 8.1+ and this package will be deprecated.
12	*
13	* @link http://github.com/myclabs/php-enum
14	*/
15
16	/**
17	* Base Enum class
18	*
19	* Create an enum by implementing this class and adding class constants.
20	*
21	* @author Matthieu Napoli <matthieu@mnapoli.fr>
22	* @author Daniel Costa <danielcosta@gmail.com>
23	* @author Mirosław Filip <mirfilip@gmail.com>
24	*
25	* @psalm-template T
26	* @psalm-immutable
27	* @psalm-consistent-constructor
28	*/
29	abstract class BaseEnum implements \JsonSerializable
30	{
31	/**
32	* Enum value
33	*
34	* @var mixed
35	* @psalm-var T
36	*/
37	protected $value;
38
39	/**
40	* Enum key, the constant name
41	*
42	* @var string
43	*/
44	private $key;
45
46	/**
47	* Store existing constants in a static cache per object.
48	*
49	*
50	* @var array
51	* @psalm-var array<class-string, array<string, mixed>>
52	*/
53	protected static $cache = [];
54
55	/**
56	* Cache of instances of the Enum class
57	*
58	* @var array
59	* @psalm-var array<class-string, array<string, static>>
60	*/
61	protected static $instances = [];
62
63	/**
64	* Creates a new value of some type
65	*
66	* @psalm-pure
67	* @param mixed $value
68	*
69	* @psalm-param T $value
70	* @throws \UnexpectedValueException if incompatible type is given.
71	*/
72	public function __construct($value)
73	{
74	if ($value instanceof static) {
75	/** @psalm-var T */
76	$value = $value->getValue();
77	}
78
79	/** @psalm-suppress ImplicitToStringCast assertValidValueReturningKey returns always a string but psalm has currently an issue here */
80	$this->key = static::assertValidValueReturningKey($value);
81
82	/** @psalm-var T */
83	$this->value = $value;
84	}
85
86	/**
87	* This method exists only for the compatibility reason when deserializing a previously serialized version
88	* that didn't had the key property
89	*/
90	public function __wakeup()
91	{
92	/** @psalm-suppress DocblockTypeContradiction key can be null when deserializing an enum without the key */
93	if ($this->key === null) {
94	/**
95	* @psalm-suppress InaccessibleProperty key is not readonly as marked by psalm
96	* @psalm-suppress PossiblyFalsePropertyAssignmentValue deserializing a case that was removed
97	*/
98	$this->key = static::search($this->value);
99	}
100	}
101
102	/**
103	* @param mixed $value
104	* @return static
105	*/
106	public static function from($value): self
107	{
108	$key = static::assertValidValueReturningKey($value);
109
110	return self::__callStatic($key, []);
111	}
112
113	/**
114	* @psalm-pure
115	* @return mixed
116	* @psalm-return T
117	*/
118	public function getValue()
119	{
120	return $this->value;
121	}
122
123	/**
124	* Returns the enum key (i.e. the constant name).
125	*
126	* @psalm-pure
127	* @return string
128	*/
129	public function getKey()
130	{
131	return $this->key;
132	}
133
134	/**
135	* @psalm-pure
136	* @psalm-suppress InvalidCast
137	* @return string
138	*/
139	public function __toString()
140	{
141	return (string)$this->value;
142	}
143
144	/**
145	* Determines if Enum should be considered equal with the variable passed as a parameter.
146	* Returns false if an argument is an object of different class or not an object.
147	*
148	* This method is final, for more information read https://github.com/myclabs/php-enum/issues/4
149	*
150	* @psalm-pure
151	* @psalm-param mixed $variable
152	* @return bool
153	*/
154	final public function equals($variable = null): bool
155	{
156	return $variable instanceof self
157	&& $this->getValue() === $variable->getValue()
158	&& static::class === \get_class($variable);
159	}
160
161	/**
162	* Returns the names (keys) of all constants in the Enum class
163	*
164	* @psalm-pure
165	* @psalm-return list<string>
166	* @return array
167	*/
168	public static function keys()
169	{
170	return \array_keys(static::toArray());
171	}
172
173	/**
174	* Returns instances of the Enum class of all Enum constants
175	*
176	* @psalm-pure
177	* @psalm-return array<string, static>
178	* @return static[] Constant name in key, Enum instance in value
179	*/
180	public static function values()
181	{
182	$values = array();
183
184	/** @psalm-var T $value */
185	foreach (static::toArray() as $key => $value) {
186	/** @psalm-suppress UnsafeGenericInstantiation */
187	$values[$key] = new static($value);
188	}
189
190	return $values;
191	}
192
193	/**
194	* Returns all possible values as an array
195	*
196	* @psalm-pure
197	* @psalm-suppress ImpureStaticProperty
198	*
199	* @psalm-return array<string, mixed>
200	* @return array Constant name in key, constant value in value
201	*/
202	public static function toArray()
203	{
204	$class = static::class;
205
206	if (!isset(static::$cache[$class])) {
207	/** @psalm-suppress ImpureMethodCall this reflection API usage has no side-effects here */
208	$reflection = new \ReflectionClass($class);
209	/** @psalm-suppress ImpureMethodCall this reflection API usage has no side-effects here */
210	static::$cache[$class] = $reflection->getConstants();
211	}
212
213	return static::$cache[$class];
214	}
215
216	/**
217	* Check if is valid enum value
218	*
219	* @param $value
220	* @psalm-param mixed $value
221	* @psalm-pure
222	* @psalm-assert-if-true T $value
223	* @return bool
224	*/
225	public static function isValid($value)
226	{
227	return \in_array($value, static::toArray(), true);
228	}
229
230	/**
231	* Asserts valid enum value
232	*
233	* @psalm-pure
234	* @psalm-assert T $value
235	* @param mixed $value
236	*/
237	public static function assertValidValue($value): void
238	{
239	self::assertValidValueReturningKey($value);
240	}
241
242	/**
243	* Asserts valid enum value
244	*
245	* @psalm-pure
246	* @psalm-assert T $value
247	* @param mixed $value
248	* @return string
249	*/
250	private static function assertValidValueReturningKey($value): string
251	{
252	if (false === ($key = static::search($value))) {
253	throw new \UnexpectedValueException("Value '$value' is not part of the enum " . static::class);
254	}
255
256	return $key;
257	}
258
259	/**
260	* Check if is valid enum key
261	*
262	* @param $key
263	* @psalm-param string $key
264	* @psalm-pure
265	* @return bool
266	*/
267	public static function isValidKey($key)
268	{
269	$array = static::toArray();
270
271	return isset($array[$key]) \|\| \array_key_exists($key, $array);
272	}
273
274	/**
275	* Return key for value
276	*
277	* @param mixed $value
278	*
279	* @psalm-param mixed $value
280	* @psalm-pure
281	* @return string\|false
282	*/
283	public static function search($value)
284	{
285	return \array_search($value, static::toArray(), true);
286	}
287
288	/**
289	* Returns a value when called statically like so: MyEnum::SOME_VALUE() given SOME_VALUE is a class constant
290	*
291	* @param string $name
292	* @param array $arguments
293	*
294	* @return static
295	* @throws \BadMethodCallException
296	*
297	* @psalm-pure
298	*/
299	public static function __callStatic($name, $arguments)
300	{
301	$class = static::class;
302	if (!isset(self::$instances[$class][$name])) {
303	$array = static::toArray();
304	if (!isset($array[$name]) && !\array_key_exists($name, $array)) {
305	$message = "No static method or enum constant '$name' in class " . static::class;
306	throw new \BadMethodCallException($message);
307	}
308	/** @psalm-suppress UnsafeGenericInstantiation */
309	return self::$instances[$class][$name] = new static($array[$name]);
310	}
311	return clone self::$instances[$class][$name];
312	}
313
314	/**
315	* Specify data which should be serialized to JSON. This method returns data that can be serialized by json_encode()
316	* natively.
317	*
318	* @return mixed
319	* @link http://php.net/manual/en/jsonserializable.jsonserialize.php
320	*/
321	#[\ReturnTypeWillChange]
322	public function jsonSerialize()
323	{
324	return $this->getValue();
325	}
326	}
327