chore: Initial commit

Author: domthomas-dev

.gitignore

@@ -0,0 +1,5 @@
+build/
+vendor/
+composer.lock
+.phpunit.result.cache
+.pest/

README.md

@@ -0,0 +1,238 @@
+# Laravel Localized Enum
+
+A Laravel package that provides automatic localization support for PHP enums, making it easy to display translated enum values in your application.
+
+## Installation
+
+You can install the package via Composer:
+
+```bash
+composer require domthomas-dev/laravel-localized-enum
+```
+
+The package will automatically register its service provider.
+
+## Usage
+
+### Basic Usage
+
+Add the `LocalizedEnum` trait to your enum:
+
+```php
+<?php
+
+namespace App\Enums;
+
+use DomThomas\LocalizedEnum\LocalizedEnum;
+
+enum ContactType: string
+{
+    use LocalizedEnum;
+
+    case EMAIL = 'email';
+    case PHONE = 'phone';
+    case SMS = 'sms';
+}
+```
+
+### Translation Files
+
+Create translation files for your enums in your `resources/lang` directory:
+
+```php
+// resources/lang/en/enums.php
+<?php
+
+use App\Enums\ContactType;
+
+return [
+    ContactType::class => [
+        'label' => [
+            ContactType::EMAIL->name => 'Email',
+            ContactType::PHONE->name => 'Phone',
+            ContactType::SMS->name => 'SMS',
+        ],
+        'description' => [
+            ContactType::EMAIL->name => 'Send via email',
+            ContactType::PHONE->name => 'Call by phone',
+            ContactType::SMS->name => 'Send text message',
+        ],
+    ],
+];
+```
+
+```php
+// resources/lang/fr/enums.php
+<?php
+
+use App\Enums\ContactType;
+
+return [
+    ContactType::class => [
+        'label' => [
+            ContactType::EMAIL->name => 'E-mail',
+            ContactType::PHONE->name => 'Téléphone',
+            ContactType::SMS->name => 'SMS',
+        ],
+        'description' => [
+            ContactType::EMAIL->name => 'Envoyer par e-mail',
+            ContactType::PHONE->name => 'Appeler par téléphone',
+            ContactType::SMS->name => 'Envoyer un SMS',
+        ],
+    ],
+];
+```
+
+### Getting Labels
+
+```php
+$contact = new Contact();
+$contact->type = ContactType::EMAIL;
+
+// Get default label
+echo $contact->type->label(); // "Email"
+
+// Get label in specific locale
+echo $contact->type->label(null, 'fr'); // "E-mail"
+```
+
+### Multiple Label Types
+
+You can define multiple label types for the same enum as shown in the translation files above:
+
+```php
+// Get description label
+echo ContactType::EMAIL->label('description'); // "Send via email"
+
+// Get default label (uses 'label' key)
+echo ContactType::EMAIL->label(); // "Email"
+```
+
+### For Select Inputs
+
+Generate arrays suitable for HTML select inputs:
+
+```php
+// Get all options for select
+$options = ContactType::forSelect();
+// Returns: ['email' => 'Email', 'phone' => 'Phone', 'sms' => 'SMS']
+
+// With placeholder
+$options = ContactType::forSelect(null, null, 'Choose contact type');
+// Returns: ['' => 'Choose contact type', 'email' => 'Email', ...]
+
+// With specific label type
+$options = ContactType::forSelect('description');
+
+// With specific locale
+$options = ContactType::forSelect(null, 'fr');
+
+// Exclude specific cases
+$options = ContactType::forSelect(null, null, null, [ContactType::SMS]);
+// Returns only EMAIL and PHONE options
+
+// Include only specific cases
+$options = ContactType::forSelect(null, null, null, null, [ContactType::EMAIL, ContactType::PHONE]);
+// Returns only EMAIL and PHONE options
+
+// Get structured options array
+$options = ContactType::options();
+// Returns: [
+//     ['value' => 'email', 'label' => 'Email'],
+//     ['value' => 'phone', 'label' => 'Phone'],
+//     ['value' => 'sms', 'label' => 'SMS']
+// ]
+```
+
+### Blade Usage
+
+```blade
+<!-- In a select input -->
+<select name="contact_type">
+    @foreach(ContactType::forSelect(null, null, 'Select type') as $value => $label)
+        <option value="{{ $value }}">{{ $label }}</option>
+    @endforeach
+</select>
+
+<!-- Select with filtered options -->
+<select name="preferred_contact">
+    @foreach(ContactType::forSelect(null, null, 'Choose method', [ContactType::SMS]) as $value => $label)
+        <option value="{{ $value }}">{{ $label }}</option>
+    @endforeach
+</select>
+
+<!-- Display enum label -->
+<p>Contact type: {{ $contact->type->label() }}</p>
+<p>Description: {{ $contact->type->label('description') }}</p>
+```
+
+## Translation Key Format
+
+The package automatically generates translation keys using this format:
+
+```
+{EnumClass}.{label_type}.{case_name}
+```
+
+For example:
+- `App\Enums\ContactType::EMAIL` → `App\Enums\ContactType.label.EMAIL`
+- With description: `App\Enums\ContactType.description.EMAIL`
+
+### Utility Methods
+
+```php
+// Get all enum values as array
+$values = ContactType::values();
+// Returns: ['email', 'phone', 'sms']
+
+// Filter enum cases
+$filtered = ContactType::filterCases([ContactType::SMS]); // Exclude SMS
+$onlyEmailPhone = ContactType::filterCases(null, [ContactType::EMAIL, ContactType::PHONE]); // Only EMAIL and PHONE
+```
+
+## Advanced Features
+
+### Fallback Behavior
+
+If a translation key is not found, the package will fall back to the enum case name:
+
+```php
+// If translation doesn't exist, returns the case name
+echo ContactType::EMAIL->label(); // "EMAIL" (if no translation found)
+```
+
+### Translation Structure
+
+The translation structure uses the enum class as the top-level key:
+
+```php
+use App\Enums\ContactType;
+
+return [
+    ContactType::class => [
+        'label' => [
+            ContactType::EMAIL->name => 'Email',
+            ContactType::PHONE->name => 'Phone',
+        ],
+        'description' => [
+            ContactType::EMAIL->name => 'Send via email',
+            ContactType::PHONE->name => 'Call by phone',
+        ],
+        // You can add custom label types
+        'short' => [
+            ContactType::EMAIL->name => 'E',
+            ContactType::PHONE->name => 'P',
+        ],
+    ],
+];
+```
+
+## Testing
+
+```bash
+composer test
+```
+
+## License
+
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

composer.json

@@ -0,0 +1,50 @@
+{
+    "name": "domthomas-dev/laravel-localized-enum",
+    "description": "A Laravel package for managing localized enums with automatic translation support",
+    "keywords": ["laravel", "enum", "localization", "translation", "i18n"],
+    "type": "library",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Dom Thomas",
+            "email": "[email protected]"
+        }
+    ],
+    "require": {
+        "php": "^8.1",
+        "illuminate/support": "^10.0|^11.0",
+        "illuminate/translation": "^10.0|^11.0"
+    },
+    "require-dev": {
+        "orchestra/testbench": "^8.0|^9.0",
+        "pestphp/pest": "^2.0",
+        "pestphp/pest-plugin-laravel": "^2.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "DomThomas\\LocalizedEnum\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "DomThomas\\LocalizedEnum\\Tests\\": "tests/"
+        }
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "DomThomas\\LocalizedEnum\\LocalizedEnumServiceProvider"
+            ]
+        }
+    },
+    "minimum-stability": "stable",
+    "prefer-stable": true,
+    "scripts": {
+        "test": "pest"
+    },
+    "config": {
+        "allow-plugins": {
+            "pestphp/pest-plugin": true
+        }
+    }
+}

phpunit.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+>
+    <testsuites>
+        <testsuite name="Package Test Suite">
+            <directory suffix=".php">./tests</directory>
+        </testsuite>
+    </testsuites>
+    <coverage>
+        <include>
+            <directory suffix=".php">./src</directory>
+        </include>
+    </coverage>
+    <logging>
+        <junit outputFile="build/report.junit.xml"/>
+    </logging>
+</phpunit>