README

A comprehensive Laravel package for working with PHP Enums, providing casting, validation, translation, query scopes, and more.

Features

✅ Enum Helpers: Useful methods for working with enums (values(), names(), random(), fromValue(), etc.)
✅ Eloquent Casting: Automatic enum casting in Eloquent models
✅ Validation Rules: Built-in validation rules for enum values
✅ Translation Support: Easy translation of enum labels
✅ Query Scopes: Helper scopes for filtering by enum values
✅ Type Safety: Full type safety with PHP 8.2+ backed enums

Installation

composer require rawnoq/laravel-enum

Configuration

Publish the config file:

php artisan vendor:publish --tag=enum-config

Usage

Basic Enum with Helpers

use Rawnoq\Enum\Concerns\HasEnumHelpers;

enum UserStatus: string
{
    use HasEnumHelpers;

    case Active = 'active';
    case Inactive = 'inactive';
    case Pending = 'pending';
}

// Get all values
UserStatus::values(); // ['active', 'inactive', 'pending']

// Get random case
UserStatus::random(); // UserStatus::Active (random)

// Get by value
UserStatus::fromValue('active'); // UserStatus::Active

// Check if value exists
UserStatus::hasValue('active'); // true

// Get as array
UserStatus::toArray(); // ['active' => 'Active', 'inactive' => 'Inactive', ...]

Eloquent Model Casting

use Rawnoq\Enum\Casts\EnumCast;

class User extends Model
{
    protected $casts = [
        'status' => EnumCast::class.':'.UserStatus::class,
    ];
}

// Usage
$user = User::find(1);
$user->status; // UserStatus::Active (enum instance)
$user->status = UserStatus::Inactive; // Automatically casts to 'inactive'

Validation

use Rawnoq\Enum\Rules\EnumRule;

$request->validate([
    'status' => ['required', new EnumRule(UserStatus::class)],
]);

Translation Support

use Rawnoq\Enum\Concerns\HasEnumTranslation;

enum UserStatus: string
{
    use HasEnumTranslation;

    case Active = 'active';
    case Inactive = 'inactive';
}

// In your language file (lang/en/enums.php):
return [
    'user_status' => [
        'active' => 'Active',
        'inactive' => 'Inactive',
    ],
];

// Usage
UserStatus::Active->label(); // 'Active'
UserStatus::labels(); // ['active' => 'Active', 'inactive' => 'Inactive']

Query Scopes

use Rawnoq\Enum\Concerns\HasEnumScopes;

class User extends Model
{
    use HasEnumScopes;
}

// Usage
User::whereEnum('status', UserStatus::Active)->get();
User::whereEnumIn('status', [UserStatus::Active, UserStatus::Pending])->get();
User::whereEnumNotIn('status', [UserStatus::Inactive])->get();

Helper Facade

use Rawnoq\Enum\Facades\Enum;

Enum::isValid(UserStatus::class, 'active'); // true
Enum::fromValueOr(UserStatus::class, 'active', UserStatus::Pending); // UserStatus::Active
Enum::valuesAsString(UserStatus::class); // 'active, inactive, pending'

Advanced Usage

Combining Multiple Traits

use Rawnoq\Enum\Concerns\HasEnumHelpers;
use Rawnoq\Enum\Concerns\HasEnumTranslation;

enum UserStatus: string
{
    use HasEnumHelpers, HasEnumTranslation;

    case Active = 'active';
    case Inactive = 'inactive';
    case Pending = 'pending';
}

Custom Translation Namespace

enum UserStatus: string
{
    use HasEnumTranslation;

    case Active = 'active';

    public static function translationNamespace(): string
    {
        return 'custom.namespace';
    }
}

Filtering and Mapping

// Filter enum cases
$activeCases = UserStatus::filter(fn($case) => $case->value !== 'inactive');

// Map enum cases
$labels = UserStatus::map(fn($case) => $case->label());

API Reference

HasEnumHelpers Methods

values() - Get all enum values
names() - Get all enum names
fromValue($value) - Get enum by value (nullable)
fromValueOrFail($value) - Get enum by value (throws exception)
random() - Get random enum case
toArray() - Convert to associative array
options() - Get options for select/dropdown
hasValue($value) - Check if value exists
hasName($name) - Check if name exists
first() - Get first enum case
last() - Get last enum case
filter($callback) - Filter enum cases
map($callback) - Map enum cases

HasEnumTranslation Methods

label() - Get translated label for current case
labelFor($locale) - Get translated label for specific locale
labels() - Get all translated labels
labelsFor($locale) - Get all translated labels for locale
translationKey($case) - Get translation key for case
translationNamespace() - Get translation namespace
translationKeyFormat() - Get translation key format

HasEnumScopes Methods (for Models)

whereEnum($column, $value) - Filter by enum value
whereEnumIn($column, $values) - Filter by multiple enum values
whereEnumNotIn($column, $values) - Exclude enum values

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

rawnoq / laravel-enum

Maintainers

Details