vicgutt/php-enhanced-enum

Enhances PHP's native enums with convenient methods

v0.1.0 2022-11-05 16:24 UTC

Requires

• php: ^8.1

Requires (Dev)

• laravel/pint: ^1.0
• pestphp/pest: ^1.21
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• phpunit/phpunit: ^9.5

MIT

• Victor GUTT

• php
• enum

README

This package provides you with convenient and single purposed traits and interfaces that aims to independently enhance native PHP enums.

The provided traits are:

• VicGutt\PhpEnhancedEnum\Concerns\HasKeys
• VicGutt\PhpEnhancedEnum\Concerns\HasValues
• VicGutt\PhpEnhancedEnum\Concerns\HasEntries
• VicGutt\PhpEnhancedEnum\Concerns\IsComparable
• VicGutt\PhpEnhancedEnum\Concerns\Enumerable

The provided interfaces are:

• VicGutt\PhpEnhancedEnum\Contracts\HasKeysContract
• VicGutt\PhpEnhancedEnum\Contracts\HasValuesContract
• VicGutt\PhpEnhancedEnum\Contracts\HasEntriesContract
• VicGutt\PhpEnhancedEnum\Contracts\IsComparableContract
• VicGutt\PhpEnhancedEnum\Contracts\EnumerableContract

Note: The Enumerable trait is a compound of all the available traits and similarly, the EnumerableContract interface extends all the other interfaces.

Installation

You can install the package via composer:

composer require vicgutt/php-enhanced-enum

Usage

As the package only provides you with traits and interfaces to enhance your enums, you will need to make use of the given trait/interface pair for each of your enums.

Example:

use VicGutt\PhpEnhancedEnum\Concerns\Enumerable;
use VicGutt\PhpEnhancedEnum\Contracts\EnumerableContract;

enum MyEnum: string implements EnumerableContract
{
    use Enumerable;
    
    case CASE1 = 'case1';
    case CASE2 = 'case2';
}

From there, you will be able to use any of the provided additional methods.

Traits, interfaces and available methods

We will be using the following example enums throughout this documentation:

use VicGutt\PhpEnhancedEnum\Concerns\Enumerable;
use VicGutt\PhpEnhancedEnum\Contracts\EnumerableContract;

/**
 * A "unit enum"
 */
enum MovementsEnum implements EnumerableContract
{
    use Enumerable;

    case ME_TOO;
    case BLACK_LIVES_MATTER;
    case LGBTQ_PLUS;
    case AND_MANY_MANY_MORE;
}

/**
 * An integer typed "backed enum"
 */
enum PromiseEnum: int implements EnumerableContract
{
    use Enumerable;

    case PENDING = 1;
    case RESOLVED = 2;
    case REJECTED = 3;
}

/**
 * A string typed "backed enum"
 */
enum StatusEnum: string implements EnumerableContract
{
    use Enumerable;

    case PENDING = 'pending';
    case SUCCEEDED = 'succeeded';
    case FAILED = 'failed';
}

Note: The example enums above could each choose to make use of one, all or any of the provided traits and interfaces individually.

HasKeys

Retrieve the enum's case names.

Example:

MovementsEnum::keys(); // ['ME_TOO', 'BLACK_LIVES_MATTER', 'LGBTQ_PLUS', 'AND_MANY_MANY_MORE']
PromiseEnum::keys(); // ['PENDING', 'RESOLVED', 'REJECTED']
StatusEnum::keys(); // ['PENDING', 'SUCCEEDED', 'FAILED']

HasValues

Retrieve the enum's case values.

Example:

MovementsEnum::values(); // ['ME_TOO', 'BLACK_LIVES_MATTER', 'LGBTQ_PLUS', 'AND_MANY_MANY_MORE']
PromiseEnum::values(); // [1, 2, 3]
StatusEnum::values(); // ['pending', 'succeeded', 'failed']

Note: For "unit enum"s, as they don't technically have values, the HasValues trait will use the enum's keys as values. Thefore, the values will always be the same as the keys.

HasEntries

Retrieve the enum's keys and values.

Example:

MovementsEnum::entries(); // ['ME_TOO' => 'ME_TOO', 'BLACK_LIVES_MATTER' => 'BLACK_LIVES_MATTER', 'LGBTQ_PLUS' => 'LGBTQ_PLUS', 'AND_MANY_MANY_MORE' => 'AND_MANY_MANY_MORE']
PromiseEnum::entries(); // ['PENDING' => 1, 'RESOLVED' => 2, 'REJECTED' => 3]
StatusEnum::entries(); // ['PENDING' => 'pending', 'SUCCEEDED' => 'succeeded', 'FAILED' => 'failed']

Note: For "unit enum"s, as they don't technically have values, the HasEntries trait will use the enum's keys as values. Thefore, the values will always be the same as the keys.

IsComparable::is

Checks if a given value is equal to itself.

Example:

MovementsEnum::ME_TOO->is(MovementsEnum::ME_TOO); // true
MovementsEnum::ME_TOO->is(MovementsEnum::BLACK_LIVES_MATTER); // false
MovementsEnum::ME_TOO->is('ME_TOO'); // true
MovementsEnum::ME_TOO->is('Me_TOO'); // false
MovementsEnum::ME_TOO->is(123); // false

PromiseEnum::PENDING->is(PromiseEnum::PENDING); // true
PromiseEnum::PENDING->is(StatusEnum::PENDING); // false
PromiseEnum::PENDING->is(1); // true
PromiseEnum::PENDING->is('1'); // false
PromiseEnum::PENDING->is('yolo'); // false

StatusEnum::PENDING->is(StatusEnum::PENDING); // true
StatusEnum::PENDING->is(PromiseEnum::PENDING); // false
StatusEnum::PENDING->is('pending'); // true
StatusEnum::PENDING->is('PENDING'); // false
StatusEnum::PENDING->is(123); // false

IsComparable::isAny

Checks if any of the given values are equal to itself.

Example:

MovementsEnum::ME_TOO->isAny([MovementsEnum::ME_TOO]); // true
MovementsEnum::ME_TOO->isAny([MovementsEnum::ME_TOO, MovementsEnum::BLACK_LIVES_MATTER]); // true
MovementsEnum::ME_TOO->isAny(['ME_TOO', MovementsEnum::BLACK_LIVES_MATTER]); // true
MovementsEnum::ME_TOO->isAny(MovementsEnum::BLACK_LIVES_MATTER, 'Me_TOO', 123]); // false

PromiseEnum::PENDING->isAny([PromiseEnum::PENDING]); // true
PromiseEnum::PENDING->isAny([PromiseEnum::PENDING, MovementsEnum::BLACK_LIVES_MATTER]); // true
PromiseEnum::PENDING->isAny([1, MovementsEnum::BLACK_LIVES_MATTER]); // true
PromiseEnum::PENDING->isAny(MovementsEnum::BLACK_LIVES_MATTER, 'PENDING', 123]); // false

StatusEnum::PENDING->isAny([StatusEnum::PENDING]); // true
StatusEnum::PENDING->isAny([StatusEnum::PENDING, MovementsEnum::BLACK_LIVES_MATTER]); // true
StatusEnum::PENDING->isAny(['pending', MovementsEnum::BLACK_LIVES_MATTER]); // true
StatusEnum::PENDING->isAny(MovementsEnum::BLACK_LIVES_MATTER, 'PENDING', 123]); // false

IsComparable::isAll

Checks if all of the given values are equal to itself.

Example:

MovementsEnum::ME_TOO->isAll([MovementsEnum::ME_TOO]); // true
MovementsEnum::ME_TOO->isAll([MovementsEnum::ME_TOO, 'ME_TOO']); // true
MovementsEnum::ME_TOO->isAll([MovementsEnum::ME_TOO, 'ME_TOO', MovementsEnum::BLACK_LIVES_MATTER]); // false

PromiseEnum::PENDING->isAll([PromiseEnum::PENDING]); // true
PromiseEnum::PENDING->isAll([PromiseEnum::PENDING, 1]); // true
PromiseEnum::PENDING->isAll([PromiseEnum::PENDING, 1, MovementsEnum::BLACK_LIVES_MATTER]); // false

StatusEnum::PENDING->isAll([StatusEnum::PENDING]); // true
StatusEnum::PENDING->isAll([StatusEnum::PENDING, 'pending']); // true
StatusEnum::PENDING->isAll([StatusEnum::PENDING, 'pending', MovementsEnum::BLACK_LIVES_MATTER]); // false

Testing

composer test

Changelog

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

Contributing

If you're interested in contributing to the project, please read our contributing docs before submitting a pull request.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Victor GUTT
• All Contributors

License

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