Enum Basics Extension Laravel Package

Getting Started

This is a thin helper package that layers convenience methods onto native PHP 8.1+ enums. Because the package is small and has almost no community footprint, treat the first thirty minutes as an audit: read the README, then read src/ directly (one or two traits, typically EnumBasics / EnumExtension). You want to know the exact method names and whether the trait targets backed enums, pure enums, or both before you wire it into anything real.

Install and confirm the constraint surface:

composer require quantumtecnology/enum-basics-extension

Check the resolved version and the package's composer.json for the PHP floor (^8.1 is the practical minimum for enums) and whether it declares a Laravel service provider. If there is no provider, it's a pure trait library with nothing to register — which is the most likely shape for a package described as "funções básicas para enum."

Where to look first:

1. vendor/quantumtecnology/enum-basics-extension/README.md — the canonical method list.
2. vendor/quantumtecnology/enum-basics-extension/src/ — the actual trait(s). This is your source of truth; a 1-star package's README may lag behind the code.
3. composer.json → autoload block, to confirm the namespace you'll use in your enum files.

First use case — a status enum feeding a dropdown:

namespace App\Enums;

use QuantumTecnology\EnumBasicsExtension\Traits\EnumBasics; // verify exact FQCN in src/

enum OrderStatus: string
{
    use EnumBasics;

    case Pending   = 'pending';
    case Paid      = 'paid';
    case Shipped   = 'shipped';
    case Cancelled = 'cancelled';
}

Then, assuming the package exposes the conventional helpers:

OrderStatus::values();            // ['pending', 'paid', 'shipped', 'cancelled']
OrderStatus::toArray();           // ['pending' => 'Pending', ...] or similar
OrderStatus::names();             // ['Pending', 'Paid', ...]

Verify each of those against src/ before committing. The value of the package is entirely in this ergonomic layer, so a five-minute read beats a day of debugging a guess.

Implementation Patterns

Validation — the highest-leverage integration. Instead of hand-maintaining in:pending,paid,shipped,cancelled strings that silently drift when a case is added:

use Illuminate\Validation\Rule;

$request->validate([
    'status' => ['required', Rule::in(OrderStatus::values())],
]);

This is the pattern that pays for the dependency immediately: adding case Refunded updates validation everywhere at once.

Eloquent casts plus label rendering. Cast the column to the enum, then use the helper for presentation rather than re-deriving strings in Blade:

protected $casts = [
    'status' => OrderStatus::class,
];

<select name="status">
    @foreach (\App\Enums\OrderStatus::cases() as $case)
        <option value="{{ $case->value }}">{{ $case->label() ?? $case->name }}</option>
    @endforeach
</select>

If the package does not ship a label() method, define one on the enum itself and let the trait handle the bulk operations — mixing package helpers with a locally defined label() is the normal composition, not a workaround.

Admin panel / form-builder integration. The value => label array shape is what Filament, Nova, and most select components want. Wrap it once on the enum and reuse:

public static function options(): array
{
    return collect(self::cases())
        ->mapWithKeys(fn ($c) => [$c->value => $c->label() ?? $c->name])
        ->all();
}

Factory and seeder ergonomics. A random()-style helper (if present) is convenient in factories, but for deterministic tests prefer fake()->randomElement(OrderStatus::cases()) — it uses the same source of truth without depending on the package's RNG behavior.

Test assertions. Assert against enum cases, not raw strings, so a rename breaks compilation rather than quietly passing:

$this->assertDatabaseHas('orders', ['status' => OrderStatus::Paid->value]);

Incremental adoption. Because this is a trait, adopt it per-enum. Apply it to new enums first; retrofit existing ones as you touch them. There is no global registration, so there is no all-or-nothing migration.

Gotchas and Tips

• The API is not verified by stars. With 1 star and 0 dependents, there is no ecosystem pressure keeping method signatures stable. Pin the version in composer.json ("quantumtecnology/enum-basics-extension": "1.0.*" or an exact constraint) and read the diff on every composer update. Semver hygiene in packages this size is aspirational, not guaranteed.
• Backed vs pure enums. Most "basic enum helpers" assume ->value exists and will fatal on a pure enum with no backing type. If your trait calls hit ->value on a unit enum, PHP throws Error: Undefined constant. Keep pure enums free of the trait, or confirm the package guards for it.
• Trait method collisions. Native enums already provide cases(), from(), and tryFrom(). If the package also declares a static cases() or a name-adjacent helper, you'll get a fatal "trait method conflicts" only if you use two traits — but if the package defines a method matching a PHP built-in, you get a hard signature error at class definition time. Symptom is an error on the enum declaration line, not at call site.
• tryFrom returning null. Any helper that wraps tryFrom probably returns null for unknown input. Guard it before calling instance methods: $status = OrderStatus::tryFrom($raw)?->label();. Silent nulls are the most common source of blank cells in admin tables.
• Translation belongs in your app, not the trait. If the package hardcodes humanized labels via Str::headline($case->name), that output is not translatable. Override label() locally with __('enums.order_status.paid') for any user-facing surface with more than one locale.
• toArray() shape ambiguity. "Array of enums" versus "value => label map" versus "list of values" are three different things and small packages pick one without saying so. Dump one call before building a Rule::in() around it — passing an enum case into Rule::in will fail validation silently on string input.
• Copy the trait if the package stalls. It's MIT. If the dependency becomes a liability, cp the trait into App\Support\Enums under your own namespace and drop the require. For a helper of this size that is a legitimate, low-cost exit and worth doing pre-emptively if you're risk-averse about vendor churn.
• Debugging a missing method. If Status::values() throws "Call to undefined method," the cause is almost always a missing use EnumBasics; inside the enum or a wrong namespace import — not version skew. Run php -r "var_dump(class_uses(App\Enums\OrderStatus::class));" to confirm the trait actually attached.