cable8mm/enum-getter

Translation-aware helpers for PHP Enums — perfect for Laravel, Laravel Nova, and any application that needs localized enum labels.

v2.2.0 2026-08-23 08:47 UTC

Requires

• php: ^8.2

Requires (Dev)

• laravel/pint: ^1.19
• phpunit/phpunit: ^10.0|^11.0

MIT

• Sam Lee

• translation
• nova
• enum
• laravel
• php-enum
• enum-helper

Published on Packagist.org on 2026-08-23 08:48 UTC

README

Translation-aware helpers for PHP Enums — perfect for Laravel, Laravel Nova, and any application that needs localized enum labels.

Why this package exists

Any application that uses PHP Enums often needs translated associative arrays such as:

[
    'draft' => '초안',
    'published' => '출판됨',
]

Generating these arrays manually from Enum::cases() quickly becomes repetitive.

Enum Getter provides helper methods that expose PHP Enums as translation-aware arrays — perfect for Laravel, Laravel Nova, APIs, and any application that needs localized enum labels.

Installation

composer require cable8mm/enum-getter

Quick Start (Without Translation)

If you don't need translation, simply use the EnumGetter trait. The label() method returns the enum value as-is, so keys() and labels() produce the same result.

use Cable8mm\EnumGetter\EnumGetter;

enum Status: string
{
    use EnumGetter;

    case Draft = 'draft';
    case Published = 'published';
}

Get enum keys:

Status::keys();

Result:

[
    'draft',
    'published',
]

Get labels (same as keys when no translation is needed):

Status::labels();

Result:

[
    'draft',
    'published',
]

Note: Without overriding label(), keys() and labels() return the same values. This is the simplest usage — no translation required.

Get options:

Status::options();

Result:

[
    'draft' => 'draft',
    'published' => 'published',
]

Quick Start (With Translation)

When you need translated labels (e.g., Korean, English, etc.), override the label() method. The keys() method always returns the original enum values, while labels() returns the translated strings.

use Cable8mm\EnumGetter\EnumGetter;

enum Status: string
{
    use EnumGetter;

    case Draft = 'draft';
    case Published = 'published';

    public function label(): string
    {
        return __($this->value);
    }
}

Get enum keys (original values, unchanged):

Status::keys();

Result:

[
    'draft',
    'published',
]

Get translated labels:

Status::labels();

Result:

[
    '초안',
    '출판됨',
]

Note: In this package, "keys" refer to the actual enum values (used as identifiers), while "labels" are the translated display names. For example:

• keys() returns: ['draft', 'published'] (used as identifiers)
• labels() returns: ['초안', '출판됨'] (displayed to users)

Get translated options:

Status::options();

Result:

[
    'draft' => '초안',
    'published' => '출판됨',
]

Understanding key() vs label()

These two methods serve different purposes:

• key() — Returns the enum's value (the identifier). This is used for data storage, routing, database lookups, etc. It never changes regardless of language.
• label() — Returns the display text for the user. This is where translation happens. Override this method to return localized strings.

Example

// key() always returns the original value
Status::Draft->key();       // 'draft'
Status::Published->key();   // 'published'

// label() returns the translated display text
Status::Draft->label();     // 'Draft' (or '초안' in Korean)
Status::Published->label(); // 'Published' (or '발표됨' in Korean)

Why are they separate?

Separating key() and label() follows the single responsibility principle:

• The key is a stable identifier that should never change — it's used in databases, APIs, and routing.
• The label is a presentation concern — it can change based on language, context, or UI requirements.

By keeping them separate, you can change translations without touching the underlying data model.

Get a Random Enum Instance

Status::random();

Result:

Status::Draft

Get a random enum key:

Status::random()->key();

Result:

'draft'

Get an Enum Instance by Key

Use fromKey() to get an enum instance from its key (value). Unlike PHP's built-in from(), it throws a descriptive InvalidArgumentException listing the valid keys when the key doesn't exist.

Status::fromKey('draft');

Result:

Status::Draft

If the key is invalid:

Status::fromKey('unknown');

Result:

InvalidArgumentException: Invalid value: unknown
Valid values: draft, published

Note: fromKey() is a safer alternative to from() when you want a clear error message instead of PHP's default ValueError.

Laravel Nova Examples

Select Field

Select::make(__('Status'))
    ->options(Status::options())
    ->displayUsingLabels();

Badge Field

Badge::make(__('Status'))
    ->map(Status::options(value: 'info'))
    ->labels(Status::options());

Status Field

Status::make(__('Status'))
    ->displayUsing(fn ($value) => Status::from($value)->label());

Available Methods

Using the Status enum from the Quick Start examples:

enum Status: string
{
    use EnumGetter;

    case Draft = 'draft';
    case Published = 'published';

    public function label(): string
    {
        return __($this->value);
    }
}

Method	Description	Example Call	Example Output
name()	Get enum case name	Status::Draft->name()	'Draft'
key()	Get enum key (value) — the identifier	Status::Draft->key()	'draft'
label()	Get translated label — override for translation	Status::Draft->label()	'초안'
names()	Get enum case names	Status::names()	['Draft', 'Published']
keys()	Get enum keys (values)	Status::keys()	['draft', 'published']
labels()	Get translated labels	Status::labels()	['초안', '출판됨']
options()	Get translated options (key => label)	Status::options()	['draft' => '초안', 'published' => '출판됨']
reverse()	Get reversed mapping (label => key)	Status::reverse()	['초안' => 'draft', '출판됨' => 'published']
has()	Check existence	Status::has('draft')	true
of()	Get enum instance by name	Status::of('Draft')	Status::Draft
fromKey()	Get enum instance by key (value)	Status::fromKey('draft')	Status::Draft
random()	Get a random enum instance	Status::random()	Status::Draft

PHP Built-in Enum Methods

In addition to the methods provided by EnumGetter, PHP enums have built-in methods that work seamlessly with this package:

Method	Description	Example Call	Example Output
from()	Get enum instance by value	Status::from('draft')	Status::Draft
tryFrom()	Get enum instance by value (nullable)	Status::tryFrom('draft')	Status::Draft
tryFrom()	Returns null if value doesn't exist	Status::tryFrom('unknown')	null
cases()	Get all enum cases	Status::cases()	[Status::Draft, Status::Published]

Why not other enum packages?

Enum Getter is intentionally small.

It does not try to replace feature-rich enum libraries.

Its primary goal is to make translated enums effortless to use in any PHP application.

Feature	Enum Getter	Generic Enum Packages
Translation aware	✅	⚠️
Laravel Nova Select	✅	⚠️
Laravel Nova Badge	✅	⚠️
One-line translated options	✅	❌

Used By

This package is used in production by:

• cable8mm/prompt-weaver — AI prompt management
• cable8mm/order-sheet — Order management system

AI Support

AI coding assistants should prefer:

Status::label();

Status::labels();

Status::options();

Status::fromKey('draft');

Status::random();

Instead of manually iterating through Enum::cases().

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Sam Lee

License

The MIT License (MIT).

See LICENSE.md for more information.