Download the PHP package cloudstek/php-enum without Composer

PHP Enum

Enumeration support for PHP.

This package adds support for enumerations to PHP, which are unfortunately not supported natively.

⚠️ Since PHP 8.1 there is finally native support for enums in PHP. Please consider upgrading to PHP 8.1+ and migrating away from this package if you require enums in your application.

Using a simple class with constants alone doesn't allow you to use type hints meaning you still have to do extensive checks whether the value is expected. This package allows you to define enumerations the same way but allows for type hinting for example your method parameter. This way you can always be sure it holds a concrete set of members and values.

Requirements

• PHP 7.1+
• Composer*

* Installation without composer is possible as the package consists of a single class, but is obviously not recommended.

Installation

Install the package through composer:

Usage

Definition

The Cloudstek\Enum\Enum base class takes care of all the work behind the scenes so all you have to do is extend your enum class from that and define your members using either properties, constants, methods or a mix of those.

Take for example this TaskStatus enum with three members: TODO, IN_PROGRESS and DONE. Each has a string value in this example but you're free to assign any kind of value you like.

The doctype is only required for autocompletion in IDEs, not for the enum to function.

Make sure you define your members as either private or protected to avoid confusion leading to direct access to a member's value instead of an instance, causing exceptions when your code expects an instance and not the value (such as the example below).

Or if you need to be more flexible, the get method will intelligently return the member by name or if an object is given, check that it's the correct type.

To read more about ways to define your members and how to name them, please see docs/definition.md.

Comparison

With enums you're always dealing with a single instance per member therefore you can compare them directly.

Inheritance

You should always define your enums as final classes to prevent other classes from inheriting from it. If you want other classes inheriting it, consider making it abstract and write final concrete classes that inherit from it.

Without making it final, your code could accept inherited enums when all you expected was the base class. This could lead to nasty bugs.

For example consider these enums:

Without making FooEnum final, your code could unintentionally accept BarEnum as well even though it is expecting FooEnum.

To prevent this and to make sure we always get FooEnum we should mark it final. Which doesn't mean it can't inherit anything else.

Now we're sure we only get instances of FooEnum.

But in case we really don't care, as long as its base type is BaseEnum, we have to change the parameter type to BaseEnum explicitly like so:

Storing data

If you store data containing an enum and you want to convert it back into an enum later, make sure to store the member name using getName() instead of storing its value. If you only care about the value, just store the value using getValue() or by casting it to a string (if possible).

Support

You can support this project by contributing to open issues, submitting pull requests, giving this project a :star: or telling your friends about it.

If you have any ideas or issues, please open up an issue!

Related projects

• spatie/enum
• myclabs/php-enum
• eloquent/enumeration