Download the PHP package marc-mabe/php-enum without Composer

php-enum

This is a native PHP implementation to add enumeration support to PHP. It's an abstract class that needs to be extended to use it.

What is an Enumeration?

Wikipedia

In computer programming, an enumerated type (also called enumeration or enum) is a data type consisting of a set of named values called elements, members or enumerators of the type. The enumerator names are usually identifiers that behave as constants in the language. A variable that has been declared as having an enumerated type can be assigned any of the enumerators as a value. In other words, an enumerated type has values that are different from each other, and that can be compared and assigned, but which do not have any particular concrete representation in the computer's memory; compilers and interpreters can represent them arbitrarily.

Usage

Basics

Type-Hint

Type-Hint issue

Because in normal OOP the above example allows UserStatus and types inherited from it.

Please think about the following example:

Now the setter receives a status it doesn't know about but allows it.

Solution 1: Finalize the enumeration

`

• Nice and obvious solution

• Resulting behaviour matches native enumeration implementation of most other languages (like Java)

But as this library emulates enumerations it has a few downsides:

• Enumerator values can not be used directly

  • $user->setStatus(UserStatus::ACTIVE) fails
  • $user->setStatus(UserStatus::ACTIVE()) works
• Does not help if the enumeration was defined in an external library

Solution 2: Using Enum::get()

• Makes sure the resulting enumerator exactly matches an enumeration. (Inherited enumerators are not allowed).

• Allows enumerator values directly

  • $user->setStatus(UserStatus::ACTIVE) works
  • $user->setStatus(UserStatus::ACTIVE()) works
• Also works for enumerations defined in external libraries

But of course this solution has downsides, too:

• Looses declarative type-hint

• A bit slower

EnumSet

An EnumSet is a specialized Set implementation for use with enumeration types. All of the enumerators in an EnumSet must come from a single enumeration type that is specified, when the set is created.

Enum sets are represented internally as bit vectors. The bit vector is either an integer type or a binary string type depending on how many enumerators are defined in the enumeration type. This representation is extremely compact and efficient. Bulk operations will run very quickly. Enumerators of an EnumSet are unique and ordered based on its ordinal number by design.

It implements IteratorAggregate and Countable to be directly iterable with foreach and countable with count().

The EnumSet has a mutable and an immutable interface. Mutable methods start with set, add or remove while immutable methods start with with.

EnumMap

An EnumMap maps enumerators of the same type to data assigned to.

It implements ArrayAccess, Countable and IteratorAggregate so elements can be accessed, iterated and counted like a normal array using $enumMap[$key], foreach and count().

Serializing

Because this enumeration implementation is based on a singleton pattern and in PHP it's currently impossible to unserialize a singleton without creating a new instance this feature isn't supported without any additional work.

As of it's an often requested feature there is a trait that can be added to your enumeration definition. The trait adds serialization functionallity and injects the unserialized enumeration instance in case it's the first one. This reduces singleton behavior breakage but still it beaks if it's not the first instance and you could result in two different instance of the same enumeration.

Use it with caution!

PS: EnumSet and EnumMap are serializable by default as long as you don't set other non-serializable values.

Example of using EnumSerializableTrait

Generics and Static Code Analyzer

With version 4.3 we have added support for generics and added better type support.

• EnumSet<T of Enum>
• EnumMap<T of Enum>

Generic types will be detected by PHPStan and Psalm.

Additionally, we have developed an extension for PHPStan to make enumerator accessor methods known.

Why not SplEnum

• SplEnum is not built-in into PHP and requires pecl extension installed.
• Instances of the same value of an SplEnum are not the same instance.
• No support for EnumMap or EnumSet.

Changelog

Changes are documented in the release page.

Install

Composer

Add marc-mabe/php-enum to the project's composer.json dependencies and run php composer.phar install

GIT

git clone git://github.com/marc-mabe/php-enum.git

ZIP / TAR

Download the last version from Github and extract it.

Versioning and Releases

This project follows SemVer specification.

There are no LTS releases and we don't have (fixed) time based release windows. Instead releases happen as necessary.

We do support at least all maintained PHP versions.

Bug fixes will be backported to the latest maintained minor release.

Critical bug fixes and security relates fixes can also be backported to older releases.

New BSD License

The files in this archive are released under the New BSD License. You can find a copy of this license in LICENSE.txt file.