Download the PHP package archtechx/enums without Composer

Enums

A collection of enum helpers for PHP.

• InvokableCases
• Names
• Values
• Options
• From
• Metadata
• Comparable

You can read more about the original idea on Twitter.

Installation

PHP 8.1+ is required.

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:

Or access the underlying primitives for any other use cases:

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 ():

Apply the trait on your enum

Use static calls to get the primitive value

Invoke instances to get the primitive value

Names

This helper returns a list of case names in the enum.

Apply the trait on your enum

Use the names() method

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 the values() method

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 the options() method

stringOptions()

The trait also adds the stringOptions() method that can be used for generating convenient string representations of your enum options:

For pure enums (non-backed), the name is used in place of $value (meaning that both $name and $value are the same).

Both arguments for this method are optional, the glue defaults to \n and the callback defaults to generating HTML <option> tags:

From

This helper adds from() and tryFrom() to pure enums, and adds fromName() and tryFromName() to all enums.

Important Notes:

• BackedEnum instances already implement their own from() and tryFrom() methods, which will not be overridden by this trait. Attempting to override those methods in a BackedEnum causes a fatal error.
• Pure enums only have named cases and not values, so the from() and tryFrom() methods are functionally equivalent to fromName() and tryFromName()

Apply the trait on your enum

Use the from() method

Use the tryFrom() method

Use the fromName() method

Use the tryFromName() method

Metadata

This trait lets you add metadata to enum cases.

Apply the trait on your enum

Explanation:

• Description and Color are 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

Creating meta properties

Each meta property (= attribute used on a case) needs to exist as a class.

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:

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:

And now the returned color will be correctly transformed:

You can also add a defaultValue() method to specify the value a case should have if it doesn't use the meta property. That way you can apply the attribute only on some cases and still get a configurable default value on all other cases.

Use the fromMeta() method

Use the tryFromMeta() method

Recommendation: use annotations and traits

If you'd like to add better IDE support for the metadata getter methods, you can use @method annotations:

And if you're using the same meta property in multiple enums, you can create a dedicated trait that includes this @method annotation.

Comparable

This trait lets you compare enums using is(), isNot(), in() and notIn().

Apply the trait on your enum

Use the is() method

Use the isNot() method

Use the in() method

Use the notIn() method

PHPStan

To assist PHPStan when using invokable cases, you can include the PHPStan extensions into your own phpstan.neon file:

Development

Run all checks locally:

Code style will be automatically fixed by php-cs-fixer.