How to use the new PHP Enum in Laravel

Photo by Mick Haupt on Unsplash

PHP 8.1 introduced long awaited support for built-in Enums. There is no more need for custom solutions in your Laravel projects since Laravel with its 8.69 release has your back.

We’ll take a really simple example of a blogpost model with a publication state that can be draft or published. As it will be stored in database, we used a “backed” Enum. It means that each value is associated with a string.

<?php

namespace App\Enums;

enum BlogpostState: string
{
    case DRAFT = 'state_draft';
    case PUBLISHED = 'state_published';
}

Entity model

When creating your database schema, you can use eloquent’s“string” type for the state column as it will store the Enum’s backed value as a string: ‘state_draft’ or ‘state_published’.

public function up()
{
    Schema::create('blogposts', function (Blueprint $table) {
        ...
        $table->string('state');
    });
}

Now comes the great part. You can use the new casting in your Blogpost model and it allows your state model attribute to be casted to/from an Enum:

<?php

namespace App\Models;
class Blogpost extends Model
{
    protected $casts = [
       'state' => BlogpostState::class,
    ];
}

Then you’ll get the enum when interacting with the state attribute:

>>> dd($blogpost->state);
=> App\Enums\BlogpostState {
     +name: "DRAFT",
     +value: "state_draft",
   }

So for example you can now compare the state to the Enum directly:

public function isPublished()
{
    return $this->state === BlogpostState::PUBLISHED;
}

Or use it in a query:

Blogpost::where('state', BlogpostState::PUBLISHED)->get();

Or access the backed value stored in database if needed:

>>> dd($blogpost->state->value);
=> "state_draft"

Also if you try to create or update a blogpost with an invalid state value, you’ll get an immediate PHP error:

>>> $blogpost->update(['state' => 'state_foo']);                                                                                                                   PHP Error:  "state_foo" is not a valid backing value for enum "App\Models\Enums\BlogpostState"

The state’s enum can have methods,

    public function label(): string
    {
        return match($this)
        {
            self::DRAFT => 'Draft...',
            self::PUBLISHED => 'Published!',
        };
    }

that could be used directly with your model:

>>> $blogpost->state->label();
=> "Draft..."

Validation rule

When you want to make sure an input match an enum, you can use a new laravel rule:

<?php

namespace App\Http\Requests;
use Illuminate\Validation\Rule;
use App\Models\Enums\BlogpostState;
class BlogpostRequest extends FormRequest
{
    public function rules()
    {
        return [
            "state" => [
                 "required",
                 Rule::enum(BlogpostState::class),
            ],
        ];
    }
}

And it’s pretty straightforward. Now your request only accept enum’s backed values: ‘state_draft’ or ‘state_published’.

This is the default validation message for an invalid Enum value

The Enum validation rule includes “only” and “except” methods if you need to exclude some values:

Rule::enum(BlogpostState::class)->except([
   BlogpostState::PUBLISHED,
])

Factory

Also, when you want to seed a blogpost, you can now use enum directly in your factory:

<?php

namespace Database\Factories;

class BlogpostFactory extends Factory
{

    public function definition()
    {
        return [
            ...
            'state' => BlogpostState::DRAFT,
        ];
    }
}

Route bindings

Since Laravel 9, there is now implicit route binding with enum. So you can type-hint your enum and Laravel will automatically cast the string value from the URL :

Route::get('/blog/{state}', function(BlogpostState $state) {
    // here $state is an enum instance
});

In our example, both

• https://mysite.com/blog/state_draft
• https://mysite.com/blog/state_published

are valid URLs. But if URL does not match any of the enum’s values, you’ll get a 404 error (Ex: https://mysite.com/blog/state_foo).

I think we’re done here. Thanks for reading !