feat: port framework enum support from Laravel

[binaryfire]

This PR ports Laravel's comprehensive enum_value() support throughout the framework, allowing enums to be used in place of strings across caching, queues, broadcasting, scheduling, validation, and more.

Summary

Laravel has gradually added enum support across the entire framework, allowing developers to use type-safe enums instead of magic strings for things like queue names, cache keys, broadcast channels, and more. This PR brings that same level of enum support to Hypervel, and builds on it.

The enum_value() helper function extracts the underlying value from enums:

• BackedEnum: Returns ->value (string or int)
• UnitEnum: Returns ->name (string)
• Non-enum: Returns the value unchanged

---

Ported from Laravel

Cache

• Repository: has(), missing(), get(), pull(), put(), set(), add(), increment(), decrement(), forever(), remember(), sear(), rememberForever(), forget(), delete()
• RateLimiter: for(), limiter(), tooManyAttempts(), hit(), attempts(), resetAttempts(), remaining(), retriesLeft(), clear(), availableIn(), cleanRateLimiterKey()

Queue & Bus

• Queueable trait: onConnection(), onQueue(), allOnConnection(), allOnQueue()
• PendingDispatch: onConnection(), onQueue(), afterCommit(), beforeCommit()
• PendingBatch: onQueue(), onConnection()
• PendingChain: onQueue(), onConnection()
• RateLimited middleware: Constructor accepts enum limiter names

Broadcasting

• InteractsWithBroadcasting trait: broadcastOn()
• PendingBroadcast: onQueue(), onConnection()

Scheduling

• ManagesFrequencies trait: days(), weekdays(), weekends(), sundays() through saturdays()
• Schedule: job() accepts enum queue/connection

Database & Eloquent

• Query\Builder: from(), fromSub(), join() and variants, crossJoinSub(), orderBy(), latest(), oldest(), groupBy(), dd(), dump()
• Model: setTable()
• Pivot / MorphPivot: setTable()
• Factory: connection(), recycle()

Auth & Gate

• Gate: allows(), denies(), check(), any(), none(), authorize(), inspect(), raw(), define(), resource(), policy()
• AuthorizesRequests trait: authorize(), authorizeForUser(), authorizeResource(), can()
• Authorize middleware: Enum abilities support

Session

• Store / Session contract: get(), has(), put(), remember(), push(), increment(), decrement(), forget(), remove(), pull()

Events

• EventDispatcher: dispatch(), listen(), hasListeners(), push(), flush(), forget()
• QueuedClosure: onConnection(), onQueue()

Validation

• Rule::in(), Rule::notIn(): Accept enum values
• In / NotIn rules: Constructor accepts enums

Filesystem

• FilesystemManager: disk(), drive(), build(), set(), forgetDisk(), purge()
• Storage facade: fake(), persistentFake()

Router

• ThrottleRequests middleware: using() accepts enum limiter names

Redis

• Redis facade: connection()

Translation

• Translator: get(), choice(), has(), hasForLocale()

Support

• Collection / LazyCollection: contains(), doesntContain(), containsStrict()
• InteractsWithData trait: data(), has(), filled(), isNotFilled(), missing(), hasAny()
• Js: Enum value serialization (changed from BackedEnum to UnitEnum)

Helpers

• report(): Exception context accepts enum keys

---

Extra Additions (Hypervel-specific)

Laravel currently doesn't support enums for these things, but probably will in the future:

Cache Tags

• TaggedCache: increment(), decrement()
• RedisTaggedCache: add(), put(), increment(), decrement(), forever()

Context

• Context: set(), get(), has(), destroy(), override(), getOrSet()

Cookie

• CookieManager / Cookie contract: has(), get(), make(), expire(), unqueue(), forever(), forget()

Sanctum

Updated Sanctum to use enum_value() instead of Str::from() / Str::fromAll() for consistency:

• HasApiTokens trait: tokenCan(), tokenCant(), createToken()
• PersonalAccessToken / TransientToken: can(), cant()
• Replaced Str::from() / Str::fromAll() with enum_value() / array_map(enum_value(...))

Type Signature Improvements

Laravel doesn't use signature type hints to avoid breaking backwards compatibility. Since this will be merged in 0.4, we can make it a breaking change and use modern typing:

• Moved type hints from docblocks to signatures
• Updated BackedEnum to UnitEnum in type hints to match Laravel's pattern (UnitEnum is the base interface that BackedEnum extends)
• Removed redundant BackedEnum|UnitEnum union types (simplified to just UnitEnum since BackedEnum extends UnitEnum)
• Affected files: Queueable, PendingDispatch, PendingBatch, PendingChain, In, NotIn, Js, Sanctum traits/contracts

Simplified enum_value() Implementation

Removed unnecessary transform() wrapper to match Laravel's simpler implementation:

// Before
return transform($value, fn ($value) => match (true) {
    $value instanceof BackedEnum => $value->value,
    $value instanceof UnitEnum => $value->name,
    default => $value,
}, $default ?? $value);

// After
return match (true) {
    $value instanceof BackedEnum => $value->value,
    $value instanceof UnitEnum => $value->name,
    default => $value ?? value($default),
};

`transform()` wasn't adding any value and added unnecessary overhead.

---

Test Coverage

Added comprehensive tests for all enum support:

• String-backed enum tests (returns ->value)
• Unit enum tests (returns ->name)
• Int-backed enum tests (verifies TypeError at typed boundaries where appropriate)

[albertcht]

Hi @binaryfire, thank you for this pull request! Will this PR introduce breaking changes for anyone who has implemented custom session stores? Custom implementations of the session store interface will need to update their method signatures to accept additional BackedEnum parameter.

Therefore, I'll merge it into the upcoming v0.4 branch, which we expect to release soon.

[binaryfire]

@albertcht Ah yeah, good point. No problems! I'm going to make PRs for the other places where enum support would be useful. This what I'm thinking:

• Cache (keys and tags)
• Config
• RateLimiter
• Gate
• Cookie
• Context

What do you think?

[albertcht]

@albertcht Ah yeah, good point. No problems! I'm going to make PRs for the other places where enum support would be useful. This what I'm thinking:

• Cache (keys and tags)
• Config
• RateLimiter
• Gate
• Cookie
• Context

What do you think?

I think enum support is a great idea, but we could be more strategic about where it provides the most value.

Enums work best when the string values are complete, standalone identifiers that are used as-is throughout the application. They're ideal for scenarios where you have a fixed, predefined set of values that get repeatedly referenced across multiple layers (controllers, services, views, middleware) without modification.

Enums are a poor fit when string values need concatenation with dynamic parts or represent hierarchical structures. For example, patterns like "user:profile:{$id}" or "posts:{$category}:{$page}" where you're constantly appending variables defeat the purpose – you can only define prefixes in enums and still need string concatenation. Similarly, dot-notation hierarchical paths like "database.connections.mysql.host" create awkward enum case names (DATABASE_CONNECTIONS_MYSQL_HOST) that are verbose and hard to maintain, especially when you have hundreds of possible paths including unpredictable third-party additions.

From your list, I think Gate seems to be the most suitable choice, while others like Cache, Config, Context, and RateLimiter don't seem to be good fits.

[binaryfire]

Hi @albertcht. Laravel has added BackedEnum support for cache keys: laravel/framework#58246

There have have been several PRs for adding enum support across the framework and they've all been accepted:

laravel/framework#58241
laravel/framework#58343
laravel/framework#57190
laravel/framework#58310

The RateLimiter supports enums now too: https://github.com/laravel/framework/blob/3026dc7a7cf24b413a34c14ea3da992d045cac66/src/Illuminate/Cache/RateLimiter.php#L318

I know you said we should limit the places enums are supported, but I think we should follow Laravel's lead and add support to the following things:

Already supported by Laravel:

• Cache
• RateLimiter
• Gate
• Session
• Translation replacement values
• Collections

Not supported by Laravel yet, but I'm sure they will be soon:

• Cookie
• Context

What do you think? I use enums for all these things. Not in every situation, but whenever possible. There's no performance overhead and it gives developers the option of better type safety if they want it.

I'll port everything over plus add support in a few more places I think make sense, then you can take a look.

[binaryfire]

Hi @albertcht. This PR is ready for review. I've updated the post. Most of this is just porting enum support from Laravel. I added enum support in a few additional areas as well.

Let me know what you think.