mohamedbakr57/localized-enum

A simple and lightweight Laravel package that adds localized labels to native PHP enums using Laravel's translation system. Ideal for multi-language applications.

v1.0.0 2025-07-05 18:16 UTC

Requires

• php: ^8.1 || ^8.2 || ^8.3
• illuminate/contracts: ^10.0 || ^11.0 || ^12.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9 || ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1 || ^7.10.0
• orchestra/testbench: ^10.0 || ^11.0 || ^12.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/extension-installer: ^1.3 || ^2.0
• phpstan/phpstan-deprecation-rules: ^1.1 || ^2.0
• phpstan/phpstan-phpunit: ^1.3 || ^2.0

MIT

• Bakr

• laravel
• Bakr
• localized-enum

README

Localized Enum is a simple, lightweight Laravel package that adds localized labels to native PHP enums using Laravel’s translation system.
Perfect for multilingual applications and API responses with dynamic localization support.

📚 Table of Contents

• Usage
  • Basic Usage
  • Custom Translation Key
  • Fallback Default
  • Locale from Request Header
  • Override Header Key
• Features
• Installation
• Example Translation File
• Testing
• Development
• License
• Credits

🧪 Usage

Basic Usage

TestStatus::Approved->label(); 
// Output: "Approved by Admin" (if translation exists)

Custom Translation Key

TestStatus::Approved->label('custom.status.approved');
// Output: value from that specific key

Fallback Default

TestStatus::Approved->label('missing.key', 'Approved fallback');
// Output: "Approved fallback" if translation not found

Locale from Request Header

If you're building an API and send locale via headers:

GET /api/user
X-Locale: ar

The trait will use the X-Locale value automatically.

📝 Default header key is X-Locale, but it can be overridden.

Override Header Key

If your app uses a different header, override the method in your enum:

enum TestStatus: string
{
    use HasLabel;

    protected function getLocaleHeaderKey(): string
    {
        return 'Accept-Language';
    }
}

Or override getLabelLocale() entirely for full control.

✨ Features

• 🏷️ Adds label() method to native PHP Enums
• 🌐 Fully supports Laravel’s translation system
• 🧠 Smart fallback resolution (from multiple key patterns)
• 🧪 Works great in API responses
• 🔧 Easily override locale detection via request headers
• 🔄 Defaults to config('app.locale') if no locale is sent
• ⚡ Compatible with flat or nested translation files

📦 Installation

composer require mohamedbakr57/localized-enum

📌 Example Translation File

// lang/en/enums.php
return [
    'TestStatus.Approved' => 'Approved by Admin',
    'TestStatus.Pending'  => 'Waiting',
    'TestStatus.Rejected' => 'Rejected',
];

Supports both:

• enums.FQCN.CASE
• enums.Basename.CASE
• FQCN.CASE
• Basename.CASE
• Or just: 'Approved' => 'Approved Label' for flat key fallback

✅ Requirements

• PHP: ^8.1
• Laravel: ^10.0, ^11.0, ^12.0

🧪 Testing

composer test
composer test-coverage

Run Pint for formatting:

composer format

🧰 Development

git clone https://github.com/mohamedbakr57/localized-enum.git
cd localized-enum
composer install
composer test

📄 License

Licensed under MIT License

🙌 Credits

Built and maintained by Mohamed Bakr
Stars and PRs are welcome ⭐️