README

Zero-dependencies PHP library to supercharge enum functionalities.

📦 Install

Via Composer:

composer require cerbero/enum

🔮 Usage

⚖️ Comparison
🏷️ Meta
🚰 Hydration
🎲 Enum operations
🧺 Cases collection
🪄 Magic
🤳 Self-awareness

To supercharge our enums with all the features provided by this package, we can let our enums use the Enumerates trait:

use Cerbero\Enum\Concerns\Enumerates;

enum PureEnum
{
    use Enumerates;

    case One;
    case Two;
    case Three;
}

enum BackedEnum: int
{
    use Enumerates;

    case One = 1;
    case Two = 2;
    case Three = 3;
}

⚖️ Comparison

We can check whether an enum includes some names or values. Pure enums check for names and backed enums check for values:

PureEnum::has('One'); // true
PureEnum::has('four'); // false
PureEnum::doesntHave('One'); // false
PureEnum::doesntHave('four'); // true

BackedEnum::has(1); // true
BackedEnum::has(4); // false
BackedEnum::doesntHave(1); // false
BackedEnum::doesntHave(4); // true

Otherwise we can check whether cases match a given name or value:

PureEnum::One->is('One'); // true
PureEnum::One->is(1); // false
PureEnum::One->is('four'); // false
PureEnum::One->isNot('One'); // false
PureEnum::One->isNot(1); // true
PureEnum::One->isNot('four'); // true

BackedEnum::One->is(1); // true
BackedEnum::One->is('1'); // false
BackedEnum::One->is(4); // false
BackedEnum::One->isNot(1); // false
BackedEnum::One->isNot('1'); // true
BackedEnum::One->isNot(4); // true

Comparisons can also be performed against arrays:

PureEnum::One->in(['One', 'four']); // true
PureEnum::One->in([1, 4]); // false
PureEnum::One->notIn(['One', 'four']); // false
PureEnum::One->notIn([1, 4]); // true

BackedEnum::One->in([1, 4]); // true
BackedEnum::One->in(['One', 'four']); // false
BackedEnum::One->notIn([1, 4]); // false
BackedEnum::One->notIn(['One', 'four']); // true

🏷️ Meta

Meta add extra information to a case. Meta can be added by implementing a public non-static method and/or by attaching #[Meta] attributes to cases:

enum BackedEnum: int
{
    use Enumerates;

    #[Meta(color: 'red', shape: 'triangle')]
    case One = 1;

    #[Meta(color: 'green', shape: 'square')]
    case Two = 2;

    #[Meta(color: 'blue', shape: 'circle')]
    case Three = 3;

    public function isOdd(): bool
    {
        return $this->value % 2 != 0;
    }
}

The above enum defines 3 meta for each case: color, shape and isOdd. The #[Meta] attributes are ideal to declare static information, whilst public non-static methods are ideal to declare dynamic information.

#[Meta] attributes can also be attached to the enum itself to provide default values when a case does not declare its own meta values:

#[Meta(color: 'red', shape: 'triangle')]
enum BackedEnum: int
{
    use Enumerates;

    case One = 1;

    #[Meta(color: 'green', shape: 'square')]
    case Two = 2;

    case Three = 3;
}

In the above example all cases have a red color and a triangle shape, except the case Two that overrides the default meta values.

Meta can also be leveraged for the hydration, elaboration and collection of cases.

🚰 Hydration

An enum case can be instantiated from its own name, value (if backed) or meta:

PureEnum::from('One'); // PureEnum::One
PureEnum::from('four'); // throws ValueError
PureEnum::tryFrom('One'); // PureEnum::One
PureEnum::tryFrom('four'); // null
PureEnum::fromName('One'); // PureEnum::One
PureEnum::fromName('four'); // throws ValueError
PureEnum::tryFromName('One'); // PureEnum::One
PureEnum::tryFromName('four'); // null
PureEnum::fromMeta('color', 'red'); // CasesCollection[PureEnum::One]
PureEnum::fromMeta('color', 'purple'); // throws ValueError
PureEnum::fromMeta('isOdd'); // CasesCollection[PureEnum::One, PureEnum::Three]
PureEnum::fromMeta('shape', fn(string $shape) => in_array($shape, ['square', 'circle'])); // CasesCollection[PureEnum::One, PureEnum::Three]
PureEnum::tryFromMeta('color', 'red'); // CasesCollection[PureEnum::One]
PureEnum::tryFromMeta('color', 'purple'); // null
PureEnum::tryFromMeta('isOdd'); // CasesCollection[PureEnum::One, PureEnum::Three]
PureEnum::tryFromMeta('shape', fn(string $shape) => in_array($shape, ['square', 'circle'])); // CasesCollection[PureEnum::One, PureEnum::Three]

BackedEnum::from(1); // BackedEnum::One
BackedEnum::from('1'); // throws ValueError
BackedEnum::tryFrom(1); // BackedEnum::One
BackedEnum::tryFrom('1'); // null
BackedEnum::fromName('One'); // BackedEnum::One
BackedEnum::fromName('four'); // throws ValueError
BackedEnum::tryFromName('One'); // BackedEnum::One
BackedEnum::tryFromName('four'); // null
BackedEnum::fromMeta('color', 'red'); // CasesCollection[BackedEnum::One]
BackedEnum::fromMeta('color', 'purple'); // throws ValueError
BackedEnum::fromMeta('isOdd'); // CasesCollection[PureEnum::One, PureEnum::Three]
BackedEnum::fromMeta('shape', fn(string $shape) => in_array($shape, ['square', 'circle'])); // CasesCollection[BackedEnum::One, BackedEnum::Three]
BackedEnum::tryFromMeta('color', 'red'); // CasesCollection[BackedEnum::One]
BackedEnum::tryFromMeta('color', 'purple'); // null
BackedEnum::tryFromMeta('isOdd'); // CasesCollection[PureEnum::One, PureEnum::Three]
BackedEnum::tryFromMeta('shape', fn(string $shape) => in_array($shape, ['square', 'circle'])); // CasesCollection[BackedEnum::One, BackedEnum::Three]

Hydrating from meta can return multiple cases. To facilitate further processing, such cases are collected into a CasesCollection.

🎲 Enum operations

A number of operations can be performed against an enum to affect all its cases:

PureEnum::collect(); // CasesCollection[PureEnum::One, PureEnum::Two, PureEnum::Three]
PureEnum::count(); // 3
PureEnum::first(); // PureEnum::One
PureEnum::first(fn(PureEnum $case,  int $key) => ! $case->isOdd()); // PureEnum::Two
PureEnum::names(); // ['One', 'Two', 'Three']
PureEnum::values(); // []
PureEnum::pluck('name'); // ['One', 'Two', 'Three']
PureEnum::pluck('color'); // ['red', 'green', 'blue']
PureEnum::pluck(fn(PureEnum $case) => $case->isOdd()); // [true, false, true]
PureEnum::pluck('color', 'shape'); // ['triangle' => 'red', 'square' => 'green', 'circle' => 'blue']
PureEnum::pluck(fn(PureEnum $case) => $case->isOdd(), fn(PureEnum $case) => $case->name); // ['One' => true, 'Two' => false, 'Three' => true]
PureEnum::map(fn(PureEnum $case, int $key) => $case->name . $key); // ['One0', 'Two1', 'Three2']
PureEnum::keyByName(); // CasesCollection['One' => PureEnum::One, 'Two' => PureEnum::Two, 'Three' => PureEnum::Three]
PureEnum::keyBy('color'); // CasesCollection['red' => PureEnum::One, 'green' => PureEnum::Two, 'blue' => PureEnum::Three]
PureEnum::keyByValue(); // CasesCollection[]
PureEnum::groupBy('color'); // CasesCollection['red' => CasesCollection[PureEnum::One], 'green' => CasesCollection[PureEnum::Two], 'blue' => CasesCollection[PureEnum::Three]]
PureEnum::filter('isOdd'); // CasesCollection[PureEnum::One, PureEnum::Three]
PureEnum::filter(fn(PureEnum $case) => $case->isOdd()); // CasesCollection[PureEnum::One, PureEnum::Three]
PureEnum::only('Two', 'Three'); // CasesCollection[PureEnum::Two, PureEnum::Three]
PureEnum::except('Two', 'Three'); // CasesCollection[PureEnum::One]
PureEnum::onlyValues(2, 3); // CasesCollection[]
PureEnum::exceptValues(2, 3); // CasesCollection[]
PureEnum::sort(); // CasesCollection[PureEnum::One, PureEnum::Three, PureEnum::Two]
PureEnum::sortBy('color'); // CasesCollection[PureEnum::Three, PureEnum::Two, PureEnum::One]
PureEnum::sortByValue(); // CasesCollection[]
PureEnum::sortDesc(); // CasesCollection[PureEnum::Two, PureEnum::Three, PureEnum::One]
PureEnum::sortByDesc(fn(PureEnum $case) => $case->color()); // CasesCollection[PureEnum::One, PureEnum::Two, PureEnum::Three]
PureEnum::sortByDescValue(); // CasesCollection[]

BackedEnum::collect(); // CasesCollection[BackedEnum::One, BackedEnum::Two, BackedEnum::Three]
BackedEnum::count(); // 3
BackedEnum::first(); // BackedEnum::One
BackedEnum::first(fn(BackedEnum $case,  int $key) => ! $case->isOdd()); // BackedEnum::Two
BackedEnum::names(); // ['One', 'Two', 'Three']
BackedEnum::values(); // [1, 2, 3]
BackedEnum::pluck('value'); // [1, 2, 3]
BackedEnum::pluck('color'); // ['red', 'green', 'blue']
BackedEnum::pluck(fn(BackedEnum $case) => $case->isOdd()); // [true, false, true]
BackedEnum::pluck('color', 'shape'); // ['triangle' => 'red', 'square' => 'green', 'circle' => 'blue']
BackedEnum::pluck(fn(BackedEnum $case) => $case->isOdd(), fn(BackedEnum $case) => $case->name); // ['One' => true, 'Two' => false, 'Three' => true]
BackedEnum::map(fn(BackedEnum $case, int $key) => $case->name . $key); // ['One0', 'Two1', 'Three2']
BackedEnum::keyByName(); // CasesCollection['One' => BackedEnum::One, 'Two' => BackedEnum::Two, 'Three' => BackedEnum::Three]
BackedEnum::keyBy('color'); // CasesCollection['red' => BackedEnum::One, 'green' => BackedEnum::Two, 'blue' => BackedEnum::Three]
BackedEnum::keyByValue(); // CasesCollection[1 => BackedEnum::One, 2 => BackedEnum::Two, 3 => BackedEnum::Three]
BackedEnum::groupBy('color'); // CasesCollection['red' => CasesCollection[BackedEnum::One], 'green' => CasesCollection[BackedEnum::Two], 'blue' => CasesCollection[BackedEnum::Three]]
BackedEnum::filter('isOdd'); // CasesCollection[BackedEnum::One, BackedEnum::Three]
BackedEnum::filter(fn(BackedEnum $case) => $case->isOdd()); // CasesCollection[BackedEnum::One, BackedEnum::Three]
BackedEnum::only('Two', 'Three'); // CasesCollection[BackedEnum::Two, BackedEnum::Three]
BackedEnum::except('Two', 'Three'); // CasesCollection[BackedEnum::One]
BackedEnum::onlyValues(2, 3); // CasesCollection[]
BackedEnum::exceptValues(2, 3); // CasesCollection['Two' => false, 'Three' => true]
BackedEnum::sort(); // CasesCollection[BackedEnum::One, BackedEnum::Three, BackedEnum::Two]
BackedEnum::sortBy('color'); // CasesCollection[BackedEnum::Three, BackedEnum::Two, BackedEnum::One]
BackedEnum::sortByValue(); // CasesCollection[BackedEnum::One, BackedEnum::Two, BackedEnum::Three]
BackedEnum::sortDesc(); // CasesCollection[BackedEnum::Two, BackedEnum::Three, BackedEnum::One]
BackedEnum::sortByDescValue(); // CasesCollection[BackedEnum::Three, BackedEnum::Two, BackedEnum::One]
BackedEnum::sortByDesc(fn(BackedEnum $case) => $case->color()); // CasesCollection[BackedEnum::One, BackedEnum::Two, BackedEnum::Three]

🧺 Cases collection

When an enum operation can return multiple cases, they are collected into a CasesCollection which provides a fluent API to perform further operations on the set of cases:

PureEnum::filter('isOdd')->sortBy('color')->pluck('color', 'name'); // ['Three' => 'blue', 'One' => 'red']

Cases can be collected by calling collect() or any other enum operation returning a CasesCollection:

PureEnum::collect(); // CasesCollection[PureEnum::One, PureEnum::Two, PureEnum::Three]

BackedEnum::only('One', 'Two'); // CasesCollection[BackedEnum::One, BackedEnum::Two]

We can iterate a cases collection within any loop:

foreach (PureEnum::collect() as $case) {
    echo $case->name;
}

All the enum operations listed above are also available when dealing with a collection of cases.

🪄 Magic

Enums can implement magic methods to be invoked or to handle calls to inaccessible methods. By default when calling an inaccessible static method, the name or value of the case matching the missing method is returned:

PureEnum::One(); // 'One'

BackedEnum::One(); // 1

To improve the autocompletion of our IDE, we can add some method annotations to our enums:

/**
 * @method static int One()
 * @method static int Two()
 * @method static int Three()
 */
enum BackedEnum: int
{
    use Enumerates;

    case One = 1;
    case Two = 2;
    case Three = 3;
}

By default, we can also obtain the name or value of a case by simply invoking it:

$case = PureEnum::One;
$case(); // 'One'

$case = BackedEnum::One;
$case(); // 1

When calling an inaccessible method of a case, by default the value of the meta matching the missing method is returned:

PureEnum::One->color(); // 'red'

BackedEnum::One->shape(); // 'triangle'

To improve the autocompletion of our IDE, we can add some method annotations to our enums:

/**
 * @method string color()
 */
enum BackedEnum: int
{
    use Enumerates;

    #[Meta(color: 'red')]
    case One = 1;

    #[Meta(color: 'green')]
    case Two = 2;

    #[Meta(color: 'blue')]
    case Three = 3;
}

Depending on our needs, we can customize the default behavior of all enums in our application when invoking a case or calling inaccessible methods:

use Cerbero\Enum\Enums;

// define the logic to run when calling an inaccessible method of an enum
Enums::onStaticCall(function(string $enum, string $name, array $arguments) {
    // $enum is the fully qualified name of the enum that called the inaccessible method
    // $name is the inaccessible method name
    // $arguments are the parameters passed to the inaccessible method
});

// define the logic to run when calling an inaccessible method of a case
Enums::onCall(function(object $case, string $name, array $arguments) {
    // $case is the instance of the case that called the inaccessible method
    // $name is the inaccessible method name
    // $arguments are the parameters passed to the inaccessible method
});

// define the logic to run when invoking a case
Enums::onInvoke(function(object $case, mixed ...$arguments) {
    // $case is the instance of the case that is being invoked
    // $arguments are the parameters passed when invoking the case
});

🤳 Self-awareness

Finally, the following methods can be useful for inspecting enums or auto-generating code:

PureEnum::isPure(); // true
PureEnum::isBacked(); // false
PureEnum::metaNames(); // ['color', 'shape', 'isOdd']
PureEnum::One->resolveItem('name'); // 'One'
PureEnum::One->resolveMeta('isOdd'); // true
PureEnum::One->resolveMetaAttribute('color'); // 'red'
PureEnum::One->value(); // 'One'

BackedEnum::isPure(); // false
BackedEnum::isBacked(); // true
BackedEnum::metaNames(); // ['color', 'shape', 'isOdd']
BackedEnum::One->resolveItem('value'); // 1
BackedEnum::One->resolveMeta('isOdd'); // true
BackedEnum::One->resolveMetaAttribute('color'); // 'red'
BackedEnum::One->value(); // 1

📆 Change log

Please see CHANGELOG for more information on what has changed recently.

🧪 Testing

composer test

💞 Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

🧯 Security

If you discover any security related issues, please email andrea.marco.sartori@gmail.com instead of using the issue tracker.

🏅 Credits

⚖️ License

The MIT License (MIT). Please see License File for more information.

cerbero / enum

Maintainers

Details