Merge branch 'release/1.1'

Author: Ne-Lexa

README.md

@@ -18,6 +18,7 @@ Table of Contents
       * [To loop a enum object](#to-loop-a-enum-object)
       * [To compare the enum values, use === operator](#to-compare-the-enum-values-use--operator)
       * [Convert a string to enum object](#convert-a-string-to-enum-object)
+      * [Convert a value to enum object](#convert-a-value-to-enum-object)
       * [Switch case](#switch-case)
       * [Use enum in the type hint](#use-enum-in-the-type-hint)
       * [Add some logic to enum](#add-some-logic-to-enum)
@@ -98,6 +99,15 @@ $enum = UserStatus::valueOf('ACTIVE');
 assert(UserStatus::ACTIVE() === UserStatus::valueOf('ACTIVE'));
 ```
 
+## Convert a value to enum object
+```php
+$enum = UserStatus::valueOf('ACTIVE');
+$value = $enum->value();
+
+assert(UserStatus::fromValue($value) === $enum);
+assert(UserStatus::fromValue($value) === UserStatus::valueOf('ACTIVE'));
+```
+
 ## Switch case
 ```php
 $enum = UserStatus::PENDING();
@@ -322,8 +332,10 @@ abstract class Nelexa\Enum {
     final public static values ( void ) : static[]
     final public static containsKey ( string $name ) : bool
     final public static containsValue ( mixed $value [, bool $strict = true ] ) : bool
+    final public static function fromValue( mixed $value ): static
     final public ordinal ( void ) : int
     public __toString ( void ) : string
+    protected static function getEnumConstants(): array
 }
 ```
 

src/Enum.php

@@ -101,7 +101,7 @@ final public static function valueOf(string $name): self
      *
      * @return array Array of constants.
      */
-    private static function getEnumConstants(): array
+    protected static function getEnumConstants(): array
     {
         static $enumConstants = [];
         if (!isset($enumConstants[static::class])) {
@@ -168,7 +168,7 @@ final public static function containsKey(string $name): bool
     /**
      * Checks if enum contains a passed value.
      *
-     * @param mixed $value Checked value.
+     * @param string|int|float|bool|array|null $value Checked value.
      * @param bool $strict Strict check.
      *
      * @return bool Returns true if the value is defined in one of the constants.
@@ -178,6 +178,26 @@ final public static function containsValue($value, bool $strict = true): bool
         return in_array($value, self::getEnumConstants(), $strict);
     }
 
+    /**
+     * Returns first enum of the specified constant value.
+     *
+     * @param string|int|float|bool|array|null $value Checked value.
+     *
+     * @return static the enum constant of the specified constant value.
+     */
+    final public static function fromValue($value): self
+    {
+        $key = array_search($value, self::getEnumConstants(), true);
+        if ($key === false) {
+            throw new \InvalidArgumentException(sprintf(
+                'Constant value "%s" is not defined in the %s class.',
+                $value,
+                static::class
+            ));
+        }
+        return self::valueOf($key);
+    }
+
     /**
      * Returns the ordinal of this enum constant.
      *

tests/EnumTest.php

@@ -3,8 +3,8 @@
 
 namespace Nelexa\Tests;
 
-use Nelexa\Tests\Enums\ExampleEnum;
 use Nelexa\Tests\Enums\EnumExtended;
+use Nelexa\Tests\Enums\ExampleEnum;
 use Nelexa\Tests\Enums\OverrideToStringEnum;
 use PHPUnit\Framework\TestCase;
 
@@ -195,4 +195,56 @@ public function testEnumProperty(): void
 
         unset($enum->new_field_name); // __unset invoke
     }
+
+    /**
+     * @dataProvider provideEnumFromValue
+     *
+     * @param string $name
+     * @param mixed $value
+     */
+    public function testEnumFromValue(string $name, $value): void
+    {
+        $enum = ExampleEnum::valueOf($name);
+
+        $this->assertSame(ExampleEnum::fromValue($value), $enum);
+    }
+
+    /**
+     * @return array
+     */
+    public function provideEnumFromValue(): array
+    {
+        return [
+            ['VALUE_INT', ExampleEnum::VALUE_INT],
+            ['VALUE_INT_1000', ExampleEnum::VALUE_INT_1000],
+            ['VALUE_STRING', ExampleEnum::VALUE_STRING],
+            ['VALUE_BOOL_TRUE', ExampleEnum::VALUE_BOOL_TRUE],
+            ['VALUE_BOOL_FALSE', ExampleEnum::VALUE_BOOL_FALSE],
+            ['VALUE_FLOAT', ExampleEnum::VALUE_FLOAT],
+            ['VALUE_NULL', ExampleEnum::VALUE_NULL],
+            ['VALUE_EMPTY_STRING', ExampleEnum::VALUE_EMPTY_STRING],
+            ['SCALAR_EXPRESSION', ExampleEnum::SCALAR_EXPRESSION],
+            ['CONST', ExampleEnum::CONST],
+            ['PUBLIC_CONST', ExampleEnum::PUBLIC_CONST],
+            ['PRIVATE_CONST', 'private'],
+            ['PROTECTED_CONST', 'protected'],
+            ['LANG_CODES', ExampleEnum::LANG_CODES],
+            ['COUNTRY_CODES', ExampleEnum::COUNTRY_CODES],
+        ];
+    }
+
+    public function testEnumFromValueForSameValues(): void
+    {
+        $this->assertSame(ExampleEnum::fromValue(ExampleEnum::VALUE_EQUALS_1), ExampleEnum::VALUE_EQUALS_1());
+        $this->assertSame(ExampleEnum::fromValue(ExampleEnum::VALUE_EQUALS_2), ExampleEnum::VALUE_EQUALS_1());
+        $this->assertNotSame(ExampleEnum::fromValue(ExampleEnum::VALUE_EQUALS_2), ExampleEnum::VALUE_EQUALS_2());
+    }
+
+    public function testEnumFromValueIncorrectValue(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Constant value "Unknown value" is not defined');
+
+        ExampleEnum::fromValue('Unknown value');
+    }
 }