Merge pull request #1 from MarkBaker/develop

New Trait for case name validation against an enum

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to `EnumHelper` will be documented in this file.
 
+## 1.0.1 - 2021-12-08
+
+- Added `EnumValidatableCase` trait, providing an `isValidCase()` method to validate a string value against the set of case names defined for an enum. 
+
 ## 1.0.0 - 2021-12-07
 
 - Initial release
+
+  Created `EnumValidatableCase` trait, providing a `fromName()` method that allows a string value which matches an enum case to be used to create an instance of that enum.

README.md

@@ -1,11 +1,17 @@
-# A trait that allows you to create an enum from a string name in PHP 8.1
+# A library of helper traits for working with PHP 8.1 enums 
 
 [![Build Status](https://github.com/MarkBaker/EnumHelper/workflows/main/badge.svg)](https://github.com/MarkBaker/EnumHelper/actions)
 [![Total Downloads](https://img.shields.io/packagist/dt/markbaker/enumhelper)](https://packagist.org/packages/markbaker/enumhelper)
 [![Latest Stable Version](https://img.shields.io/github/v/release/MarkBaker/EnumHelper)](https://packagist.org/packages/markbaker/enumhelper)
 [![License](https://img.shields.io/github/license/MarkBaker/EnumHelper)](https://packagist.org/packages/markbaker/enumhelper)
 
-This package provides a trait that allows you to create a PHP 8.1 enum from a name string.
+This package provides a series of traits that allows you to:
+ - RestorableFromName Trait
+
+   Create/restore a PHP 8.1 enum from a name string.
+ - EnumValidatableCase
+
+   Validate an enum name from a name string.
 
 ## Installation
 
@@ -17,6 +23,8 @@ composer require markbaker/enumhelper
 
 ## Usage
 
+### RestorableFromName Trait
+
 In PHP 8.1, it is possible to create a backed enum from a value using the enum's `from()` or `tryFrom()` methods.
 
 ```php
@@ -50,19 +58,49 @@ enum Suit: string
 
 $suit = Suit::Diamonds;
 
-$name = $suit->name;      // Returns 'Diamonds' 
+$suitName = $suit->name;      // Returns 'Diamonds' 
 
-$newSuit = Suit::fromName($name);
+$newSuit = Suit::fromName($suitName);
 ```
 
+An invalid name will throw an exception. Note that names are case-sensitive.
+
 This could be useful if you wanted to store the name in a database for readability (particularly appropriate for unbacked enums); then recreate the enum in the model when you load the database record.
 
 This works with both backed and unbacked enums.
 
+### EnumValidatableCase Trait
+
+Useful to validate if a name has been defined in the case set for an enum:
+
+```php
+enum Suit: string
+{
+    use EnumHelper\EnumValidatableCase;
+
+    case Hearts = 'H';
+    case Diamonds = 'D';
+    case Clubs = 'C';
+    case Spades = 'S';
+}
+
+$suit = Suit::Diamonds;
+
+$validCaseName = Suit::Hearts;
+$isCaseNameValid = Suit::isValidCase($validCaseName);      // Returns boolean true
+
+$invalidCaseName = 'HeArTs';
+$isCaseNameValid = Suit::isValidCase($invalidCaseName);    // Returns boolean false
+```
+
+Note that names are case-sensitive.
+
+This works with both backed and unbacked enums.
+
 ## Changelog
 
-Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
+Please see the [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
 
 ## License
 
-The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
+This librar is released under the MIT License (MIT). Please see [License File](LICENSE.md) for more information.

src/EnumRestorableFromName.php

@@ -4,10 +4,10 @@
 
 trait EnumRestorableFromName
 {
-    public static function fromName(string $name)
+    public static function fromName(string $name): self
     {
+        $reflector = new \ReflectionEnum(self::class);
         try {
-            $reflector = new \ReflectionEnum(self::class);
             $enumReflector = $reflector->getCase($name);
             return $enumReflector->getValue();
         } catch (\ReflectionException $e) {

src/EnumValidatableCase.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace EnumHelper;
+
+trait EnumValidatableCase
+{
+    public static function isValidCase(string $name): bool
+    {
+        $reflector = new \ReflectionEnum(self::class);
+        try {
+            $reflector->getCase($name);
+        } catch (\ReflectionException $e) {
+            return false;
+        }
+
+        return true;
+    }
+}

tests/data/BackedEnumSuit.php

@@ -3,10 +3,11 @@
 namespace EnumHelper\TestData;
 
 use EnumHelper\EnumRestorableFromName;
+use EnumHelper\EnumValidatableCase;
 
 enum BackedEnumSuit: string
 {
-    use EnumRestorableFromName;
+    use EnumRestorableFromName, EnumValidatableCase;
 
     case Clubs = 'C';
     case Diamonds = 'D';

tests/data/EnumSuit.php

@@ -3,10 +3,11 @@
 namespace EnumHelper\TestData;
 
 use EnumHelper\EnumRestorableFromName;
+use EnumHelper\EnumValidatableCase;
 
 enum EnumSuit
 {
-    use EnumRestorableFromName;
+    use EnumRestorableFromName, EnumValidatableCase;
 
     case Clubs;
     case Diamonds;

tests/src/BackedEnumSuitTest.php → tests/src/RestoreFromNameBackedEnumSuitTest.php

@@ -5,7 +5,7 @@
 use EnumHelper\TestData\BackedEnumSuit;
 use PHPUnit\Framework\TestCase;
 
-class BackedEnumSuitTest extends TestCase
+class RestoreFromNameBackedEnumSuitTest extends TestCase
 {
     /**
      * @dataProvider providerBackedEnumSuit

tests/src/EnumSuitTest.php → tests/src/RestoreFromNameEnumSuitTest.php

@@ -6,7 +6,7 @@
 use EnumHelper\TestData\NotAnEnum;
 use PHPUnit\Framework\TestCase;
 
-class EnumSuitTest extends TestCase
+class RestoreFromNameEnumSuitTest extends TestCase
 {
     /**
      * @dataProvider providerEnumSuit
@@ -29,8 +29,9 @@ public function testBackedEnumThrowsExceptionFromInvalidName()
 
     public function testFromNameThrowsExceptionIfNotEnum()
     {
+        $fqClassName = NotAnEnum::class;
         self::expectException(\Exception::class);
-        self::expectExceptionMessage('Undefined enum name');
+        self::expectExceptionMessage(sprintf('Class "%s" is not an enum', $fqClassName));
 
         NotAnEnum::fromName('Mark');
     }

tests/src/ValidateNameInBackedEnumSuitTest.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace EnumHelper\Tests;
+
+use EnumHelper\TestData\BackedEnumSuit;
+use PHPUnit\Framework\TestCase;
+
+class ValidateNameInBackedEnumSuitTest extends TestCase
+{
+    /**
+     * @dataProvider providerBackedEnumSuit
+     */
+    public function testBackedEnumValidateName(string $caseName, bool $validity)
+    {
+        $caseValidity = BackedEnumSuit::isValidCase($caseName);
+
+        self::assertSame($validity, $caseValidity);
+    }
+
+    public function providerBackedEnumSuit(): array
+    {
+        return [
+            [BackedEnumSuit::Clubs->name, true],
+            [BackedEnumSuit::Diamonds->name, true],
+            [BackedEnumSuit::Hearts->name, true],
+            [BackedEnumSuit::Spades->name, true],
+            [strtoupper(BackedEnumSuit::Hearts->name), false],
+            ['NoTrumps', false],
+            ['', false],
+        ];
+    }
+}

tests/src/ValidateNameInEnumSuitTest.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace EnumHelper\Tests;
+
+use EnumHelper\TestData\EnumSuit;
+use PHPUnit\Framework\TestCase;
+
+class ValidateNameInEnumSuitTest extends TestCase
+{
+    /**
+     * @dataProvider providerEnumSuit
+     */
+    public function testBackedEnumValidateName(string $caseName, bool $validity)
+    {
+        $caseValidity = EnumSuit::isValidCase($caseName);
+
+        self::assertSame($validity, $caseValidity);
+    }
+
+    public function providerEnumSuit(): array
+    {
+        return [
+            [EnumSuit::Clubs->name, true],
+            [EnumSuit::Diamonds->name, true],
+            [EnumSuit::Hearts->name, true],
+            [EnumSuit::Spades->name, true],
+            [strtoupper(EnumSuit::Hearts->name), false],
+            ['NoTrumps', false],
+            ['', false],
+        ];
+    }
+}