Php Enhanced Enum Laravel Package

Getting Started

This package is a small convenience layer over native PHP 8.1+ enums. It does not replace enum semantics; it mostly removes repeated cases() mapping, name/value lookups, and comparison boilerplate. Treat it as a utility trait, not as framework infrastructure.

Minimal setup:

composer require vicgutt/php-enhanced-enum

Confirm the installed version and PHP constraint:

composer show vicgutt/php-enhanced-enum

Look first at:

1. The README usage block for the exact trait namespace and method names.
2. The trait source in src/ to confirm whether helpers are static, instance methods, or both.
3. Any tests for the exact shape of toArray()/values()/names() and whether failures throw or return null.

First use case: a backed enum for an order status, used in a form select and request validation.

use VicGUTT\PhpEnhancedEnum\EnhancedEnum; // confirm exact namespace in README

enum OrderStatus: string
{
    use EnhancedEnum;

    case Draft = 'draft';
    case Paid = 'paid';
    case Shipped = 'shipped';
}

Then use the package helpers where you would otherwise repeat array_map(fn ($case) => $case->value, OrderStatus::cases()):

$values = OrderStatus::values();  // allowed values for validation/UI
$options = OrderStatus::toArray(); // form options; confirm key/value shape

For Laravel validation, pair it with Rule::enum() where available:

'status' => ['required', Rule::enum(OrderStatus::class)],

Implementation Patterns

• Wrap the package behind one app trait. Create App\Enums\Concerns\HasEnumHelpers that uses the package trait, then have all app enums use your wrapper. This gives you one place to add options(), labels(), or swap the package later.

namespace App\Enums\Concerns;

use VicGUTT\PhpEnhancedEnum\EnhancedEnum;

trait HasEnumHelpers
{
    use EnhancedEnum;
}

• Centralize form options in the enum or a presenter. Do not call package helpers repeatedly inside Blade templates. Add an explicit options() method when labels differ from case names, or when you need a stable display order.

• Use enum values at boundaries. In FormRequests/controllers, convert request input with tryFrom()/tryFromName() and return a 422 on failure. Avoid letting from() throw an uncaught ValueError in normal request handling.

• Keep Eloquent casts native. Use Laravel enum casts for model attributes. Use the package for display lists, validation allow-lists, and readable comparisons, not as a replacement for casts.

• Use comparison helpers for guard clauses. Methods like is(), isNot(), and in() make state checks readable, but keep transition rules in explicit enum methods or a state machine. Do not scatter raw arrays of allowed transitions through controllers.

• Generate test data from cases(). Data providers should use Enum::cases() so new cases automatically get coverage. Add one test that locks down package helper semantics, then test domain behavior against your wrapper trait.

• Design for replacement. Since the package is small and old, keep app code calling your wrapper, not the vendor trait directly. Replacing it with a local trait should be a one-file change.

Gotchas and Tips

• Maturity risk is real. Zero stars, zero dependents, and a last release in November 2022 mean you should pin the version, review the source, and avoid building architecture around it. It is a small utility; be ready to vendor or replace it.

• Confirm method contracts before relying on them. Check whether toArray() returns name => value, value => name, or a list; whether helpers sort results; whether lookups throw or return null; and whether name lookups are case-sensitive.

• Native enum traps still apply. from() throws ValueError, tryFrom() returns null, pure enums have no backing value, and backed values must be unique. The package does not fix invalid input data.

• Watch for trait method collisions. If an enum already defines values(), toArray(), or another helper with the same name, the trait can cause a fatal conflict. Rename local methods or alias the trait method.

• Do not assume JSON behavior changes. Backed enums already serialize in specific ways; if your API contract needs {value, label}, return that explicitly from an API Resource instead of relying on the enum helper.

• Case names are not user-facing labels. The package may expose names like Draft and Paid, but UI labels often need localization. Add a label() method or label map and translate it deliberately.

• Laravel version check. Rule::enum() is available in newer Laravel versions. On older versions, build an in: rule from OrderStatus::values() or your own wrapper.

• Static analysis and IDE support. The package is old enough that PHPStan/Psalm generics may be missing. Add docblocks like @return array<string, string> on your wrapper methods and import the trait normally so IDEs can autocomplete.

• Do not install it for validation alone. If you only need allowed values, native cases() plus Rule::enum() or a one-line array_map() may be simpler. The package earns its place when it consistently removes enum boilerplate across many enums.