Enums
A collection of enum helpers for PHP.
You can read more about the idea on Twitter. I originally wanted to include the InvokableCases helper in archtechx/helpers, but it makes more sense to make it a separate dependency and use it inside the other package.
Installation
PHP 8.1+ is required.
composer require archtechx/enums
Usage
InvokableCases
This helper lets you get the value of a backed enum, or the name of a pure enum, by "invoking" it — either statically (MyEnum::FOO() instead of MyEnum::FOO), or as an instance ($enum()).
That way, you can use enums as array keys:
'statuses' => [
TaskStatus::INCOMPLETE() => ['some configuration'],
TaskStatus::COMPLETED() => ['some configuration'],
],
Or access the underlying primitives for any other use cases:
public function updateStatus(int $status): void;
$task->updateStatus(TaskStatus::COMPLETED());
The main point: this is all without having to append ->value to everything.
This approach also has decent IDE support. You get autosuggestions while typing, and then you just append ():
MyEnum::FOO; // => MyEnum instance
MyEnum::FOO(); // => 1
Apply the trait on your enum
use ArchTech\Enums\InvokableCases;
enum TaskStatus: int
{
use InvokableCases;
case INCOMPLETE = 0;
case COMPLETED = 1;
case CANCELED = 2;
}
enum Role
{
use InvokableCases;
case ADMINISTRATOR;
case SUBSCRIBER;
case GUEST;
}
Use static calls to get the primitive value
TaskStatus::INCOMPLETE(); // 0
TaskStatus::COMPLETED(); // 1
TaskStatus::CANCELED(); // 2
Role::ADMINISTRATOR(); // 'ADMINISTRATOR'
Role::SUBSCRIBER(); // 'SUBSCRIBER'
Role::GUEST(); // 'GUEST'
Invoke instances to get the primitive value
public function updateStatus(TaskStatus $status, Role $role)
{
$this->record->setStatus($status(), $role());
}
Names
This helper returns a list of case names in the enum.
Apply the trait on your enum
use ArchTech\Enums\Names;
enum TaskStatus: int
{
use Names;
case INCOMPLETE = 0;
case COMPLETED = 1;
case CANCELED = 2;
}
enum Role
{
use Names;
case ADMINISTRATOR;
case SUBSCRIBER;
case GUEST;
}
Use the names() method
TaskStatus::names(); // ['INCOMPLETE', 'COMPLETED', 'CANCELED']
Role::names(); // ['ADMINISTRATOR', 'SUBSCRIBER', 'GUEST']
Values
This helper returns a list of case values for backed enums, or a list of case names for pure enums (making this functionally equivalent to ::names() for pure Enums)
Apply the trait on your enum
use ArchTech\Enums\Values;
enum TaskStatus: int
{
use Values;
case INCOMPLETE = 0;
case COMPLETED = 1;
case CANCELED = 2;
}
enum Role
{
use Values;
case ADMINISTRATOR;
case SUBSCRIBER;
case GUEST;
}
Use the values() method
TaskStatus::values(); // [0, 1, 2]
Role::values(); // ['ADMINISTRATOR', 'SUBSCRIBER', 'GUEST']
Options
This helper returns an associative array of case names and values for backed enums, or a list of names for pure enums (making this functionally equivalent to ::names() for pure Enums).
Apply the trait on your enum
use ArchTech\Enums\Options;
enum TaskStatus: int
{
use Options;
case INCOMPLETE = 0;
case COMPLETED = 1;
case CANCELED = 2;
}
enum Role
{
use Options;
case ADMINISTRATOR;
case SUBSCRIBER;
case GUEST;
}
Use the options() method
TaskStatus::options(); // ['INCOMPLETE' => 0, 'COMPLETED' => 1, 'CANCELED' => 2]
Role::options(); // ['ADMINISTRATOR', 'SUBSCRIBER', 'GUEST']
From
This helper adds from() and tryFrom() to pure enums, and adds fromName() and tryFromName() to all enums.
Important Notes:
BackedEnuminstances already implement their ownfrom()andtryFrom()methods, which will not be overridden by this trait. Attempting to override those methods in aBackedEnumcauses a fatal error.- Pure enums only have named cases and not values, so the
from()andtryFrom()methods are functionally equivalent tofromName()andtryFromName()
Apply the trait on your enum
use ArchTech\Enums\From;
enum TaskStatus: int
{
use From;
case INCOMPLETE = 0;
case COMPLETED = 1;
case CANCELED = 2;
}
enum Role
{
use From;
case ADMINISTRATOR;
case SUBSCRIBER;
case GUEST;
}
Use the from() method
Role::from('ADMINISTRATOR'); // Role::ADMINISTRATOR
Role::from('NOBODY'); // Error: ValueError
Use the tryFrom() method
Role::tryFrom('GUEST'); // Role::GUEST
Role::tryFrom('NEVER'); // null
Use the fromName() method
TaskStatus::fromName('INCOMPLETE'); // TaskStatus::INCOMPLETE
TaskStatus::fromName('MISSING'); // Error: ValueError
Role::fromName('SUBSCRIBER'); // Role::SUBSCRIBER
Role::fromName('HACKER'); // Error: ValueError
Use the tryFromName() method
TaskStatus::tryFromName('COMPLETED'); // TaskStatus::COMPLETED
TaskStatus::tryFromName('NOTHING'); // null
Role::tryFromName('GUEST'); // Role::GUEST
Role::tryFromName('TESTER'); // null
Metadata
This trait lets you add metadata to enum cases.
Apply the trait on your enum
use ArchTech\Enums\Metadata;
use ArchTech\Enums\Meta\Meta;
use App\Enums\MetaProperties\{Description, Color};
#[Meta(Description::class, Color::class)]
enum TaskStatus: int
{
use Metadata;
#[Description('Incomplete Task')] #[Color('red')]
case INCOMPLETE = 0;
#[Description('Completed Task')] #[Color('green')]
case COMPLETED = 1;
#[Description('Canceled Task')] #[Color('gray')]
case CANCELED = 2;
}
Explanation:
DescriptionandColorare userland class attributes — meta properties- The
#[Meta]call enables those two meta properties on the enum - Each case must have a defined description & color (in this example)
Access the metadata
TaskStatus::INCOMPLETE->description(); // 'Incomplete Task'
TaskStatus::COMPLETED->color(); // 'green'
Creating meta properties
Each meta property (= attribute used on a case) needs to exist as a class.
#[Attribute]
class Color extends MetaProperty {}
#[Attribute]
class Description extends MetaProperty {}
Inside the class, you can customize a few things. For instance, you may want to use a different method name than the one derived from the class name (Description becomes description() by default). To do that, override the method() method on the meta property:
#[Attribute]
class Description extends MetaProperty
{
public static function method(): string
{
return 'note';
}
}
With the code above, the description of a case will be accessible as TaskStatus::INCOMPLETE->note().
Another thing you can customize is the passed value. For instance, to wrap a color name like text-{$color}-500, you'd add the following transform() method:
#[Attribute]
class Color extends MetaProperty
{
protected function transform(mixed $value): mixed
{
return "text-{$color}-500";
}
}
And now the returned color will be correctly transformed:
TaskStatus::COMPLETED->color(); // 'text-green-500'
Use the fromMeta() method
TaskStatus::fromMeta(Color::make('green')); // TaskStatus::COMPLETED
TaskStatus::fromMeta(Color::make('blue')); // Error: ValueError
Use the tryFromMeta() method
TaskStatus::tryFromMeta(Color::make('green')); // TaskStatus::COMPLETED
TaskStatus::tryFromMeta(Color::make('blue')); // null
Recommendation: use annotations and traits
If you'd like to add better IDE support for the metadata getter methods, you can use @method annotations:
/**
* @method string description()
* @method string color()
*/
#[Meta(Description::class, Color::class)]
enum TaskStatus: int
{
use Metadata;
#[Description('Incomplete Task')] #[Color('red')]
case INCOMPLETE = 0;
#[Description('Completed Task')] #[Color('green')]
case COMPLETED = 1;
#[Description('Canceled Task')] #[Color('gray')]
case CANCELED = 2;
}
And if you're using the same meta property in multiple enums, you can create a dedicated trait that includes this @method annotation.
Development
Run all checks locally:
./check
Code style will be automatically fixed by php-cs-fixer.
14 Dec 15, 2022
295 Dec 20, 2022
5 Apr 17, 2022
69 Dec 23, 2022
2 Apr 25, 2022
2 Nov 15, 2022
2 Aug 18, 2021
3 Oct 10, 2021
1 Jan 3, 2022
197 Dec 6, 2022
29 Nov 27, 2022
14 Dec 6, 2022
3 Apr 18, 2022
14 Aug 31, 2022
2 Mar 8, 2022
1 Mar 29, 2022
4 Jul 2, 2022
5 Dec 5, 2022
30 Aug 8, 2022