Download the PHP package dbalabka/php-enumeration without Composer

PHP Enumeration classes

Implementation of Enumeration Classes in PHP. The better alternative for Enums.

In contrast to Magic methods and Reflection to provide better performance and code autocompletion. The Enumeration class holds a reference to a single Enum element represented as an object (singleton) to provide the possiblity to use strict (===) comparision between the values. Also, it uses static properties that can utilize the power of Typed Properties. The Enumeration Classes are much closer to other language implementations like Java Enums and Python Enums.

Declaration

A basic way to declare a named Enumeration class:

Note! You should always call the Enumeration::initialize() method right after Enumeration Class declaration. To avoid manual initialization you can setup the StaticConstructorLoader provided in this library.

Declaration with Typed Properties support:

By default an enumeration class does not require the value to be provided. You can use the constructor to set any types of values.

1. Flag enum implementation example:

2. You should override initializeValues() method to set custom values for each Enum element.

Declaration rules that the developer should follow:

1. The resulting Enumeration class should be marked as final. Abstract classes should be used to share functionality between multiple Enumeration classes.

   ...Allowing subclassing of enums that define members would lead to a violation of some important invariants of types and instances. On the other hand, it makes sense to allow sharing some common behavior between a group of enumerations... (from Python Enum documentation)

2. Constructor should always be declared as non-public (private or protected) to avoid unwanted class instantiation.
3. Implementation is based on assumption that all class static properties are elements of Enum.
4. The method Dbalabka\Enumeration\Enumeration::initialize() should be called after each Enumeration class declaration. Please use the StaticConstructorLoader provided in this library to avoid boilerplate code.

Usage

Basic usage

Match expression

PHP 8 is going to support match expression which simplifies usage of enums:

More usage examples

• Static constructor usage
• Option enum similar to Rust enum
• Shape enum similar to Rust enum
• Serialization restriction
• Day enum
• Flag enum
• Planet enum

Known issues

Readonly Properties

In the current implementation, static property value can be occasionally replaced. Readonly Properties is aimed to solve this issue. In an ideal world Enum values should be declared as a constants. Unfortunately, it is not possible in PHP right now.

Also, see most recent Write-Once Properties RFC that aimed to address this issue.

Class static initialization

This implementation relies on class static initialization which was proposed in Static Class Constructor. The RFC is still in Draft status but it describes possible workarounds. The simplest way is to call the initialization method right after the class declaration, but it requires the developer to keep this in mind. Thanks to Typed Properties we can control uninitialized properties - PHP will throw an error in case of access to an uninitialized property. It might be automated with custom autoloader Dbalabka\StaticConstructorLoader\StaticConstructorLoader provided in this library:

Also, it would be very helpful to have expression based properties initialization (see C# example):

See examples/class_static_construct.php for example.

Serialization

There is no possibility to serialize the singleton. As a result, we have to restrict direct Enum object serialization.

New custom object serialization mechanism does not help with singleton serialization but it gives the possibility to control this in the class which holds the references to Enum instances. Also, it can be worked around with Serializable Interface in a similar way. For example, Java handles Enums serialization differently than other classes, but you can serialize it directly thanks to readResolve(). In PHP, we can't serialize Enums directly, but we can handle Enums serialization in class that holds the reference. We can serialize the name of the Enum constant and use valueOf() method to obtain the Enum constant value during unserialization. So this problem somewhat resolved the cost of a worse developer experience. Hope it will be solved in future RFCs.

See complete example in examples/serialization_php74.php.

Callable static properties syntax

Unfortunately, it is not easy to use callable that is stored in static property. There was a syntax change since PHP 7.0 which complicates the way to call callable.

It is the main disatvatige of static class properties.

It can be workarounded by magic calls using __callStatic but such option suffers from missing autosuggestion, negative performance impact and missing static analysis.

It would be helpful to have PHP built-in suppoort for late (in runtime) constants initialization or/and class constants initialization using simple expressions:

Still, calling Enum::FOO() will try to find a method instead of trying to treat constant's value as a callable. We assume, that such PHP behavior can be improved.

Existing solutions

Libraries:

• https://github.com/myclabs/php-enum (~1200 stars)
• https://github.com/BenSampo/laravel-enum (~700 stars)
• https://github.com/marc-mabe/php-enum (~300 stars)
• https://github.com/spatie/enum (~200 stars)
• https://github.com/Elao/PhpEnums (~100 stars)
• https://github.com/consistence/consistence#enums-and-multienums (~100 stars)
• https://github.com/mad-web/laravel-enum (~80 stars)
• https://github.com/greg0ire/enum (~40 stars)
• https://github.com/grifart/enum
• https://github.com/zlikavac32/php-enum

PHP native:

• https://www.php.net/manual/en/class.splenum.php
• PHP RFC: Enumerated Types

(there are a lot of other PHP implementations)

References

• Enum Types - The Java™ Tutorials
• Enum — Support for enumerations - The Python Standard Library
  • Class Enum<E extends Enum> - Java™ Platform, Standard Edition 7 API Specification
• Use enumeration classes instead of enum types - .NET microservices - Architecture e-book
  • Enumeration Class implementation - Microservices Architecture and Containers based Reference Application
• Python Enum is a singleton
• Java Enum is a singleton