Download the PHP package thunderer/platenum without Composer

Platenum

Platenum provides a flexible and feature-complete solution for enumerations (enums) in PHP with no external dependencies. The name comes from the Latin term for a Platinum chemical element.

Installation

This library is available on Packagist and can be installed with Composer in projects supporting PHP 7.1 and above:

Usage

Create a new class with members definition:

Tip: To enable autocomplete for the constant methods, include the @method declarations as shown in the listing above.

Members instances can be created using either constants methods, members names, or their values:

Enums can be compared using strict === operator or an equals() method:

Note: Strict comparison === should be always preferred. Loose == comparison will also work correctly, but it has loads of quirks.

The getValue() method returns the raw value of given instance:

enum generator

Classes can be automatically generated using built-in bin/generate utility. It accepts three parameters:

• location of its members (either constants, docblock or static),
• (fully qualified) class name, Platenum matches the namespace to your autoloading configuration and puts the file in the proper directory,
• members names with optional values where supported.

Example:

Sources

There are multiple sources from which Platenum can read enumeration members. Base EnumTrait provides all enum functionality without any source, to be defined in a static resolve() method. Each source is available both as a trait which uses EnumTrait with concrete resolve() method implementation and an abstract class based on that trait. Usage of traits is recommended as target enum classes should not have any common type hint.

In this section the StatusEnum class with two members (ACTIVE=1 and DISABLED=2) will be used as an example.

class constants

class docblock

Note: There is no way to specify members values inside docblock, therefore all members names are also their values - in this case ACTIVE='ACTIVE' and DISABLED='DISABLED'.

attributes (PHP 8.0)

Leverage PHP 8.0 features by declaring members through attributes:

static property

callback

Unlike other types, callback enum requires initialization before creating member instances. To make it ready to use, run initialize() method with a callback returning member => value mapping (similar to StaticEnumTrait). This callback will be run exactly once right before creating the first member instance:

NOTE: This type allows loading members and values mapping from virtually any external place (database, Redis, session, files, etc.). The only requirement for this callable is that it returns a proper member => value pairs.

custom source

Note: The resolve method will be called only once when the enumeration is used for the first time.

Exceptions

The library throws default PlatenumException with dedicated message for all errors happening in the enum classes. Certain situations may require a dedicated exception class and message. To redefine the exception logic, override one or more of the static methods described below:

• throwInvalidMemberException() used when enum receives an invalid enum member in any method,
• throwInvalidValueException() used when enum receives an invalid enum value in any method.

NOTE: If the overridden method won't throw an exception, the library contains a safeguard which will still throw the default one. This way a development oversight won't hide errors in your application.

Persistence

Enumerations are frequently used in entities and mapped in ORMs. Register your custom Doctrine enum type by calling dedicated PlatenumDoctrineType static method:

The alias provided as a first argument can be then used as a Doctrine type, as shown in the listings below (equivalent XML and PHP mapping):

Reasons

There are already a few enum libraries in the PHP ecosystem. Why another one? There are several reasons to do so:

Sources Platenum allows multiple sources for enumeration members. EnumTrait contains all enum functions - extend it with your custom resolve() method to create custom source. In fact, all enumeration sources in this repository are defined this way.

Features Platenum provides complete feature set for all kinds of operations on enumeration members, values, comparison, transformation, and more. Look at PhpEnumerations project to see the feature matrix created during development of this library.

Inheritance Existing solutions use inheritance for creating enum classes:

Enumerations should be represented as different types without an ability to be used interchangeably. Platenum leverages traits to provide complete class body, therefore instanceof comparison will fail as it should and there is no possibility to typehint generic LibraryEnum class to allow any enum instance there.

Comparison Creating more than one instance of certain enum value should not prohibit you from strictly comparing them like any other variable. Other solutions encourage using loose comparison (==) as the instances with the same values are not the same instances of their classes. This library guarantees that the same enum value instance will always be the same instance which can be strictly compared:

Note: If you want to prove me wrong by using reflection or other opcode modifying extensions like uopz, then save yourself that effort, you're right and I surrender.

Serialization

Platenum provides correct (de)serialization solution which preserves its single member instance guarantees.

The only exception to that guarantee is when an enum instance is unserialize()d inside another class as PHP always creates a new object there. This can be easily mitigated by fromInstance replacement helper method inside __wakeup() method which accepts its argument by reference and automatically swaps it to a correct instance:

Note that equals() method is not affected as it does not rely on the same object instance but its class and actual value inside.

License

See LICENSE file in the main directory of this library.