README.rst

Enumeration type for PHP

This component provides an actual enumeration type for PHP.

Installation

This component relies on Composer for its installation.

To use the Enum Trait in your project, just add a requirement on the package:

$ php composer.php require fpoirotte/enum-trait

Usage

Use the following snippet to declare a new enumeration:

<?php

use \fpoirotte\EnumTrait;

final class FavoriteColor implements Serializable
{
    use EnumTrait;

    private $RED;
    private $BLUE;
    private $GREEN;
}

$red    = FavoriteColor::RED();
$red2   = FavoriteColor::RED();
$red3   = unserialize(serialize($red));
$red4   = clone $red;
$blue   = FavoriteColor::BLUE();

// Compare two distinct values
var_dump($red == $blue); // False

// Compare various instances of the same value
var_dump($red == $red2); // True
var_dump($red == $red3); // True
var_dump($red == $red4); // True

// Get the enum's value name
var_dump((string) $red); // "RED"

?>

Goals

This component was designed to achieve the following goals:

• Define a true type for enumerations, so they can serve as type-hints :

  <?php
  
  function displayUsingFavoriteColor(FavoriteColor $color, $message) {
      // ...
  }
  
  ?>

• Make it possible to extend an existing enum to add new values. This is made dead easy by class inheritance. Preventing this is also easy thanks to the final keyword.

• Remove the need for an actual value. Intrinsically, a label ought to be enough to figure out the meaning of a specific enum instance. This also avoids repetition.

  Say goodbye to the following idiom:

  <?php
  
  class MyEnum extends SomeInferiorEnum
  {
      const VALUE1 = 'value1';
  }
  
  ?>

• Turn enumeration values into opaque values. This is actually a consequence from the previous goal.

  This prevents developers from using the value directly, eg. if ($enumValue == 1) { /* ... */ }, which in turn prevents subtle bugs whenever the underlying value/type evolves.

• Make it possible to compare enumeration values directly, without the need for helper methods. See Usage for an example of that.

• Make it possible to easily serialize/unserialize enumerations (without requiring some helper functions).

• Make it possible to copy (clone) an enumeration value without a specific support function.

• Add no requirements on additional PHP extensions (eg. SplTypes).

Contributions

To contribute a patch:

• Fork this project
• Prepare your patch
• Submit a pull request

License

This project is released under the MIT license. See the LICENSE file for more information.