README

Laravel package that introduces a new Artisan command to generate Enum classes.

It provides an easy syntax to specify and map constants in Enum classes while adding PHPDoc tags to make IDEs recognise what constants can be invoked as methods to instantiate an Enum class.

Install

Via Composer

$ composer require cerbero/laravel-enum

Usage

Enums can be generated by calling the Artisan command make:enum and specifying the class and constant names. Many enums can be defined at once by separating them with pipes (please note the use of quotes):

$ php artisan make:enum Status 'IN_PROGRESS|COMPLETE|FAILED'

In the previous example no key has been defined, in this case keys are assumed to be equal to their lowercased constant name. This is how the Status enum will look like:

<?php

namespace App\Enums;

use Rexlabs\Enum\Enum;

/**
 * The Status enum.
 *
 * @method static self IN_PROGRESS()
 * @method static self COMPLETE()
 * @method static self FAILED()
 */
class Status extends Enum
{
    const IN_PROGRESS = 'in_progress';
    const COMPLETE = 'complete';
    const FAILED = 'failed';
}

Nonetheless you may need to define your own keys, that is possible by pairing constant names and keys with an = character:

$ php artisan make:enum Status 'IN_PROGRESS=1|COMPLETE=2|FAILED=3'

The command above will generate the following Status enum:

<?php

namespace App\Enums;

use Rexlabs\Enum\Enum;

/**
 * The Status enum.
 *
 * @method static self IN_PROGRESS()
 * @method static self COMPLETE()
 * @method static self FAILED()
 */
class Status extends Enum
{
    const IN_PROGRESS = 1;
    const COMPLETE = 2;
    const FAILED = 3;
}

Similarly you can specify enum values by pairing keys and values with an = character:

$ php artisan make:enum Status 'IN_PROGRESS=1=In progress|COMPLETE=2=Complete|FAILED=3=Failed'

The above command will generate the following Status enum and implement the map() method:

<?php

namespace App\Enums;

use Rexlabs\Enum\Enum;

/**
 * The Status enum.
 *
 * @method static self IN_PROGRESS()
 * @method static self COMPLETE()
 * @method static self FAILED()
 */
class Status extends Enum
{
    const IN_PROGRESS = 1;
    const COMPLETE = 2;
    const FAILED = 3;

    /**
     * Retrieve a map of enum keys and values.
     *
     * @return array
     */
    public static function map() : array
    {
        return [
            static::IN_PROGRESS => 'In progress',
            static::COMPLETE => 'Complete',
            static::FAILED => 'Failed',
        ];
    }
}

Sometimes you may want to define array of values in your keys or values, you can do that by providing JSON strings:

$ php artisan make:enum Status 'NAMES={"in_progress":"In progress","complete":"Complete"}'

This package will take care of building, indenting and formatting the array for you:

<?php

namespace App\Enums;

use Rexlabs\Enum\Enum;

/**
 * The Status enum.
 *
 * @method static self NAMES()
 */
class Status extends Enum
{
    const NAMES = [
        'in_progress' => 'In progress',
        'complete' => 'Complete',
    ];
}

You may also generate keys without the need to define them by using the --keys option:

--keys=bitwise generates bitwise keys (1, 2, 4, 8...)
--keys=int0 generates 0-indexed integer keys (1, 2, 3, 4...)
--keys=int1 generates 1-indexed integer keys (0, 1, 2, 3...)
--keys=lower generates keys by converting constant names to lower case

The following paired commands generate the same Enum class:

$ php artisan make:enum Status 'IN_PROGRESS=1|COMPLETE=2|FAILED=4'
$ php artisan make:enum Status 'IN_PROGRESS|COMPLETE|FAILED' --keys=bitwise

$ php artisan make:enum Status 'IN_PROGRESS=0|COMPLETE=1|FAILED=2'
$ php artisan make:enum Status 'IN_PROGRESS|COMPLETE|FAILED' --keys=int0

$ php artisan make:enum Status 'IN_PROGRESS=1|COMPLETE=2|FAILED=3'
$ php artisan make:enum Status 'IN_PROGRESS|COMPLETE|FAILED' --keys=int1

$ php artisan make:enum Status 'IN_PROGRESS=in_progress|COMPLETE=complete|FAILED=failed'
$ php artisan make:enum Status 'IN_PROGRESS|COMPLETE|FAILED' --keys=lower

When --keys is provided, you may define enum values by pairing names and values with an = character:

$ php artisan make:enum JSON 'HEX_TAG=Hex Tag|HEX_AMP=Hex Amp|HEX_APOS=Hex Apos|HEX_QUOT=Hex Quot' --keys=bitwise

The command above will generate the following JSON enum:

<?php

namespace App\Enums;

use Rexlabs\Enum\Enum;

/**
 * The JSON enum.
 *
 * @method static self HEX_TAG()
 * @method static self HEX_AMP()
 * @method static self HEX_APOS()
 * @method static self HEX_QUOT()
 */
class JSON extends Enum
{
    const HEX_TAG = 1;
    const HEX_AMP = 2;
    const HEX_APOS = 4;
    const HEX_QUOT = 8;

    /**
     * Retrieve a map of enum keys and values.
     *
     * @return array
     */
    public static function map() : array
    {
        return [
            static::HEX_TAG => 'Hex Tag',
            static::HEX_AMP => 'Hex Amp',
            static::HEX_APOS => 'Hex Apos',
            static::HEX_QUOT => 'Hex Quot',
        ];
    }
}

By default enums are generated in the app/Enums directory. If you prefer a different location, you can set the option --path (or the shortcut -p):

$ php artisan make:enum Status 'IN_PROGRESS|COMPLETE|FAILED' --path=Other/Directory

The above command will generate the Status class in app/Other/Directory.

If you try to generate an enum that already exists, the existing enum won't be overwritten unless you set the option --force (or the shortcut -f):

$ php artisan make:enum Status 'IN_PROGRESS|COMPLETE|FAILED' --force

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 / laravel-enum

Maintainers

Details