From a4c54edb2437c1a572729c53241496b304182a02 Mon Sep 17 00:00:00 2001 From: MarkBaker Date: Wed, 8 Dec 2021 15:00:36 +0100 Subject: [PATCH 1/2] Minor tweaks and renaming tests --- license.md => LICENSE.md | 0 README.md | 6 +++--- src/EnumRestorableFromName.php | 4 ++-- ...umSuitTest.php => RestoreFromNameBackedEnumSuitTest.php} | 2 +- .../{EnumSuitTest.php => RestoreFromNameEnumSuitTest.php} | 5 +++-- 5 files changed, 9 insertions(+), 8 deletions(-) rename license.md => LICENSE.md (100%) rename tests/src/{BackedEnumSuitTest.php => RestoreFromNameBackedEnumSuitTest.php} (93%) rename tests/src/{EnumSuitTest.php => RestoreFromNameEnumSuitTest.php} (84%) diff --git a/license.md b/LICENSE.md similarity index 100% rename from license.md rename to LICENSE.md diff --git a/README.md b/README.md index 5f0d625..476e4f9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# A trait that allows you to create an enum from a string name in PHP 8.1 +# A trait that allows you to create an enum from a name string in PHP 8.1 [![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) @@ -61,8 +61,8 @@ 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. \ No newline at end of file +This librar is released under the MIT License (MIT). Please see [License File](LICENSE.md) for more information. \ No newline at end of file diff --git a/src/EnumRestorableFromName.php b/src/EnumRestorableFromName.php index 87191f5..91c3f3d 100644 --- a/src/EnumRestorableFromName.php +++ b/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) { diff --git a/tests/src/BackedEnumSuitTest.php b/tests/src/RestoreFromNameBackedEnumSuitTest.php similarity index 93% rename from tests/src/BackedEnumSuitTest.php rename to tests/src/RestoreFromNameBackedEnumSuitTest.php index cfd2bf4..15e3502 100644 --- a/tests/src/BackedEnumSuitTest.php +++ b/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 diff --git a/tests/src/EnumSuitTest.php b/tests/src/RestoreFromNameEnumSuitTest.php similarity index 84% rename from tests/src/EnumSuitTest.php rename to tests/src/RestoreFromNameEnumSuitTest.php index 27a38aa..a819e3f 100644 --- a/tests/src/EnumSuitTest.php +++ b/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'); } From a695bf9a81f107dd796b68f8b8ed770d750cb963 Mon Sep 17 00:00:00 2001 From: MarkBaker Date: Wed, 8 Dec 2021 17:08:33 +0100 Subject: [PATCH 2/2] Addition of the EnumValidatableCase Trait --- CHANGELOG.md | 6 +++ README.md | 46 +++++++++++++++++-- src/EnumValidatableCase.php | 18 ++++++++ tests/data/BackedEnumSuit.php | 3 +- tests/data/EnumSuit.php | 3 +- .../src/ValidateNameInBackedEnumSuitTest.php | 32 +++++++++++++ tests/src/ValidateNameInEnumSuitTest.php | 32 +++++++++++++ 7 files changed, 134 insertions(+), 6 deletions(-) create mode 100644 src/EnumValidatableCase.php create mode 100644 tests/src/ValidateNameInBackedEnumSuitTest.php create mode 100644 tests/src/ValidateNameInEnumSuitTest.php diff --git a/CHANGELOG.md b/CHANGELOG.md index e424fdf..57c5577 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index 476e4f9..8b1e4c2 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,17 @@ -# A trait that allows you to create an enum from a name string 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,15 +58,45 @@ 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 the [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. diff --git a/src/EnumValidatableCase.php b/src/EnumValidatableCase.php new file mode 100644 index 0000000..f9e7e86 --- /dev/null +++ b/src/EnumValidatableCase.php @@ -0,0 +1,18 @@ +getCase($name); + } catch (\ReflectionException $e) { + return false; + } + + return true; + } +} diff --git a/tests/data/BackedEnumSuit.php b/tests/data/BackedEnumSuit.php index a127b97..2d61d43 100644 --- a/tests/data/BackedEnumSuit.php +++ b/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'; diff --git a/tests/data/EnumSuit.php b/tests/data/EnumSuit.php index 260aea8..4b56c32 100644 --- a/tests/data/EnumSuit.php +++ b/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; diff --git a/tests/src/ValidateNameInBackedEnumSuitTest.php b/tests/src/ValidateNameInBackedEnumSuitTest.php new file mode 100644 index 0000000..4d248d8 --- /dev/null +++ b/tests/src/ValidateNameInBackedEnumSuitTest.php @@ -0,0 +1,32 @@ +name, true], + [BackedEnumSuit::Diamonds->name, true], + [BackedEnumSuit::Hearts->name, true], + [BackedEnumSuit::Spades->name, true], + [strtoupper(BackedEnumSuit::Hearts->name), false], + ['NoTrumps', false], + ['', false], + ]; + } +} diff --git a/tests/src/ValidateNameInEnumSuitTest.php b/tests/src/ValidateNameInEnumSuitTest.php new file mode 100644 index 0000000..f516cf4 --- /dev/null +++ b/tests/src/ValidateNameInEnumSuitTest.php @@ -0,0 +1,32 @@ +name, true], + [EnumSuit::Diamonds->name, true], + [EnumSuit::Hearts->name, true], + [EnumSuit::Spades->name, true], + [strtoupper(EnumSuit::Hearts->name), false], + ['NoTrumps', false], + ['', false], + ]; + } +}