feat: add BackedEnum support to more places in the framework

[binaryfire]

Summary

This PR enables using BackedEnums in more places across the framework,, building on the Str::from() and Str::fromAll() helpers merged in #291.

Motivation

Using string literals for session keys is error-prone:

// Typos slip through unnoticed
session()->get('user_prferences');  // 'prferences' typo
session()->put('curent_user', $user);  // 'curent' typo

// Inconsistent naming causes bugs
session()->put('currentUser', $user);
session()->get('current_user');  // Different key!

BackedEnums solve this with IDE autocomplete and compile-time safety:

enum SessionKey: string
{
    case CurrentUser = 'current_user';
    case CartItems = 'cart_items';
    case Locale = 'locale';
}

// Now you get autocomplete, refactoring support, and typo prevention
session()->put(SessionKey::CurrentUser, $user);
session()->get(SessionKey::CurrentUser);

Added for

• Session

Tests

Added new tests covering:

• Single enum keys for operations
• Arrays of enums
• Mixed arrays (enums + strings)
• Int-backed enum support
• Interoperability between enum and string access

[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.