Download the PHP package osama-98/laravel-enum-translatable without Composer

Translate Native PHP Enums in Laravel

A Laravel package that extends PHP 8.2 backed enums with first-class translation support, fluent array helpers, and safe comparison utilities — all through composable traits.

References: Medium Article · Laravel News

Table of Contents

• Requirements
• Installation
• Quick Start
• Configuration
• Available Traits
• Generating Enums
• Usage
  • Translation Key Convention
  • EnumTranslatable
  • EnumArrayable
  • EnumWrappable
• Real-World Examples
• Testing
• Changelog
• Credits
• License

Requirements

• PHP 8.2 or higher
• Laravel 11.0 or higher

Installation

Install the package via Composer:

Quick Start

Step 1. Generate an enum using the Artisan command:

Step 2. Define your cases and apply the trait:

Step 3. Add translation entries in lang/en/enums.php:

Step 4. Use the enum in your application:

Configuration

Publish the configuration file to customise supported locales and modular support:

Available Traits

The package provides three traits that compose on top of one another:

Generating Enums

Use the make:enum Artisan command to scaffold a new enum class:

Note: The --arrayable flag already includes EnumWrappable internally. There is no need to combine both flags.

Generated files are placed in app/Enums/. Nested namespaces are supported using /:

The Enum suffix is appended automatically if it is not included in the provided name.

Usage

All examples in this section use the following enum definition:

Translation Key Convention

The translation key is derived automatically from the enum class name by applying the following rules:

1. Strip the Enum suffix
2. Convert to snake_case
3. Pluralise
4. Nest under the enums key

Create one enums.php translation file per locale inside your lang/ directory:

EnumTranslatable

trans(?string $locale = null, ?string $context = null, array $replace = []): string

Returns the translated label for the current case. Defaults to the application locale. Falls back to the raw enum value if no translation is found.

The optional $context parameter appends a suffix to the translation key, enabling multiple label variants per case:

The optional $replace parameter passes replacement variables into the translation string, identical to Laravel's __() helper:

allTrans(): array

Returns translations for all locales defined in the supported_locales configuration option.

toArrayTrans(?string $locale = null): array

Returns all cases as an array of ['value', 'name'] pairs. Uses the current application locale when $locale is null.

toTransCollection(?string $locale = null): Collection

Identical to toArrayTrans() but returns a Laravel Collection.

object(): array

Returns the current case as a ['value', 'name'] pair using the current locale. Suitable for use in API responses.

transKey(): string

Returns the full translation key for the current case.

getTransKey(): string

Returns the translation key for the enum class, without a specific case appended.

EnumArrayable

names(): array · values(): array · toArray(): array

toCollection(): Collection

Identical to toArray() but returns a Laravel Collection.

only(array $values): array · except(array $values): array

Filter cases by value. Accepts raw string values or enum instances.

randomCase(): self · randomValue(): string

Returns a random case or raw value. Accepts an optional exclusion list.

matching(string $pattern): array · notMatching(string $pattern): array

Filter cases using a wildcard pattern. Matching is case-insensitive; * matches any sequence of characters.

The following convenience methods are also available:

EnumWrappable

wrap(BackedEnum|string|null $value, bool $strict = true): ?static

Safely casts a string or an existing enum instance to the enum type. Returns null for null or an empty string. A backed enum of a different type is unwrapped to its value and re-resolved against the calling enum, so the result is always an instance of the calling enum or null. Set strict: false to use tryFrom() instead of from(), which suppresses exceptions on invalid input.

is(BackedEnum|string $value): bool · isNot(BackedEnum|string $value): bool

isAny(array $values): bool · isNotAny(array $values): bool

Real-World Examples

Eloquent Model

Cast a database column directly to an enum using Laravel's built-in casting:

API Resource

Use object() to return a structured value and name pair in API responses:

Select Dropdown

Return all cases as translatable options for a frontend select component:

Testing

Changelog

Please refer to CHANGELOG.md for a detailed list of changes in each release.

Credits

• Osama Sadah
• All Contributors

License

This package is open-sourced software licensed under the MIT License.