Coder Social home page Coder Social logo

enum's Introduction

๐ŸŽฒ Enum

Author PHP Version Build Status Coverage Status Quality Score Latest Version Software License PSR-12 Total Downloads

Zero-dependencies PHP library to supercharge enum functionalities. Similar libraries worth mentioning are:

๐Ÿ“ฆ Install

Via Composer:

composer require cerbero/enum

๐Ÿ”ฎ Usage

To supercharge our enums with all functionalities provided by this package, we can simply use the Enumerates trait in both pure enums and backed enums:

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;
}

Classification

These methods determine whether an enum is pure or backed:

PureEnum::isPure(); // true
PureEnum::isBacked(); // false

BackedEnum::isPure(); // false
BackedEnum::isBacked(); // true

Comparison

We can check whether an enum includes some names or values. Pure enums check for names, whilst 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 let cases determine whether they match with a name or a 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 within 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

Keys resolution

With the term "key" we refer to any element defined in an enum, such as names, values or methods implemented by cases. Take the following enum for example:

enum BackedEnum: int
{
    use Enumerates;

    case one = 1;
    case two = 2;
    case three = 3;

    public function color(): string
    {
        return match ($this) {
            static::one => 'red',
            static::two => 'green',
            static::three => 'blue',
        };
    }

    public function isOdd(): bool
    {
        return match ($this) {
            static::one => true,
            static::two => false,
            static::three => true,
        };
    }
}

The keys defined in this enum are name, value (as it is a backed enum), color and isOdd. We can retrieve any key assigned to a case by calling get():

PureEnum::one->get('name'); // 'one'
PureEnum::one->get('value'); // throws ValueError as it is a pure enum
PureEnum::one->get('color'); // 'red'
PureEnum::one->get(fn (PureEnum $caseOne) => $caseOne->isOdd()); // true

BackedEnum::one->get('name'); // 'one'
BackedEnum::one->get('value'); // 1
BackedEnum::one->get('color'); // 'red'
BackedEnum::one->get(fn (BackedEnum $caseOne) => $caseOne->isOdd()); // true

At first glance this method may seem an overkill as "keys" can be accessed directly by cases like this:

BackedEnum::one->name; // 'one'
BackedEnum::one->value; // 1
BackedEnum::one->color(); // 'red'
BackedEnum::one->isOdd(); // true

However get() is useful to resolve keys dynamically as a key may be a property, a method or a closure. It often gets called internally for more advanced functionalities that we are going to explore very soon.

Hydration

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

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::fromKey('name', 'one'); // CasesCollection<PureEnum::one>
PureEnum::fromKey('value', 1); // throws ValueError
PureEnum::fromKey('color', 'red'); // CasesCollection<PureEnum::one>
PureEnum::fromKey(fn (PureEnum $case) => $case->isOdd(), true); // CasesCollection<PureEnum::one, PureEnum::three>
PureEnum::tryFromKey('name', 'one'); // CasesCollection<PureEnum::one>
PureEnum::tryFromKey('value', 1); // null
PureEnum::tryFromKey('color', 'red'); // CasesCollection<PureEnum::one>
PureEnum::tryFromKey(fn (PureEnum $case) => $case->isOdd(), true); // 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::fromKey('name', 'one'); // CasesCollection<BackedEnum::one>
BackedEnum::fromKey('value', 1); // CasesCollection<BackedEnum::one>
BackedEnum::fromKey('color', 'red'); // CasesCollection<BackedEnum::one>
BackedEnum::fromKey(fn (BackedEnum $case) => $case->isOdd(), true); // CasesCollection<BackedEnum::one, BackedEnum::three>
BackedEnum::tryFromKey('name', 'one'); // CasesCollection<BackedEnum::one>
BackedEnum::tryFromKey('value', 1); // CasesCollection<BackedEnum::one>
BackedEnum::tryFromKey('color', 'red'); // CasesCollection<BackedEnum::one>
BackedEnum::tryFromKey(fn (BackedEnum $case) => $case->isOdd(), true); // CasesCollection<BackedEnum::one, BackedEnum::three>

While pure enums try to hydrate cases from names, backed enums can hydrate from both names and values. Even keys can be used to hydrate cases, cases are then wrapped into a CasesCollection to allow further processing.

Elaborating cases

There is a bunch of operations that can be performed on the cases of an enum. If the result of an operation is a plain list of cases, they get wrapped into a CasesCollection for additional elaboration, otherwise the final result of the operation is returned:

PureEnum::collect(); // CasesCollection<PureEnum::one, PureEnum::two, PureEnum::three>
PureEnum::count(); // 3
PureEnum::casesByName(); // ['one' => PureEnum::one, 'two' => PureEnum::two, 'three' => PureEnum::three]
PureEnum::casesByValue(); // []
PureEnum::casesBy('color'); // ['red' => PureEnum::one, 'green' => PureEnum::two, 'blue' => PureEnum::three]
PureEnum::groupBy('color'); // ['red' => [PureEnum::one], 'green' => [PureEnum::two], 'blue' => [PureEnum::three]]
PureEnum::names(); // ['one', 'two', 'three']
PureEnum::values(); // []
PureEnum::pluck(); // ['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::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::sortDesc(); // CasesCollection<PureEnum::two, PureEnum::three, PureEnum::one>
PureEnum::sortByValue(); // CasesCollection<>
PureEnum::sortDescByValue(); // CasesCollection<>
PureEnum::sortBy('color'); // CasesCollection<PureEnum::three, PureEnum::two, PureEnum::one>
PureEnum::sortDescBy(fn (PureEnum $case) => $case->color()); // CasesCollection<PureEnum::one, PureEnum::two, PureEnum::three>

BackedEnum::collect(); // CasesCollection<BackedEnum::one, BackedEnum::two, BackedEnum::three>
BackedEnum::count(); // 3
BackedEnum::casesByName(); // ['one' => BackedEnum::one, 'two' => BackedEnum::two, 'three' => BackedEnum::three]
BackedEnum::casesByValue(); // [1 => BackedEnum::one, 2 => BackedEnum::two, 3 => BackedEnum::three]
BackedEnum::casesBy('color'); // ['red' => BackedEnum::one, 'green' => BackedEnum::two, 'blue' => BackedEnum::three]
BackedEnum::groupBy('color'); // ['red' => [BackedEnum::one], 'green' => [BackedEnum::two], 'blue' => [BackedEnum::three]]
BackedEnum::names(); // ['one', 'two', 'three']
BackedEnum::values(); // [1, 2, 3]
BackedEnum::pluck(); // [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, 
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::sortDesc(); // CasesCollection<BackedEnum::two, BackedEnum::three, BackedEnum::one>
BackedEnum::sortByValue(); // CasesCollection<BackedEnum::one, BackedEnum::two, BackedEnum::three>
BackedEnum::sortDescByValue(); // CasesCollection<BackedEnum::three, BackedEnum::two, BackedEnum::one>
BackedEnum::sortBy('color'); // CasesCollection<BackedEnum::three, BackedEnum::two, BackedEnum::one>
BackedEnum::sortDescBy(fn (BackedEnum $case) => $case->color()); // CasesCollection<BackedEnum::one, BackedEnum::two, BackedEnum::three>

Cases collection

When a plain list of cases is returned by one of the cases operations, it gets wrapped 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 cases 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 cases collections within any loop:

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

Obtaining the underlying plain list of cases is easy:

PureEnum::collect()->cases(); // [PureEnum::one, PureEnum::two, PureEnum::three]

Sometimes we may need to extract only the first case of the collection:

PureEnum::filter(fn (PureEnum $case) => !$case->isOdd())->first(); // PureEnum::two

For reference, here are all the operations available in CasesCollection:

PureEnum::collect()->cases(); // [PureEnum::one, PureEnum::two, PureEnum::three]
PureEnum::collect()->count(); // 3
PureEnum::collect()->first(); // PureEnum::one
PureEnum::collect()->keyByName(); // ['one' => PureEnum::one, 'two' => PureEnum::two, 'three' => PureEnum::three]
PureEnum::collect()->keyByValue(); // []
PureEnum::collect()->keyBy('color'); // ['red' => PureEnum::one, 'green' => PureEnum::two, 'blue' => PureEnum::three]
PureEnum::collect()->groupBy('color'); // ['red' => [PureEnum::one], 'green' => [PureEnum::two], 'blue' => [PureEnum::three]]
PureEnum::collect()->names(); // ['one', 'two', 'three']
PureEnum::collect()->values(); // []
PureEnum::collect()->pluck(); // ['one', 'two', 'three']
PureEnum::collect()->pluck('color'); // ['red', 'green', 'blue']
PureEnum::collect()->pluck(fn (PureEnum $case) => $case->isOdd()); // [true, false, true]
PureEnum::collect()->pluck('color', 'shape'); // ['triangle' => 'red', 'square' => 'green', 'circle' => 'blue']
PureEnum::collect()->pluck(fn (PureEnum $case) => $case->isOdd(), fn (PureEnum $case) => $case->name); // ['one' => true, 'two' => false, 'three' => true]
PureEnum::collect()->filter('isOdd'); // CasesCollection<PureEnum::one, PureEnum::three>
PureEnum::collect()->filter(fn (PureEnum $case) => $case->isOdd()); // CasesCollection<PureEnum::one, PureEnum::three>
PureEnum::collect()->only('two', 'three'); // CasesCollection<PureEnum::two, PureEnum::three>
PureEnum::collect()->except('two', 'three'); // CasesCollection<PureEnum::one>
PureEnum::collect()->onlyValues(2, 3); // CasesCollection<>
PureEnum::collect()->exceptValues(2, 3); // CasesCollection<>
PureEnum::collect()->sort(); // CasesCollection<PureEnum::one, PureEnum::three, PureEnum::two>
PureEnum::collect()->sortDesc(); // CasesCollection<PureEnum::two, PureEnum::three, PureEnum::one>
PureEnum::collect()->sortByValue(); // CasesCollection<>
PureEnum::collect()->sortDescByValue(); // CasesCollection<>
PureEnum::collect()->sortBy('color'); // CasesCollection<PureEnum::three, PureEnum::two, PureEnum::one>
PureEnum::collect()->sortDescBy(fn (PureEnum $case) => $case->color()); // CasesCollection<PureEnum::one, PureEnum::two, PureEnum::three>

BackedEnum::collect()->cases(); // [BackedEnum::one, BackedEnum::two, BackedEnum::three]
BackedEnum::collect()->count(); // 3
BackedEnum::collect()->first(); // BackedEnum::one
BackedEnum::collect()->keyByName(); // ['one' => BackedEnum::one, 'two' => BackedEnum::two, 'three' => BackedEnum::three]
BackedEnum::collect()->keyByValue(); // [1 => BackedEnum::one, 2 => BackedEnum::two, 3 => BackedEnum::three]
BackedEnum::collect()->keyBy('color'); // ['red' => BackedEnum::one, 'green' => BackedEnum::two, 'blue' => BackedEnum::three]
BackedEnum::collect()->groupBy('color'); // ['red' => [BackedEnum::one], 'green' => [BackedEnum::two], 'blue' => [BackedEnum::three]]
BackedEnum::collect()->names(); // ['one', 'two', 'three']
BackedEnum::collect()->values(); // [1, 2, 3]
BackedEnum::collect()->pluck(); // [1, 2, 3]
BackedEnum::collect()->pluck('color'); // ['red', 'green', 'blue']
BackedEnum::collect()->pluck(fn (BackedEnum $case) => $case->isOdd()); // [true, false, true]
BackedEnum::collect()->pluck('color', 'shape'); // ['triangle' => 'red', 'square' => 'green', 'circle' => 'blue']
BackedEnum::collect()->pluck(fn (BackedEnum $case) => $case->isOdd(), fn (BackedEnum $case) => $case->name); // ['one' => true, 'two' => false, 'three' => true]
BackedEnum::collect()->filter('isOdd'); // CasesCollection<BackedEnum::one, BackedEnum::three>
BackedEnum::collect()->filter(fn (BackedEnum $case) => $case->isOdd()); // CasesCollection<BackedEnum::one, BackedEnum::three>
BackedEnum::collect()->only('two', 'three'); // CasesCollection<BackedEnum::two, BackedEnum::three>
BackedEnum::collect()->except('two', 'three'); // CasesCollection<BackedEnum::one>
BackedEnum::collect()->onlyValues(2, 3); // CasesCollection<BackedEnum::two, BackedEnum::three>
BackedEnum::collect()->exceptValues(2, 3); // CasesCollection<BackedEnum::one>
BackedEnum::collect()->sort(); // CasesCollection<BackedEnum::one, BackedEnum::three, BackedEnum::two>
BackedEnum::collect()->sortDesc(); // CasesCollection<BackedEnum::two, BackedEnum::three, BackedEnum::one>
BackedEnum::collect()->sortByValue(); // CasesCollection<BackedEnum::one, BackedEnum::two, BackedEnum::three>
BackedEnum::collect()->sortDescByValue(); // CasesCollection<BackedEnum::three, BackedEnum::two, BackedEnum::one>
BackedEnum::collect()->sortBy('color'); // CasesCollection<BackedEnum::three, BackedEnum::two, BackedEnum::one>
BackedEnum::collect()->sortDescBy(fn (BackedEnum $case) => $case->color()); // CasesCollection<BackedEnum::one, BackedEnum::two, BackedEnum::three>

๐Ÿ“† 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 [email protected] instead of using the issue tracker.

๐Ÿ… Credits

โš–๏ธ License

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

enum's People

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar

Forkers

cxw0504

enum's Issues

FormRequest validations

Is there a way to get FormRequest validations from an enum?

Context

Enumerations are commonly used at the PHP code and database level, in addition, in the FormRequest an extra layer of validation is added before trying to store in the database.

In my projects I usually use validation:

$request->validate(['status' => 'required|in:active,inactive']);

What is sought is to add a method to automate this based on the values/names of the enum.

Possible implementation

A method like the following would be very useful.

<?php

namespace App\Enums;

use Cerbero\Enum\Concerns\Enumerates;

enum StatusEnum: string {
    use Enumerates;

    case ACTIVE = 'active';
    case INACTIVE = 'inactive';
}

StatusEnum::rules(); // ['in:active,inactive']
StatusEnum::rules(['required']); // ['required', 'in:active,inactive']
StatusEnum::rulesFromNames(); // ['in:ACTIVE,INACTIVE']

Please let me know if there is a way to do this currently, if not please consider adding it to your package, I'm happy to send a PR if needed. Thank you

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.