Download the PHP package geoffroy-aubry/enum without Composer

PHP Enum

This is a simple-to-use PHP class that provides the ability to emulate and create type-safe enumerations.

Table of Contents

• Introduction
  • Definition
  • SplEnum
• Features
• Requirements
• Usage
  • An enumeration
  • Magic static calls
  • Property calls approach
  • Other functionalities
• Benchmark
• Installation
• Documentation
• Copyrights & licensing
• Change log
• Continuous integration
• Git branching model

Introduction

Definition

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. — Wikipedia

SplEnum

SplEnum is not integrated to PHP, you have to install it separately: $ sudo pecl install SPL_Types.

In addition, it's not a panacea:

Features

Yet another implementation…

Several interesting type-safe enumeration's implementations already exists:

• FlorianWolters/PHP-Component-Core-Enum
• myclabs/php-enum
• eloquent/enumeration
• …

But this one provides all the following advantages:

• Type-safe enumeration.
• Whatever the definition of one or more enumerations:
  • each element object is unique under comparison operator (==)
  • and it is not possible to have 2 distincts instances of the same element, under the identity operator (===).
• Supports both static method calls (via __callStatic() magic method) and property calls.
• Property calls approach has a low overhead.
• Supports namespaces to avoid naming collisions.
• Supports autocompletion within an Integrated Development Environment (IDE).
• No need to write any method. Just a simple class with elements as properties.
• Elements cannot be cloned via the magic __clone() method.

Drawbacks:

• Elements are not immutable (but allow property calls approach with a low overhead)
• In case of exclusive property calls approach, a call to MyEnum::buildInstances(); is needed first.

Requirements

PHP >= 5.3.3

Usage

An enumeration

A simple example of enumeration:

Magic static calls

With the ColorEnum enumeration just defined:

Property calls approach

This approach is much faster than that using magic static calls (see benchmark below).

With the same ColorEnum enumeration as above:

Other functionalities

Cast to string

By default, __toString() method returns the name of the property. But it is possible to choose the string returned:

All elements

All values of enumeration can be retrieve by static values() method:

Keys can be easily listed by static keys() method:

Benchmark

All files are provided in /tests directory:

Result:

So after the one necessary call to buildInstances(), property calls approach has a low overhead compared to a simple constant class.

Installation

1. Class autoloading and dependencies are managed by Composer so install it following the instructions on Composer: Installation - *nix or just run the following command:

2. Add dependency to GAubry\Enum into require section of your composer.json:

and run php composer.phar install from the terminal into the root folder of your project.

3. Include Composer's autoloader and use the GAubry\Enum\EnumAbstract class:

Documentation

API documentation generated by ApiGen and included in the /doc/api folder.

Copyrights & licensing

Licensed under the GNU Lesser General Public License v3 (LGPL version 3). See LICENSE file for details.

Change log

See CHANGELOG file for details.

Continuous integration

Following commands are executed during each build and must report neither errors nor warnings:

• Unit tests with PHPUnit:

• Coding standards with PHP CodeSniffer:

• Code quality with PHP Mess Detector:

Git branching model

The git branching model used for development is the one described and assisted by twgit tool: https://github.com/Twenga/twgit.