support for strict values + constants

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `Enumhancer` will be documented in this file
 
+## 1.19.0 - 2022-12-15
+
+- You can now use constants for [Mappers](docs/mappers)
+ and [Defaults](docs/defaults.md)
+- you can now flag a unit enum as `strict`, so you don't
+ have to worry about casing in [Values](docs/value.md).
+
 ## 1.18.0 - 2022-12-14
 
 - Added Magic method functionality to [State](docs/state.md)

docs/defaults.md

@@ -23,6 +23,15 @@ enum YourDefaultEnum {
     case Default;
 }
 
+enum MyDefaultConstEnum {
+    use Defaults, Makers;
+
+    case MyEnum;
+    case MyDefaultEnum;
+
+    const Default = MyDefaultEnum::MyDefaultEnum;
+}
+
 enum MyDefaultEnum {
     use Defaults, Makers;
 
@@ -54,6 +63,14 @@ YourDefaultEnum::get('unknown'); // crashes
 YourDefaultEnum::tryGet('default'); // returns YourDefaultEnum::Default
 YourDefaultEnum::tryGet('unknown'); // returns YourDefaultEnum::Default
 
+MyDefaultConstEnum::default(); //returns MyDefaultEnum::MyDefaultEnum
+MyDefaultConstEnum::MyDefaultEnum->isDefault(); // returns true
+MyDefaultConstEnum::MyDefaultEnum->isNotDefault(); // returns false
+MyDefaultConstEnum::get('default'); // MyDefaultEnum::MyDefaultEnum
+MyDefaultConstEnum::get('unknown'); // crashes
+MyDefaultConstEnum::tryGet('default'); // returns MyDefaultEnum::MyDefaultEnum
+MyDefaultConstEnum::tryGet('unknown'); // returns MyDefaultEnum::MyDefaultEnum
+
 MyDefaultEnum::default(); //returns MyDefaultEnum::MyDefaultEnum
 MyDefaultEnum::MyDefaultEnum->isDefault(); // returns true
 MyDefaultEnum::MyDefaultEnum->isNotDefault(); // returns false

docs/from.md

@@ -39,11 +39,8 @@ YourEnum::tryFrom(YourOtherEnum::MyOtherEnum); // will return null;
 
 Note: Under the hood it uses the Getters functionality, so you can use lower- and
 uppercase names, and you can also use [Mappers](mappers.md) that you have
-defined using the `mappers` method and the [Defaults](mappers.md).
-
-By default, from and tryFrom do not use [Mappers](mappers.md). But when
-an UnitEnum object is passed, it will try to map the value first. If
-no match is found, it will use the `name`.
+defined as described in [Defaults](mappers.md).
 
 Warning: Be aware that this feature will not work if you have a backed enum.
 Even when you use this trait, currently, the original methods take precedence.
+For those situations use [Getters](getters.md)

docs/getters.md

@@ -15,6 +15,8 @@ enum YourEnum: string {
 
     case ENUM = 'your_enum';
     case ENUM2 = 'your_other_enum';
+
+    const ConstantEnum = self::ENUM;
 }
 ```
 
@@ -23,6 +25,7 @@ enum YourEnum: string {
 ```php
 /** get */
 YourEnum::get('ENUM'); // returns YourEnum::ENUM
+YourEnum::get('ConstantEnum'); // returns YourEnum::ENUM
 YourEnum::get('0'); // returns YourEnum::ENUM
 YourEnum::get(0); // returns YourEnum::ENUM
 YourEnum::get('ENUM2'); // returns YourEnum::ENUM2
@@ -34,6 +37,7 @@ YourEnum::get('ENUM3'); // throws exception
 
 /** tryGet */
 YourEnum::tryGet('ENUM'); // returns YourEnum::ENUM
+YourEnum::tryGet('ConstantEnum'); // returns YourEnum::ENUM
 YourEnum::tryGet('0'); // returns YourEnum::ENUM
 YourEnum::tryGet(1); // returns YourEnum::ENUM
 YourEnum::tryGet('ENUM2'); // returns YourEnum::ENUM2

docs/mappers.md

@@ -150,6 +150,61 @@ enum YourEnum {
 }
 ```
 
+## Mapping with arrays
+
+You can specify a map just by passing an array. This way you don't
+have to create a `Mapper` class.
+
+```php
+use Henzeb\Enumhancer\Concerns\Mappers;
+
+enum Suit {
+use Mappers, Getters;
+
+    case Spades;
+    case Diamonds;
+
+    public static function mapper() : array
+    {
+        return [
+            'schoppen' => self::Spades,
+            'ruiten' => self::Diamonds
+        ];
+    }
+}
+
+Suit::get('schoppen'); // returns self::Spades
+Suit::get('ruiten'); // returns self::Diamonds
+```
+
+## Mapping with a constant
+
+You can also specify a map inside a constant. This way you don't
+need to add a static `mapper` method and this allows you to use
+[Configurable](configure.md#configuremapper) for mappers.
+
+```php
+use Henzeb\Enumhancer\Concerns\Mappers;
+
+enum Suit {
+    use Mappers, Getters;
+
+    case Spades;
+    case Diamonds;
+
+    private const MAP_SPADES = [
+        'schoppen' => self::Spades
+    ];
+
+    private const map_diamonds = [
+        'ruiten' => self::Diamonds
+    ];
+}
+
+Suit::get('schoppen'); // returns self::Spades
+Suit::get('ruiten'); // returns self::Diamonds
+```
+
 ## Flip
 
 In some cases you might want to map two enums to each other. This is already
@@ -177,7 +232,7 @@ enum Animal
     case Dog;
     case Cat;
 
-    protected static function mapper(): ?Mapper
+    protected static function mapper(): Mapper
     {
         return new AnimalMapper();
     }
@@ -190,7 +245,7 @@ enum LatinAnimalName
     case Canine;
     case Feline;
 
-    public static function mapper(): ?Mapper
+    public static function mapper(): Mapper
     {
         return AnimalMapper::flip();
     }

docs/value.md

@@ -32,3 +32,27 @@ Note: When used with a string or int backed enum, `value` will return it's
 actual value.
 
 Note: When used with an int backed enum, `key` will return the value.
+
+## Strict values
+
+By default, the value of a UnitEnum will be the lower cased value of the
+enum case. With strict, you can modify this behavior so it returns uppercase.
+
+### Strict example
+
+```php
+use Henzeb\Enumhancer\Concerns\Value;
+
+enum yourEnum {
+    use Value;
+
+    const STRICT = true;
+
+    case MY_ENUM;
+    case Other;
+
+}
+
+yourEnum::Other->value(); // returns Other
+yourEnum::MY_ENUM->value(); // returns MY_ENUM
+```

src/Concerns/ConfigureMapper.php

@@ -12,7 +12,7 @@ trait ConfigureMapper
     /**
      * @throws ReservedPropertyNameException|PropertyAlreadyStoredException
      */
-    public static function setMapper(?Mapper $mapper): void
+    public static function setMapper(Mapper|array|null $mapper): void
     {
         EnumProperties::store(
             self::class,
@@ -25,7 +25,7 @@ public static function setMapper(?Mapper $mapper): void
     /**
      * @throws ReservedPropertyNameException|PropertyAlreadyStoredException
      */
-    public static function setMapperOnce(Mapper $mapper): void
+    public static function setMapperOnce(Mapper|array $mapper): void
     {
         EnumProperties::storeOnce(
             self::class,

src/Concerns/Dropdown.php

@@ -4,6 +4,8 @@
 
 use Henzeb\Enumhancer\Helpers\EnumCheck;
 use Henzeb\Enumhancer\Helpers\EnumSubsetMethods;
+use ReflectionClass;
+use ReflectionClassConstant;
 
 /**
  * @method static array cases()

src/Concerns/Enhancers.php

@@ -6,6 +6,7 @@ trait Enhancers
 {
     use Comparison,
         Defaults,
+        Dropdown,
         From,
         Labels,
         Mappers,

src/Concerns/From.php

@@ -9,11 +9,11 @@ trait From
 {
     public static function from(UnitEnum|string $key): self
     {
-        return EnumGetters::get(static::class, $key, $key instanceof UnitEnum, true);
+        return EnumGetters::get(static::class, $key, true, true);
     }
 
     public static function tryFrom(UnitEnum|string $key): ?self
     {
-        return EnumGetters::tryGet(static::class, $key, $key instanceof UnitEnum);
+        return EnumGetters::tryGet(static::class, $key, true);
     }
 }

src/Concerns/Mappers.php

@@ -19,7 +19,7 @@ protected static function reporter(): ?Reporter
         return EnumReporter::get();
     }
 
-    protected static function mapper(): ?Mapper
+    protected static function mapper(): Mapper|array|null
     {
         return EnumProperties::get(
             self::class,
@@ -38,7 +38,7 @@ public static function make(string|int|UnitEnum|null $value, Mapper|string $mapp
         );
     }
 
-    public static function get(string|int|UnitEnum|null $value, Mapper|string $mapper = null): self
+    public static function get(string|int|UnitEnum|null $value, Mapper|string|array $mapper = null): self
     {
         return EnumGetters::get(
             self::class,
@@ -57,7 +57,7 @@ public static function tryMake(string|int|UnitEnum|null $value, Mapper|string $m
         );
     }
 
-    public static function tryGet(string|int|UnitEnum|null $value, Mapper|string $mapper = null): ?self
+    public static function tryGet(string|int|UnitEnum|null $value, Mapper|string|array $mapper = null): ?self
     {
         return EnumGetters::tryGet(
             self::class,
@@ -77,7 +77,7 @@ public static function makeArray(iterable $values, Mapper|string $mapper = null)
         );
     }
 
-    public static function getArray(iterable $values, Mapper|string $mapper = null): array
+    public static function getArray(iterable $values, Mapper|string|array $mapper = null): array
     {
         return EnumGetters::getArray(
             self::class,
@@ -96,7 +96,7 @@ public static function tryMakeArray(iterable $values, Mapper|string $mapper = nu
         );
     }
 
-    public static function tryArray(iterable $values, Mapper|string $mapper = null): array
+    public static function tryArray(iterable $values, Mapper|string|array $mapper = null): array
     {
         return EnumGetters::tryArray(
             self::class,
@@ -122,7 +122,7 @@ public static function makeOrReport(
     public static function getOrReport(
         int|string|UnitEnum|null $value,
         BackedEnum $context = null,
-        Mapper|string $mapper = null
+        Mapper|string|array $mapper = null
     ): ?self {
         return EnumReporter::getOrReport(
             self::class,
@@ -150,7 +150,7 @@ public static function makeOrReportArray(
     public static function getOrReportArray(
         iterable $values,
         BackedEnum $context = null,
-        Mapper|string $mapper = null
+        Mapper|string|array $mapper = null
     ): array {
         return EnumReporter::getOrReportArray(
             self::class,
@@ -160,7 +160,7 @@ public static function getOrReportArray(
         );
     }
 
-    public static function extract(string $text, Mapper|string $mapper = null): array
+    public static function extract(string $text, Mapper|string|array $mapper = null): array
     {
         return EnumExtractor::extract(self::class, $text, $mapper, self::mapper());
     }

src/Helpers/EnumArrayMapper.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Henzeb\Enumhancer\Helpers;
+
+use Henzeb\Enumhancer\Contracts\Mapper;
+
+class EnumArrayMapper extends Mapper
+{
+    public function __construct(private array $mappable)
+    {
+    }
+    protected function mappable(): array
+    {
+        return $this->mappable;
+    }
+}

src/Helpers/EnumExtractor.php

@@ -10,7 +10,7 @@ abstract class EnumExtractor
 {
     use Mappers;
 
-    public static function extract(string $class, string $text, Mapper|string|null ...$mappers): array
+    public static function extract(string $class, string $text, Mapper|string|array|null ...$mappers): array
     {
         EnumCheck::check($class);
 

src/Helpers/EnumGetters.php

@@ -3,6 +3,8 @@
 namespace Henzeb\Enumhancer\Helpers;
 
 use Henzeb\Enumhancer\Concerns\Getters;
+use Henzeb\Enumhancer\Concerns\Mappers;
+use ReflectionClass;
 use UnitEnum;
 use ValueError;
 use function Henzeb\Enumhancer\Functions\backingLowercase;
@@ -19,7 +21,7 @@ public static function get(
 
         if ($useMapper && EnumImplements::mappers($class)) {
             /**
-             * @var $class Getters;
+             * @var $class Mappers;
              */
             return $class::get($value);
         }
@@ -129,7 +131,11 @@ private static function match(string $class, int|string|null $value): ?UnitEnum
             return $class::cases()[$value];
         }
 
-        return self::findInCases($class, $value);
+        if (defined($class . '::' . $value) && constant($class . '::' . $value) instanceof $class) {
+            return constant($class . '::' . $value);
+        }
+
+        return self::findInCases($class, $value) ?? self::findInConstants($class, $value);
     }
 
     private static function findInCases(string $class, int|string $value): ?UnitEnum
@@ -164,4 +170,17 @@ protected static function useDefaultIf(string $class, int|string|null $value, bo
         }
         return null;
     }
+
+    private static function findInConstants(UnitEnum|string $class, int|string $value): ?UnitEnum
+    {
+        $constants = (new ReflectionClass($class))->getConstants();
+
+        foreach ($constants as $name => $constant) {
+            if ($constant instanceof $class && strtolower($name) === strtolower($value)) {
+                return $constant;
+            }
+        }
+
+        return null;
+    }
 }