vjik/php-enum

PHP 5.4+ Enum implementation

PHP Enum Implementation

, _(*1)

The package implement ideas from RFC Enumerations and provide abstract class Enum that intended to create enumerated objects with support extra data and auxiliary static functions values(), cases() and isValid()., _(*2)

Requirements

• PHP 8.0 or higher.

Installation

The package could be installed with composer:, _(*3)

composer require vjik/php-enum --prefer-dist

General usage

Declaration of class

use Vjik\Enum\Enum;

/**
 * @method static self NEW()
 * @method static self PROCESS()
 * @method static self DONE()
 */
final class Status extends Enum
{
    private const NEW = 'new';
    private const PROCESS = 'process';
    private const DONE = 'done';
}

Creating an object

By static method from()

$process = Status::from('process');

On create object with invalid value throws ValueError., _(*4)

By static method tryFrom()

$process = Status::tryFrom('process'); // Status object with value "process"
$process = Status::tryFrom('not-exists'); // null

On create object with invalid value returns null., _(*5)

By static method with a name identical to the constant name

Static methods are automatically implemented to provide quick access to an enum value., _(*6)

$process = Status::PROCESS();

Getting value and name

Status::DONE()->getName(); // DONE
Status::DONE()->getValue(); // done

Class with extra data

Set data in the protected static function data() and create getters using the protected method getPropertyValue(). Also you can create getter using protected method match()., _(*7)

use Vjik\Enum\Enum;

/**
 * @method static self CREATE()
 * @method static self UPDATE()
 */
final class Action extends Enum
{
    private const CREATE = 1;
    private const UPDATE = 2;

    protected static function data(): array
    {
        return [
            self::CREATE => [
                'tip' => 'Create document',
            ],
            self::UPDATE => [
                'tip' => 'Update document',
            ],
        ];
    }

    public function getTip(): string
    {
        /** @var string */
        return $this->getPropertyValue('tip');
    }

    public function getColor(): string
    {
        return $this->match([
            self::CREATE => 'red',
            self::UPDATE => 'blue',
        ]);
    }

    public function getCode(): int
    {
        return $this->match([
            self::CREATE => 1,
        ], 99);
    }
}

Usage:, _(*8)

echo Action::CREATE()->getTip();
echo Action::CREATE()->getColor();
echo Action::CREATE()->getCode();

Auxiliary static functions

List of values values()

Returns list of values., _(*9)

// [1, 2]
Action::values(); 

List of objects cases()

Returns list of objects:, _(*10)

// [$createObject, $updateObject]
Action::cases();

Validate value isValid()

Check if value is valid on the enum set., _(*11)

Action::isValid(1); // true
Action::isValid(99); // false

Casting to string

Enum support casting to string (using magic method __toString). The value is returned as a string., _(*12)

echo Status::DONE(); // done

Testing

Unit testing

The package is tested with PHPUnit. To run tests:, _(*13)

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework. To run it:, _(*14)

./vendor/bin/infection

Static analysis

The code is statically analyzed with Psalm. To run static analysis:, _(*15)

./vendor/bin/psalm

License

The PHP Enum implementation is free software. It is released under the terms of the BSD License. Please see LICENSE for more information., _(*16)

Credits

Version 3 of this package is inspired by myclabs/php-enum., _(*17)