Laravel Enum Helpers

https://github.com/isap-ou/laravel-enum-helpers
Admin
Laravel Enum Helpers provides helpers for native PHP enums in Laravel, including translatable...
Tokens:9,349
Snippets:80
Trust Score:7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Install the package using Composer.

```bash
composer require isap-ou/laravel-enum-helpers
```

--------------------------------

### Install Laravel Boost skill

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Run the installer to add the Boost skill when the package is a direct dependency. If Boost is already installed, use the update command instead.

```bash
php artisan boost:install
```

```bash
php artisan boost:update
```

--------------------------------

### Generated JS object output

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Example output of the JS export command. The object is frozen and maps enum case names to their values.

```js
export const ExampleEnum = Object.freeze({ENUM_ONE:"enum_one", ENUM_TWO:"enum_two"});
```

--------------------------------

### FilamentPHP compatibility example

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Use the HasLabel trait alongside Filament's HasLabel interface for full compatibility with FilamentPHP enums.

```php

use Filament\Support\Contracts\HasLabel;
use IsapOu\EnumHelpers\Concerns\HasLabel as HasLabelTrait;

enum ExampleEnum: string implements HasLabel
{
    use HasLabelTrait;

    case ENUM_ONE = 'enum_one';
    case ENUM_TWO = 'enum_two';
}
```

--------------------------------

### getLabel() with custom parameters

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Pass prefix, namespace, and locale to getLabel() to customize the translation key. This example retrieves the French translation with the given prefix and namespace.

```php
ExampleEnum::ENUM_ONE->getLabel('custom_prefix', 'custom_namespace', 'fr');
```

--------------------------------

### Retrieve a label with getLabel()

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Call getLabel() on an enum instance to get its textual label. By default, it looks for a translation key in the format 'ExampleEnum.ENUM_ONE'.

```php
ExampleEnum::ENUM_ONE->getLabel()
```

--------------------------------

### Use InteractWithCollection trait to get enum cases as collections

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Add the `InteractWithCollection` trait to an enum to access collection helpers like `collection()`, `values()`, `keys()`, and `keyValuePairs()`. The example shows an `OrderStatus` enum with string-backed cases and the expected outputs for each helper.

```php
use IsapOu\EnumHelpers\Concerns\InteractWithCollection;

enum OrderStatus: string
{
    use InteractWithCollection;

    case NEW = 'new';
    case PAID = 'paid';
}

OrderStatus::collection();    // Collection of the case objects
OrderStatus::values();        // ['new', 'paid']
OrderStatus::keys();          // ['NEW', 'PAID']
OrderStatus::keyValuePairs(); // ['NEW' => 'new', 'PAID' => 'paid']
```

--------------------------------

### Get labels for all cases with getLabels()

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

getLabels() returns a collection of labels for all enum cases. The output shows the collection structure with case names as keys and labels as values.

```php
$labels = ExampleEnum::getLabels();

// Output:
// Illuminate\Support\Collection {#1234
//     all: [
//         "ENUM_ONE" => "Enum One Label",
//         "ENUM_TWO" => "Enum Two Label",
//     ],
// }
```

--------------------------------

### Use values() to define an enum column in a migration

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Use the `values()` method from the `InteractWithCollection` trait to define an enum column in a Laravel migration. The example shows a `$table->enum()` call with `OrderStatus::values()->toArray()` as the allowed values.

```php
$table->enum('status', OrderStatus::values()->toArray());
```

--------------------------------

### Run the export command

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Executes the artisan command that writes one line per enum to the js_objects_file, replacing old content. Run again after changing a JsConvertibleEnum enum.

```bash
php artisan enum-helpers:js:export
```

--------------------------------

### Publish enum-helpers config file

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Run this Artisan command to publish the package configuration to config/enum-helpers.php. The published file contains keys such as enum_locations, post_migrate, label.prefix, label.namespace, and js_objects_file.

```bash
php artisan vendor:publish --tag="enum-helpers-config"
```

--------------------------------

### getLabels() with custom parameters

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Customize prefix, namespace, and locale when retrieving labels for all cases.

```php
$customLabels = ExampleEnum::getLabels('custom_prefix', 'custom_namespace', 'fr');
```

--------------------------------

### Default Configuration

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Default configuration for enum locations, label settings, post-migrate behavior, and JS export path.

```php
return [
    'enum_locations' => [
        'app/Enums' => '\\App\\Enums\\',
    ],

    'label' => [
        'prefix' => 'enums',
        'namespace' => null,
    ],

    'post_migrate' => true,

    'js_objects_file' => 'resources/js/enums.js',
];
```

--------------------------------

### Migration using enum values

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Use ExampleEnum::values()->toArray() in a migration to create an enum column with all enum values. This is part of the migration helper workflow.

```php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('table_name', function (Blueprint $table){
            ...
            $table->enum('enum_column', ExampleEnum::values()->toArray());
            ...
        });
    }
}
```

--------------------------------

### Translation file for labels

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Default configuration expects labels in lang/{locale}/enums.php. The translation key is {namespace}::{prefix}.{EnumShortName}.{CASE_NAME}.

```php
return [
    'OrderStatus' => [
        'NEW' => 'New',
        'PAID' => 'Paid',
    ],
];
```

--------------------------------

### getLabels

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Returns a collection of labels for all enum cases. It accepts optional prefix, namespace, and locale parameters to customize the translations.

```APIDOC
## getLabels

### Description
Returns a collection of labels for all enum cases. It accepts optional prefix, namespace, and locale parameters to customize the translations.

### Method
Static method on enum class

### Endpoint
`ExampleEnum::getLabels()`

### Parameters
- `prefix` (string) - Optional - Prepends a prefix to the translation key.
- `namespace` (string) - Optional - Prepends a namespace to the translation key. Useful for packages.
- `locale` (string) - Optional - Specifies the locale for translation. Defaults to app's default locale.

### Request Example
```php
$labels = ExampleEnum::getLabels('custom_prefix', 'custom_namespace', 'fr');
```

### Response
Returns an `Illuminate\Support\Collection` mapping enum case names to their labels.

### Response Example
```php
Illuminate\Support\Collection {#1234
    all: [
        "ENUM_ONE" => "Enum One Label",
        "ENUM_TWO" => "Enum Two Label",
    ],
}
```
```

--------------------------------

### Pass optional arguments to label methods

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Both getLabel() and getLabels() accept optional prefix, namespace, and locale arguments. Empty arguments fall back to enum's getPrefix()/getNamespace().

```php
OrderStatus::NEW->getLabel('statuses', 'my-package', 'fr'); // trans('my-package::statuses.OrderStatus.NEW', locale: 'fr')
OrderStatus::getLabels(locale: 'fr');
```

--------------------------------

### Run enum-helpers:migrate:enums command to sync enum columns

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Run the `php artisan enum-helpers:migrate:enums` command to sync database enum columns. The command executes `ALTER TABLE {table} MODIFY COLUMN {column} ENUM(...)` for each pair and adds `DEFAULT '{value}'` when `tableColumnDefaults()` has a matching key. It skips tables and columns that do not exist.

```bash
php artisan enum-helpers:migrate:enums
```

--------------------------------

### Configure JS output path

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Set the output path for generated JS objects in the enum-helpers.php config file. The default is 'resources/js/enums.js'.

```php
return [
    ...
    
    'js_objects_file' => 'resources/js/enums.js'
    
    ...
]
```

--------------------------------

### Override prefix and namespace on enum level

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Define getPrefix() and getNamespace() methods in the enum to override global configuration. These are used unless custom values are passed to getLabel or getLabels.

```php
protected function getPrefix(): ?string
{
    return 'prefix';
}

protected function getNamespace(): ?string
{
    return 'namespace';
}
```

--------------------------------

### Exported JavaScript object

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

The output written to the js_objects_file. Do not edit by hand.

```js
export const OrderStatus = Object.freeze({NEW:"new", PAID:"paid"});
```

--------------------------------

### Implement UpdatableEnumColumns to sync database enum columns

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Implement the `UpdatableEnumColumns` contract to define which table columns should be synced with enum cases. The `tables()` method returns a map of table to column, and `tableColumnDefaults()` optionally provides default values keyed by `{table}_{column}`.

```php
use IsapOu\EnumHelpers\Contracts\UpdatableEnumColumns;

enum OrderStatus: string implements UpdatableEnumColumns
{
    case NEW = 'new';
    case PAID = 'paid';

    public static function tables(): array
    {
        return [
            'orders' => 'status',
        ];
    }

    // Optional. The key is "{table}_{column}". The value is an enum case.
    public static function tableColumnDefaults(): array
    {
        return [
            'orders_status' => self::NEW,
        ];
    }
}
```

--------------------------------

### getLabel

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Retrieves a textual label for an enum case. It attempts to find a translation key based on the enum class name and case name, with optional prefix, namespace, and locale parameters.

```APIDOC
## getLabel

### Description
Retrieves a textual label for an enum case. It attempts to find a translation key based on the enum class name and case name, with optional prefix, namespace, and locale parameters.

### Method
Instance method on enum case

### Endpoint
`ExampleEnum::ENUM_ONE->getLabel()`

### Parameters
- `prefix` (string) - Optional - Prepends a prefix to the translation key.
- `namespace` (string) - Optional - Prepends a namespace to the translation key. Useful for packages.
- `locale` (string) - Optional - Specifies the locale for translation. Defaults to app's default locale.

### Request Example
```php
ExampleEnum::ENUM_ONE->getLabel('custom_prefix', 'custom_namespace', 'fr');
```

### Response
Returns a string label for the enum case.

### Response Example
```php
"Enum One Label"
```
```

--------------------------------

### UpdatableEnumColumns::tableColumnDefaults()

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Optional method that returns a map of table_column keys to default enum cases. The key format is '{table}_{column}'.

```APIDOC
## UpdatableEnumColumns::tableColumnDefaults()

### Description
Optional method that returns a map of table_column keys to default enum cases. The key format is '{table}_{column}'.

### Method
tableColumnDefaults()

### Return Value
- Associative array of table_column => enum case

### Example
```php
public static function tableColumnDefaults(): array
{
    return [
        'orders_status' => self::NEW,
    ];
}
```
```

--------------------------------

### InteractWithCollection::keys()

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Returns a collection of the enum case keys (names). This method is available when the InteractWithCollection trait is used on an enum.

```APIDOC
## InteractWithCollection::keys()

### Description
Returns a collection of the enum case keys (names).

### Method
keys()

### Return Value
- Laravel Collection of enum case keys

### Example
```php
OrderStatus::keys(); // ['NEW', 'PAID']
```
```

--------------------------------

### UpdatableEnumColumns::tables()

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Returns a map of table names to column names that should be synchronized with the enum cases. This method must be implemented when using the UpdatableEnumColumns contract.

```APIDOC
## UpdatableEnumColumns::tables()

### Description
Returns an associative array mapping table names to column names that should be updated to match the enum cases.

### Method
tables()

### Return Value
- Associative array of table => column

### Example
```php
public static function tables(): array
{
    return [
        'orders' => 'status',
    ];
}
```
```

--------------------------------

### php artisan enum-helpers:migrate:enums

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Artisan command that synchronizes database enum columns with the enum cases defined in enums implementing UpdatableEnumColumns. It runs ALTER TABLE statements and adds defaults when configured.

```APIDOC
## php artisan enum-helpers:migrate:enums

### Description
Artisan command that synchronizes database enum columns with the enum cases defined in enums implementing UpdatableEnumColumns. It runs ALTER TABLE statements and adds defaults when configured.

### Method
Artisan command

### Usage
```bash
php artisan enum-helpers:migrate:enums
```

### Behavior
- Runs `ALTER TABLE {table} MODIFY COLUMN {column} ENUM(...)` for each table/column pair.
- Adds `DEFAULT '{value}'` when `tableColumnDefaults()` has a matching key.
- Skips tables and columns that do not exist.
```

--------------------------------

### InteractWithCollection::collection()

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Returns a Laravel collection of all enum cases. This method is available when the InteractWithCollection trait is used on an enum.

```APIDOC
## InteractWithCollection::collection()

### Description
Returns a Laravel collection containing all the enum case objects.

### Method
collection()

### Return Value
- Laravel Collection of enum case objects

### Example
```php
OrderStatus::collection();
```
```

--------------------------------

### InteractWithCollection::keyValuePairs()

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Returns an associative array mapping enum case keys to their values. This method is available when the InteractWithCollection trait is used on an enum.

```APIDOC
## InteractWithCollection::keyValuePairs()

### Description
Returns an associative array mapping enum case keys to their values.

### Method
keyValuePairs()

### Return Value
- Associative array of key-value pairs

### Example
```php
OrderStatus::keyValuePairs(); // ['NEW' => 'new', 'PAID' => 'paid']
```
```

--------------------------------

### Enum implementing JsConvertibleEnum

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Implement the JsConvertibleEnum contract to allow the artisan command to generate JS objects from enums.

```php
use IsapOu\EnumHelpers\Contracts\JsConvertibleEnum;

enum ExampleEnum: string implements JsConvertibleEnum
{
    case ENUM_ONE = 'enum_one';
    case ENUM_TWO = 'enum_two';
}
```

--------------------------------

### Enum implementing UpdatableEnumColumns

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Implement the UpdatableEnumColumns contract to allow the artisan command to update enum column values. The tables() method maps table names to column names.

```php
use IsapOu\EnumHelpers\Contracts\UpdatableEnumColumns;

enum ExampleEnum: string implements UpdatableEnumColumns
{

    case ENUM_ONE = 'enum_one';
    case ENUM_TWO = 'enum_two';
    
    public static function tables(): array
    {
        return [
            'table_name' => 'enum_column'
        ];
    }
}
```

--------------------------------

### Alias HasLabel trait for Filament compatibility

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

When implementing Filament's HasLabel interface, alias the trait to avoid name collision. The trait is compatible with Filament's contract.

```php
use Filament\Support\Contracts\HasLabel;
use IsapOu\EnumHelpers\Concerns\HasLabel as HasLabelTrait;

enum OrderStatus: string implements HasLabel
{
    use HasLabelTrait;

    case NEW = 'new';
}
```

--------------------------------

### Disable post-migrate listener

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Edit the enum-helpers.php config file to disable the listener that runs after a successful migration. Set 'post_migrate' to false.

```php
<?php 
return [
    ...
    
    'post_migrate' => false,
    
    ...
]
```

--------------------------------

### Implement JsConvertibleEnum marker interface

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Add the empty marker interface to an enum to make it exportable to JavaScript. The enum must be backed by a string type.

```php
use IsapOu\EnumHelpers\Contracts\JsConvertibleEnum;

enum OrderStatus: string implements JsConvertibleEnum
{
    case NEW = 'new';
    case PAID = 'paid';
}
```

--------------------------------

### InteractWithCollection::values()

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Returns a collection of the enum case values. This method is available when the InteractWithCollection trait is used on an enum.

```APIDOC
## InteractWithCollection::values()

### Description
Returns a collection of the enum case values.

### Method
values()

### Return Value
- Laravel Collection of enum case values

### Example
```php
OrderStatus::values(); // ['new', 'paid']
```
```

--------------------------------

### Override getPrefix() in enum

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Override getPrefix() to change the translation key prefix for a single enum. The method returns the label.prefix config by default.

```php
protected function getPrefix(): ?string
{
    return 'statuses';
}
```

--------------------------------

### Define an enum with HasLabel trait

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Use the HasLabel trait to enable label generation for enum cases. The enum must be backed by a string.

```php
use IsapOu\EnumHelpers\Concerns\HasLabel;

enum ExampleEnum: string
{
    use HasLabel;

    case ENUM_ONE = 'enum_one';
    case ENUM_TWO = 'enum_two';
}
```

--------------------------------

### Define table column defaults

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Optionally define a static method tableColumnDefaults() to set DEFAULT values for specific enum columns. The migrator appends DEFAULT '<case->value>' to the generated SQL for matching keys.

```php
    /**
     * Map "table_column" => enum case.
     * The migrator will generate "... DEFAULT '<case->value>'" .
     *
     * @return array<string, self>
     */
    public static function tableColumnDefaults(): array
    {
        return [
            'orders_status'      => self::NEW,
            'order_items_status' => self::NEW,
        ];
    }
```

--------------------------------

### Enum with InteractWithCollection trait

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/README.md

Add the InteractWithCollection trait to an enum to enable migration helper functionality. The trait provides the values() method used in migrations.

```php
use IsapOu\EnumHelpers\Concerns\InteractWithCollection;

enum ExampleEnum: string
{

    use InteractWithCollection;

    case ENUM_ONE = 'enum_one';
    case ENUM_TWO = 'enum_two';
}
```

--------------------------------

### Add HasLabel trait to enum

Source: https://github.com/isap-ou/laravel-enum-helpers/blob/main/resources/boost/skills/enum-helpers-development/SKILL.md

Add the HasLabel trait to an enum to enable translatable labels. The trait provides getLabel() and getLabels() methods.

```php
use IsapOu\EnumHelpers\Concerns\HasLabel;

enum OrderStatus: string
{
    use HasLabel;

    case NEW = 'new';
    case PAID = 'paid';
}

OrderStatus::NEW->getLabel();  // trans('enums.OrderStatus.NEW')
OrderStatus::getLabels();      // Collection: ['NEW' => '...', 'PAID' => '...']
```
Tokens:
Raw