summaryrefslogtreecommitdiffstats
path: root/vendor/myclabs/php-enum
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/myclabs/php-enum')
-rw-r--r--vendor/myclabs/php-enum/LICENSE18
-rw-r--r--vendor/myclabs/php-enum/README.md194
-rw-r--r--vendor/myclabs/php-enum/SECURITY.md11
-rw-r--r--vendor/myclabs/php-enum/composer.json36
-rw-r--r--vendor/myclabs/php-enum/src/Enum.php318
-rw-r--r--vendor/myclabs/php-enum/src/PHPUnit/Comparator.php54
-rw-r--r--vendor/myclabs/php-enum/stubs/Stringable.php11
7 files changed, 642 insertions, 0 deletions
diff --git a/vendor/myclabs/php-enum/LICENSE b/vendor/myclabs/php-enum/LICENSE
new file mode 100644
index 0000000..d65b309
--- /dev/null
+++ b/vendor/myclabs/php-enum/LICENSE
@@ -0,0 +1,18 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 My C-Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/vendor/myclabs/php-enum/README.md b/vendor/myclabs/php-enum/README.md
new file mode 100644
index 0000000..86304d3
--- /dev/null
+++ b/vendor/myclabs/php-enum/README.md
@@ -0,0 +1,194 @@
+# PHP Enum implementation inspired from SplEnum
+
+[![GitHub Actions][GA Image]][GA Link]
+[![Latest Stable Version](https://poser.pugx.org/myclabs/php-enum/version.png)](https://packagist.org/packages/myclabs/php-enum)
+[![Total Downloads](https://poser.pugx.org/myclabs/php-enum/downloads.png)](https://packagist.org/packages/myclabs/php-enum)
+[![Psalm Shepherd][Shepherd Image]][Shepherd Link]
+
+Maintenance for this project is [supported via Tidelift](https://tidelift.com/subscription/pkg/packagist-myclabs-php-enum?utm_source=packagist-myclabs-php-enum&utm_medium=referral&utm_campaign=readme).
+
+## Why?
+
+First, and mainly, `SplEnum` is not integrated to PHP, you have to install the extension separately.
+
+Using an enum instead of class constants provides the following advantages:
+
+- You can use an enum as a parameter type: `function setAction(Action $action) {`
+- You can use an enum as a return type: `function getAction() : Action {`
+- You can enrich the enum with methods (e.g. `format`, `parse`, …)
+- You can extend the enum to add new values (make your enum `final` to prevent it)
+- You can get a list of all the possible values (see below)
+
+This Enum class is not intended to replace class constants, but only to be used when it makes sense.
+
+## Installation
+
+```
+composer require myclabs/php-enum
+```
+
+## Declaration
+
+```php
+use MyCLabs\Enum\Enum;
+
+/**
+ * Action enum
+ */
+final class Action extends Enum
+{
+ private const VIEW = 'view';
+ private const EDIT = 'edit';
+}
+```
+
+## Usage
+
+```php
+$action = Action::VIEW();
+
+// or with a dynamic key:
+$action = Action::$key();
+// or with a dynamic value:
+$action = Action::from($value);
+// or
+$action = new Action($value);
+```
+
+As you can see, static methods are automatically implemented to provide quick access to an enum value.
+
+One advantage over using class constants is to be able to use an enum as a parameter type:
+
+```php
+function setAction(Action $action) {
+ // ...
+}
+```
+
+## Documentation
+
+- `__construct()` The constructor checks that the value exist in the enum
+- `__toString()` You can `echo $myValue`, it will display the enum value (value of the constant)
+- `getValue()` Returns the current value of the enum
+- `getKey()` Returns the key of the current value on Enum
+- `equals()` Tests whether enum instances are equal (returns `true` if enum values are equal, `false` otherwise)
+
+Static methods:
+
+- `from()` Creates an Enum instance, checking that the value exist in the enum
+- `toArray()` method Returns all possible values as an array (constant name in key, constant value in value)
+- `keys()` Returns the names (keys) of all constants in the Enum class
+- `values()` Returns instances of the Enum class of all Enum constants (constant name in key, Enum instance in value)
+- `isValid()` Check if tested value is valid on enum set
+- `isValidKey()` Check if tested key is valid on enum set
+- `assertValidValue()` Assert the value is valid on enum set, throwing exception otherwise
+- `search()` Return key for searched value
+
+### Static methods
+
+```php
+final class Action extends Enum
+{
+ private const VIEW = 'view';
+ private const EDIT = 'edit';
+}
+
+// Static method:
+$action = Action::VIEW();
+$action = Action::EDIT();
+```
+
+Static method helpers are implemented using [`__callStatic()`](http://www.php.net/manual/en/language.oop5.overloading.php#object.callstatic).
+
+If you care about IDE autocompletion, you can either implement the static methods yourself:
+
+```php
+final class Action extends Enum
+{
+ private const VIEW = 'view';
+
+ /**
+ * @return Action
+ */
+ public static function VIEW() {
+ return new Action(self::VIEW);
+ }
+}
+```
+
+or you can use phpdoc (this is supported in PhpStorm for example):
+
+```php
+/**
+ * @method static Action VIEW()
+ * @method static Action EDIT()
+ */
+final class Action extends Enum
+{
+ private const VIEW = 'view';
+ private const EDIT = 'edit';
+}
+```
+
+## Native enums and migration
+Native enum arrived to PHP in version 8.1: https://www.php.net/enumerations
+If your project is running PHP 8.1+ or your library has it as a minimum requirement you should use it instead of this library.
+
+When migrating from `myclabs/php-enum`, the effort should be small if the usage was in the recommended way:
+- private constants
+- final classes
+- no method overridden
+
+Changes for migration:
+- Class definition should be changed from
+```php
+/**
+ * @method static Action VIEW()
+ * @method static Action EDIT()
+ */
+final class Action extends Enum
+{
+ private const VIEW = 'view';
+ private const EDIT = 'edit';
+}
+```
+ to
+```php
+enum Action: string
+{
+ case VIEW = 'view';
+ case EDIT = 'edit';
+}
+```
+All places where the class was used as a type will continue to work.
+
+Usages and the change needed:
+
+| Operation | myclabs/php-enum | native enum |
+|----------------------------------------------------------------|----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Obtain an instance will change from | `$enumCase = Action::VIEW()` | `$enumCase = Action::VIEW` |
+| Create an enum from a backed value | `$enumCase = new Action('view')` | `$enumCase = Action::from('view')` |
+| Get the backed value of the enum instance | `$enumCase->getValue()` | `$enumCase->value` |
+| Compare two enum instances | `$enumCase1 == $enumCase2` <br/> or <br/> `$enumCase1->equals($enumCase2)` | `$enumCase1 === $enumCase2` |
+| Get the key/name of the enum instance | `$enumCase->getKey()` | `$enumCase->name` |
+| Get a list of all the possible instances of the enum | `Action::values()` | `Action::cases()` |
+| Get a map of possible instances of the enum mapped by name | `Action::values()` | `array_combine(array_map(fn($case) => $case->name, Action::cases()), Action::cases())` <br/> or <br/> `(new ReflectionEnum(Action::class))->getConstants()` |
+| Get a list of all possible names of the enum | `Action::keys()` | `array_map(fn($case) => $case->name, Action::cases())` |
+| Get a list of all possible backed values of the enum | `Action::toArray()` | `array_map(fn($case) => $case->value, Action::cases())` |
+| Get a map of possible backed values of the enum mapped by name | `Action::toArray()` | `array_combine(array_map(fn($case) => $case->name, Action::cases()), array_map(fn($case) => $case->value, Action::cases()))` <br/> or <br/> `array_map(fn($case) => $case->value, (new ReflectionEnum(Action::class))->getConstants()))` |
+
+## Related projects
+
+- [PHP 8.1+ native enum](https://www.php.net/enumerations)
+- [Doctrine enum mapping](https://github.com/acelaya/doctrine-enum-type)
+- [Symfony ParamConverter integration](https://github.com/Ex3v/MyCLabsEnumParamConverter)
+- [PHPStan integration](https://github.com/timeweb/phpstan-enum)
+
+
+[GA Image]: https://github.com/myclabs/php-enum/workflows/CI/badge.svg
+
+[GA Link]: https://github.com/myclabs/php-enum/actions?query=workflow%3A%22CI%22+branch%3Amaster
+
+[Shepherd Image]: https://shepherd.dev/github/myclabs/php-enum/coverage.svg
+
+[Shepherd Link]: https://shepherd.dev/github/myclabs/php-enum
diff --git a/vendor/myclabs/php-enum/SECURITY.md b/vendor/myclabs/php-enum/SECURITY.md
new file mode 100644
index 0000000..8edec67
--- /dev/null
+++ b/vendor/myclabs/php-enum/SECURITY.md
@@ -0,0 +1,11 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest stable release is supported.
+
+## Reporting a Vulnerability
+
+To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security).
+
+Tidelift will coordinate the fix and disclosure.
diff --git a/vendor/myclabs/php-enum/composer.json b/vendor/myclabs/php-enum/composer.json
new file mode 100644
index 0000000..da9bf49
--- /dev/null
+++ b/vendor/myclabs/php-enum/composer.json
@@ -0,0 +1,36 @@
+{
+ "name": "myclabs/php-enum",
+ "type": "library",
+ "description": "PHP Enum implementation",
+ "keywords": ["enum"],
+ "homepage": "http://github.com/myclabs/php-enum",
+ "license": "MIT",
+ "authors": [
+ {
+ "name": "PHP Enum contributors",
+ "homepage": "https://github.com/myclabs/php-enum/graphs/contributors"
+ }
+ ],
+ "autoload": {
+ "psr-4": {
+ "MyCLabs\\Enum\\": "src/"
+ },
+ "classmap": [
+ "stubs/Stringable.php"
+ ]
+ },
+ "autoload-dev": {
+ "psr-4": {
+ "MyCLabs\\Tests\\Enum\\": "tests/"
+ }
+ },
+ "require": {
+ "php": "^7.3 || ^8.0",
+ "ext-json": "*"
+ },
+ "require-dev": {
+ "phpunit/phpunit": "^9.5",
+ "squizlabs/php_codesniffer": "1.*",
+ "vimeo/psalm": "^4.6.2"
+ }
+}
diff --git a/vendor/myclabs/php-enum/src/Enum.php b/vendor/myclabs/php-enum/src/Enum.php
new file mode 100644
index 0000000..a21936f
--- /dev/null
+++ b/vendor/myclabs/php-enum/src/Enum.php
@@ -0,0 +1,318 @@
+<?php
+/**
+ * @link http://github.com/myclabs/php-enum
+ * @license http://www.opensource.org/licenses/mit-license.php MIT (see the LICENSE file)
+ */
+
+namespace MyCLabs\Enum;
+
+/**
+ * Base Enum class
+ *
+ * Create an enum by implementing this class and adding class constants.
+ *
+ * @author Matthieu Napoli <matthieu@mnapoli.fr>
+ * @author Daniel Costa <danielcosta@gmail.com>
+ * @author Mirosław Filip <mirfilip@gmail.com>
+ *
+ * @psalm-template T
+ * @psalm-immutable
+ * @psalm-consistent-constructor
+ */
+abstract class Enum implements \JsonSerializable, \Stringable
+{
+ /**
+ * Enum value
+ *
+ * @var mixed
+ * @psalm-var T
+ */
+ protected $value;
+
+ /**
+ * Enum key, the constant name
+ *
+ * @var string
+ */
+ private $key;
+
+ /**
+ * Store existing constants in a static cache per object.
+ *
+ *
+ * @var array
+ * @psalm-var array<class-string, array<string, mixed>>
+ */
+ protected static $cache = [];
+
+ /**
+ * Cache of instances of the Enum class
+ *
+ * @var array
+ * @psalm-var array<class-string, array<string, static>>
+ */
+ protected static $instances = [];
+
+ /**
+ * Creates a new value of some type
+ *
+ * @psalm-pure
+ * @param mixed $value
+ *
+ * @psalm-param T $value
+ * @throws \UnexpectedValueException if incompatible type is given.
+ */
+ public function __construct($value)
+ {
+ if ($value instanceof static) {
+ /** @psalm-var T */
+ $value = $value->getValue();
+ }
+
+ /** @psalm-suppress ImplicitToStringCast assertValidValueReturningKey returns always a string but psalm has currently an issue here */
+ $this->key = static::assertValidValueReturningKey($value);
+
+ /** @psalm-var T */
+ $this->value = $value;
+ }
+
+ /**
+ * This method exists only for the compatibility reason when deserializing a previously serialized version
+ * that didn't had the key property
+ */
+ public function __wakeup()
+ {
+ /** @psalm-suppress DocblockTypeContradiction key can be null when deserializing an enum without the key */
+ if ($this->key === null) {
+ /**
+ * @psalm-suppress InaccessibleProperty key is not readonly as marked by psalm
+ * @psalm-suppress PossiblyFalsePropertyAssignmentValue deserializing a case that was removed
+ */
+ $this->key = static::search($this->value);
+ }
+ }
+
+ /**
+ * @param mixed $value
+ * @return static
+ */
+ public static function from($value): self
+ {
+ $key = static::assertValidValueReturningKey($value);
+
+ return self::__callStatic($key, []);
+ }
+
+ /**
+ * @psalm-pure
+ * @return mixed
+ * @psalm-return T
+ */
+ public function getValue()
+ {
+ return $this->value;
+ }
+
+ /**
+ * Returns the enum key (i.e. the constant name).
+ *
+ * @psalm-pure
+ * @return string
+ */
+ public function getKey()
+ {
+ return $this->key;
+ }
+
+ /**
+ * @psalm-pure
+ * @psalm-suppress InvalidCast
+ * @return string
+ */
+ public function __toString()
+ {
+ return (string)$this->value;
+ }
+
+ /**
+ * Determines if Enum should be considered equal with the variable passed as a parameter.
+ * Returns false if an argument is an object of different class or not an object.
+ *
+ * This method is final, for more information read https://github.com/myclabs/php-enum/issues/4
+ *
+ * @psalm-pure
+ * @psalm-param mixed $variable
+ * @return bool
+ */
+ final public function equals($variable = null): bool
+ {
+ return $variable instanceof self
+ && $this->getValue() === $variable->getValue()
+ && static::class === \get_class($variable);
+ }
+
+ /**
+ * Returns the names (keys) of all constants in the Enum class
+ *
+ * @psalm-pure
+ * @psalm-return list<string>
+ * @return array
+ */
+ public static function keys()
+ {
+ return \array_keys(static::toArray());
+ }
+
+ /**
+ * 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);
+ }
+
+ return $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
+ */
+ public static function toArray()
+ {
+ $class = static::class;
+
+ if (!isset(static::$cache[$class])) {
+ /** @psalm-suppress ImpureMethodCall this reflection API usage has no side-effects here */
+ $reflection = new \ReflectionClass($class);
+ /** @psalm-suppress ImpureMethodCall this reflection API usage has no side-effects here */
+ static::$cache[$class] = $reflection->getConstants();
+ }
+
+ return static::$cache[$class];
+ }
+
+ /**
+ * Check if is valid enum value
+ *
+ * @param $value
+ * @psalm-param mixed $value
+ * @psalm-pure
+ * @psalm-assert-if-true T $value
+ * @return bool
+ */
+ public static function isValid($value)
+ {
+ return \in_array($value, static::toArray(), true);
+ }
+
+ /**
+ * Asserts valid enum value
+ *
+ * @psalm-pure
+ * @psalm-assert T $value
+ * @param mixed $value
+ */
+ public static function assertValidValue($value): void
+ {
+ self::assertValidValueReturningKey($value);
+ }
+
+ /**
+ * Asserts valid enum value
+ *
+ * @psalm-pure
+ * @psalm-assert T $value
+ * @param mixed $value
+ * @return string
+ */
+ private static function assertValidValueReturningKey($value): string
+ {
+ if (false === ($key = static::search($value))) {
+ throw new \UnexpectedValueException("Value '$value' is not part of the enum " . static::class);
+ }
+
+ return $key;
+ }
+
+ /**
+ * Check if is valid enum key
+ *
+ * @param $key
+ * @psalm-param string $key
+ * @psalm-pure
+ * @return bool
+ */
+ public static function isValidKey($key)
+ {
+ $array = static::toArray();
+
+ return isset($array[$key]) || \array_key_exists($key, $array);
+ }
+
+ /**
+ * Return key for value
+ *
+ * @param mixed $value
+ *
+ * @psalm-param mixed $value
+ * @psalm-pure
+ * @return string|false
+ */
+ public static function search($value)
+ {
+ return \array_search($value, static::toArray(), true);
+ }
+
+ /**
+ * Returns a value when called statically like so: MyEnum::SOME_VALUE() given SOME_VALUE is a class constant
+ *
+ * @param string $name
+ * @param array $arguments
+ *
+ * @return static
+ * @throws \BadMethodCallException
+ *
+ * @psalm-pure
+ */
+ public static function __callStatic($name, $arguments)
+ {
+ $class = static::class;
+ if (!isset(self::$instances[$class][$name])) {
+ $array = static::toArray();
+ if (!isset($array[$name]) && !\array_key_exists($name, $array)) {
+ $message = "No static method or enum constant '$name' in class " . static::class;
+ throw new \BadMethodCallException($message);
+ }
+ return self::$instances[$class][$name] = new static($array[$name]);
+ }
+ return clone self::$instances[$class][$name];
+ }
+
+ /**
+ * Specify data which should be serialized to JSON. This method returns data that can be serialized by json_encode()
+ * natively.
+ *
+ * @return mixed
+ * @link http://php.net/manual/en/jsonserializable.jsonserialize.php
+ * @psalm-pure
+ */
+ #[\ReturnTypeWillChange]
+ public function jsonSerialize()
+ {
+ return $this->getValue();
+ }
+}
diff --git a/vendor/myclabs/php-enum/src/PHPUnit/Comparator.php b/vendor/myclabs/php-enum/src/PHPUnit/Comparator.php
new file mode 100644
index 0000000..b52fce3
--- /dev/null
+++ b/vendor/myclabs/php-enum/src/PHPUnit/Comparator.php
@@ -0,0 +1,54 @@
+<?php
+
+namespace MyCLabs\Enum\PHPUnit;
+
+use MyCLabs\Enum\Enum;
+use SebastianBergmann\Comparator\ComparisonFailure;
+
+/**
+ * Use this Comparator to get nice output when using PHPUnit assertEquals() with Enums.
+ *
+ * Add this to your PHPUnit bootstrap PHP file:
+ *
+ * \SebastianBergmann\Comparator\Factory::getInstance()->register(new \MyCLabs\Enum\PHPUnit\Comparator());
+ */
+final class Comparator extends \SebastianBergmann\Comparator\Comparator
+{
+ public function accepts($expected, $actual)
+ {
+ return $expected instanceof Enum && (
+ $actual instanceof Enum || $actual === null
+ );
+ }
+
+ /**
+ * @param Enum $expected
+ * @param Enum|null $actual
+ *
+ * @return void
+ */
+ public function assertEquals($expected, $actual, $delta = 0.0, $canonicalize = false, $ignoreCase = false)
+ {
+ if ($expected->equals($actual)) {
+ return;
+ }
+
+ throw new ComparisonFailure(
+ $expected,
+ $actual,
+ $this->formatEnum($expected),
+ $this->formatEnum($actual),
+ false,
+ 'Failed asserting that two Enums are equal.'
+ );
+ }
+
+ private function formatEnum(Enum $enum = null)
+ {
+ if ($enum === null) {
+ return "null";
+ }
+
+ return get_class($enum)."::{$enum->getKey()}()";
+ }
+}
diff --git a/vendor/myclabs/php-enum/stubs/Stringable.php b/vendor/myclabs/php-enum/stubs/Stringable.php
new file mode 100644
index 0000000..cf05862
--- /dev/null
+++ b/vendor/myclabs/php-enum/stubs/Stringable.php
@@ -0,0 +1,11 @@
+<?php
+
+if (\PHP_VERSION_ID < 80000 && !interface_exists('Stringable')) {
+ interface Stringable
+ {
+ /**
+ * @return string
+ */
+ public function __toString();
+ }
+}