BenSampo/laravel-enum: PHP enum classes for Laravel with a built-in migration path out

The README opens with a deprecation notice, and the reason is PHP 8.1

The first substantive line in the BenSampo/laravel-enum README is a recommendation to stop using it. 'Using this library is no longer recommended, especially for new projects. PHP 8.1 supports enums natively.' That framing matters before anything else, because it sets the context for every other fact about the library.

This package was built to solve a real gap. PHP lacked a native enum type before version 8.1, so developers who wanted enumeration semantics had to rely on class-based workarounds. BenSampo/laravel-enum filled that role with a full suite of methods, artisan integration, type hinting, validation rules and a flagged or bitwise variant. Values were stored as PHP class constants, each enum extending a base class that supplied the collection of methods. Instantiation, casting, localization and artisan scaffolding were part of the API that PHP's own type system could not provide at the time.

The deprecation notice refers readers to issue #332 on the repository. For legacy codebases already using the library, it continues to function, and version 6.x ships a migration command for those cases.

Composer install takes one line; version 6.x requires PHP 8 and Laravel 9 through 13

Current documentation is for 6.x. Earlier major versions correspond to earlier Laravel releases: 4.x covers Laravel 8, 2.x covers Laravel 7, and 1.x covers Laravel 6 and below. Each branch's documentation is pinned by tag in the repository, giving users on older Laravel versions a path to the matching documentation without reading backward from the current README.

A project on Laravel 7 cannot install the latest 6.x release and expect compatibility, because each major version was built against a specific Laravel generation. The README is explicit about this, and links to the branch-specific docs directly.

For 6.x, the requirement is PHP 8 and Laravel 9 through 13. A single Composer command installs the package:

composer require bensampo/laravel-enum

No service provider registration is listed as a required step in the README, and no published config file is documented. UPGRADE.md at the repository root covers transitions between major versions, and CHANGELOG.md tracks the release history in plain text.

Class constants hold the values, and five methods handle instantiation

Enum values are defined as PHP class constants. A class extends BenSampo\Enum\Enum and declares its members as constants. Accessing UserType::Administrator directly returns the integer 0 without any instantiation.

<?php declare(strict_types=1);

namespace App\Enums;

use BenSampo\Enum\Enum;

final class UserType extends Enum
{
    const Administrator = 0;
    const Moderator = 1;
    const Subscriber = 2;
    const SuperAdministrator = 3;
}

When passing enum members between functions, instantiation provides type hinting, and an instance cannot be created with an invalid value, which removes a category of defensive checks from call sites. Five distinct methods are available to create an instance, each accepting a different form of the enum value. The standard constructor takes a value directly as its argument: new UserType(UserType::Administrator). UserType::fromValue(UserType::Administrator) does the same thing with a named method. UserType::fromKey('Administrator') takes the constant name as a string rather than the constant's integer value. A static call using the constant name, UserType::Administrator(), resolves through __callStatic at runtime and reads like a factory method. The fifth method, UserType::coerce($someValue), returns null when the value is invalid rather than throwing an exception, which is the behavior the other four do not provide.

The five methods exist because the library had to replicate, through PHP class methods, what PHP 8.1 eventually provided as a language feature. The migration guide makes that lineage visible: tryFrom() is the recommended replacement for coerce when only values were passed, which shows the intent was always to model the eventual native type.

The null return from coerce is the one to reach for when input is untrusted and a missing match should not abort the request. The other four methods throw on invalid input, which is the right behavior when an invalid value at that call site represents a programming error.

The make:enum generator and enum:annotate for IDE autocomplete

Artisan integration in this library covers two commands, both accessed through the standard php artisan entry point. The first generates a new enum class file:

php artisan make:enum UserType

That command produces a class skeleton with the extends clause and a placeholder for constants. The annotation command's documented default directory is app/Enums, but the README does not state where make:enum places the generated file, so checking the output path after the first run is a necessary step.

A second command adds PHPDoc annotations to help IDEs autocomplete the static instantiation helpers. Running it without arguments annotates all enums under app/Enums:

php artisan enum:annotate

To annotate a single class, pass its fully qualified name:

php artisan enum:annotate "App\Enums\UserType"

Without those annotations, IDEs see an unknown call when you write UserType::Administrator(), because __callStatic resolves method names at runtime. Generated PHPDoc @method comments add the missing static signatures, which is what static analysis tools and IDE plugins need to check the call at edit time. The README notes that the target folder can be changed by passing a path to --folder, so the command also covers project layouts that place enums outside app/Enums.

php artisan enum:to-native automates migration, but three gap areas need manual fixes

For projects on PHP 8.1 or above with Laravel 10 or above, version 6.x provides an artisan command that converts BenSampo enum classes to native PHP enums. Rector 0.17 or higher must also be installed, with rector.php configured to include all relevant files.

Running the command without arguments converts every enum in the project:

php artisan enum:to-native

To limit the conversion to a single class, pass its fully qualified name:

php artisan enum:to-native "App\Enums\UserType"

Three specific areas are not covered by the automated migration and require manual revision after Rector completes its pass. Enum::coerce() has no direct native equivalent: if only values were passed to it, tryFrom() can replace it, but if keys or instances were also possible inputs, additional logic is required. Enum::$description and Enum::getDescription() require a manual alternative after migration, because native PHP enums provide neither property. Exception handlers for BenSampo\Enum\Exceptions\InvalidEnumKeyException and BenSampo\Enum\Exceptions\InvalidEnumMemberException need conversion to either catching ValueError from native enums or switching to tryFrom() with a null check.

Unimplemented migration cases are maintained under tests/Rector/Unimplemented in the repository. Reading that directory before running the command gives a realistic picture of how much manual work remains after the automated step.

Bitwise flags, attribute casting, validation rules and localization are separate concerns

Several additional capabilities are available in this package. Flagged or bitwise enums allow a single integer value to represent a combination of states through bitwise operators. This is the right pattern when a record must hold multiple simultaneous flags, such as a user with both Administrator and Moderator roles active at the same time. Standard integer enums would force a separate column or junction table for that requirement.

Validation rules let enum keys or values be passed as input parameters and checked against the enum's defined members, integrating the constant set directly into Laravel's request validation pipeline. That means the same constants declared in the class serve as the validation constraint, with no duplication. Localization support maps enum values to translated display strings, which matters in multi-locale applications where an enum member's description must change by language. Attribute casting ties the enum to an Eloquent model attribute, so reads return an instance and writes convert back to the raw value automatically.

PHPStan integration is available through extension.neon at the repository root. Laravel Nova integration adds Nova fields and filters for use with enum instances. Macros allow extending the base enum class without subclassing, but no registration example appears in the documentation. A community-contributed library of common enums is documented in enum-library.md at the repository root.

No GitHub releases, MIT license, and the last push was on 2026-09-03

No GitHub releases appear on the repository. There is no tagged version to pin by release number: version resolution happens through Packagist, and the current documentation covers 6.x. CHANGELOG.md at the repository root tracks the version history in plain text, which is where specific version numbers and changes are found.

License is MIT, per LICENSE.txt at the repository root and the package metadata. MIT imposes no restrictions on commercial use, distribution or modification beyond preserving the copyright notice. LICENSE.txt is the text to read in full before redistributing a modified build.

The last push was on 2026-09-03. The repository is not archived. An active recent push combined with the deprecation notice suggests the maintainer is accepting changes for compatibility maintenance with newer Laravel versions rather than expanding the feature set. CONTRIBUTING.md is present in the repository for developers who want to submit changes.

Editorial conclusion

BenSampo/laravel-enum suits teams maintaining Laravel codebases built before PHP 8.1 enums arrived. Version 6.x supports Laravel 9 through 13 and includes php artisan enum:to-native as a documented exit path. The migration is not fully automated: the coerce method, the getDescription API, and exception handlers for the two library-specific exceptions need manual revision after Rector runs. New projects on PHP 8.1 and Laravel 10 or above should use native PHP enums and skip this dependency entirely. Before starting, review tests/Rector/Unimplemented to estimate the manual work remaining after the automated step.

Frequently asked questions

Official sources

1. BenSampo/laravel-enum on GitHub
2. Issues
3. License: MIT
4. Project website
5. README