Download the PHP package mindtwo/laravel-enum without Composer

About Laravel Enum

Simple, extensible and powerful enumeration implementation for Laravel.

• Enum key value pairs as class constants
• Full featured suite of methods
• Enum instantiation
• Type hinting
• Attribute casting
• Enum artisan generator
• Validation rules for passing enum key or values as input parameters
• Localization support
• Extendable via Macros

Created by Ben Sampson

Jump To

• Guide
• Installation
• Enum Library
• Basic Usage
  • Enum definition
  • Instantiation
  • Instance Properties
  • Instance Equality
  • Type Hinting
• Attribute Casting
• Validation
• Localization
• Overriding the getDescription method
• Extending the Enum Base Class
• PHPStan Integration
• Artisan Command List
• Enum Class Reference

Guide

I wrote a blog post about using laravel-enum: https://sampo.co.uk/blog/using-enums-in-laravel

Requirements

• Laravel 5.4 or newer
• PHP 7.1 or newer

Installation

Via Composer

If you're using Laravel < 5.5 you'll need to add the service provider to config/app.php

Enum Library

Browse and download from a list of commonly used, community contributed enums.

Enum library →

Basic Usage

Enum Definition

You can use the following Artisan command to generate a new enum class:

Now, you just need to add the possible values your enum can have as constants.

That's it! Note that because the enum values are defined as plain constants, you can simple access them like any other class constant.

Instantiation

It can be useful to instantiate enums in order to pass them between functions with the benefit of type hinting.

Additionally, it's impossible to instantiate an enum with an invalid value, therefore you can be certain that the passed value is always valid.

For convenience, enums can be instantiated in multiple ways:

If you want your IDE to autocomplete the static instantiation helpers, you can generate PHPDoc annotations through an artisan command.

By default all Enums in app/Enums will be annotated (you can change the folder by passing a path to --folder)

You can annotate a single class by specifying the class name

Instance Properties

Once you have an enum instance, you can access the key, value and description as properties.

This is particularly useful if you're passing an enum instance to a blade view.

Instance Casting

Enum instances can be cast to strings as they implement the __toString() magic method.
This also means they can be echoed in blade views, for example.

Instance Equality

You can check the equality of an instance against any value by passing it to the is method. For convenience, there is also an isNot method which is the exact reverse of the is method.

You can also check to see if the instance's value matches against an array of possible values using the in method.

Type Hinting

One of the benefits of enum instances is that it enables you to use type hinting, as shown below.

Attribute Casting

You may cast model attributes to enums using the CastsEnums trait. This will cast the attribute to an enum instance when getting and back to the enum value when setting.

Similar to how standard attribute casting works, you simply define which attributes you want to cast to which enum as an array on the model.

Now, when you access the user_type attribute of your Example model, the underlying value will be returned as a UserType enum.

Review the methods and properties available on enum instances to get the most out of attribute casting.

You can set the value by either passing the enum value or another enum instance.

Model Annotation

The package can automatically generate DocBlocks for your Model classes to provide type hinting & completion in your IDE.

By default all Model classes in the root of app will be annotated (you can change the folder by passing a path to --folder)

Validation

Array Validation

You may validate that an enum value passed to a controller is a valid value for a given enum by using the EnumValue rule.

By default, type checking is set to strict, but you can bypass this by passing false to the optional second parameter of the EnumValue class.

You can also validate on keys using the EnumKey rule. This is useful if you're taking the enum key as a URL parameter for sorting or filtering for example.

Of course, both of these work on form request classes too.

Make sure to include BenSampo\Enum\Rules\EnumValue and/or BenSampo\Enum\Rules\EnumKey and your enum class in the usings.

Pipe Validation

You can also use the 'pipe' syntax for both the EnumKey and EnumValue rules by using enum_value and/or enum_key respectively.

enum_value_:enumclass,[strict]
enum_key_:enumclass

Localization

You can translate the strings returned by the getDescription method using Laravel's built in localization features.

Add a new enums.php keys file for each of your supported languages. In this example there is one for English and one for Spanish.

Now, you just need to make sure that your enum implements the LocalizedEnum interface as demonstrated below:

The getDescription method will now look for the value in your localization files. If a value doesn't exist for a given key, the default description is returned instead.

Overriding the getDescription method

If you'd like to return a custom value from the getDescription method, you may do so by overriding the method on your enum:

Calling UserType::getDescription(3); now returns Super admin instead of Super administator.

Extending the Enum Base Class

The Enum base class implements the Laravel Macroable trait, meaning it's easy to extend it with your own functions. If you have a function that you often add to each of your enums, you can use a macro.

Let's say we want to be able to get a flipped version of the enum toArray method, we can do this using:

Now, on each of my enums, I can call it using UserType::toFlippedArray().

It's best to register the macro inside of a service providers' boot method.

PHPStan integration

If you are using PHPStan for static analysis, you can enable the extension for proper recognition of the magic instantiation methods.

Add the following to your projects phpstan.neon includes:

Artisan Command List

php artisan make:enum

Create a new enum class
Find out more

php artisan enum:annotate

Generate DocBlock annotations for enum classes
Find out more

php artisan enum:annotate-model

Generate DocBlock annotations for models that have enums
Find out more

Enum Class Reference

static getKeys(): array

Returns an array of the keys for an enum.

static getValues(): array

Returns an array of the values for an enum.

static getKey(mixed $value): string

Returns the key for the given enum value.

static getValue(string $key): mixed

Returns the value for the given enum key.

static hasKey(string $key): bool

Check if the enum contains a given key.

static hasValue(mixed $value, bool $strict = true): bool

Check if the enum contains a given value.

static getDescription(mixed $value): string

Returns the key in sentence case for the enum value. It's possible to override the getDescription method to return custom descriptions.

static getRandomKey(): string

Returns a random key from the enum. Useful for factories.

static getRandomValue(): mixed

Returns a random value from the enum. Useful for factories.

static getRandomInstance(): mixed

Returns a random instance of the enum. Useful for factories.

static toArray(): array

Returns the enum key value pairs as an associative array.

static toSelectArray(): array

Returns the enum for use in a select as value => description.

static getInstance(mixed $enumValue): Enum

Returns an instance of the called enum. Read more about enum instantiation.

static getInstances(): array

Returns an array of all possible instances of the called enum, keyed by the constant names.

static coerce(): ?Enum

Attempt to instantiate a new Enum using the given value if it exists. Returns null if it doesn't.