fpoirotte/enum-trait

Enumeration type for PHP using traits

v0.1.4 2017-06-11 22:43 UTC

This package is auto-updated.

Last update: 2024-10-14 06:24:16 UTC


README

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:

License

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