README

Library provides support of enumerable classes for PHP.

• Enumerable
  • Installation
  • Example of usage
    • Definition
    • Equality/Identity checking
    • Usage in switch-case statement
    • Serialization and Persistence
    • Extensibility
  • Run tests
  • LICENSE

Installation

Install via composer:

composer require litgroup/enumerable:^0.8.0

Example of usage

Definition

1. Create final class, which extends Enumerable;
2. For each variant of values create a static method, which will creates an instance of value. For this purpose your method must call Enumerable::createEnum() with some index of value.

Note:

• Enumerable class must be final!
• Index can be of type string or int.

Enum definition example:

namespace Acme;

use LitGroup\Enumerable\Enumerable;

final class ColorEnum extends Enumerable
{
    /**
     * @return self
     */
    public static function red()
    {
        return self::createEnum('red');
    }

    /**
     * @return self
     */
    public static function green()
    {
        return self::createEnum('green');
    }

    /**
     * @return self
     */
    public static function blue()
    {
        return self::createEnum('blue');
    }
}

Equality/Identity checking

You can use enumerable values in equality/identity expressions:

ColorEnum::red() == ColorEnum::red() // => true
ColorEnum::red() === ColorEnum::red() // => true

ColorEnum::red() == ColorEnum::blue() // => false
ColorEnum::red() === ColorEnum::blue() // => false

Note: Enumerables works as runtime constants. Therefor enumerable values can be checked on identity. And we recommend to use check on identity (===) instesd of equality (==) if possible.

Usage in switch-case statement

$color = ColorEnum::green();

switch ($color) {
    case ColorEnum::red():
        echo "Red!\n";
        break;
    case ColorEnum::green():
        echo "Green!\n";
        break;
    case ColorEnum::blue():
        echo "Blue!\n";
        break;
}

// "Green!" will be printed

Serialization and Persistence

Enumerable works as runtime-constant. Enumerable type cannot be serialized. If you need to store representation of enumerable in a database or send it via an API you can use index of enumerable value as representation.

$enum->getRawValue();

To restore an instance of enumerable type by index from database or from API-request you can use static method getValueOf() on the concrete enum-class.

$colorIndex = getFromDatabase(/* something */);

$enum = ColorEnum::getValueOf($colorIndex);

If you need to get all values of enumerable type, use static method getValues() on the concrete enum-class.

ColorEnum::getValues(); // => Returns array of ColorEnum with index as key

Extensibility

Instances of your enumerable classes can have additional behaviour if it needed. But you cannot define any public static methods with behaviour. Public static methods used only for creation of values.

Note: You cannot define any public static methods with behaviour. Public static methods used only for creation of values.

Example:

final class MergeRequestStatus extends Enumerable {

    public static function open()
    {
        return self::createEnum('open');
    }

    public static function approved()
    {
        return self::createEnum('approved');
    }

    public static function merged()
    {
        return self::createEnum('merged');
    }

    public static function declined()
    {
        return self::createEnum('declined');
    }

    /**
     * Returns true if status is final.
     *
     * @return bool
     */
    public function isFinal()
    {
        return $this === self::merged() || $this === self::declined();
    }
}

Run tests

composer install
./tests.sh

LICENSE

See LICENSE file.