Laravel Enum helpers

Dit pakket brengt een aantal helpers voor native PHP Enums

Installatie

Je kunt het pakket installeren via composer:

composer require isap-ou/laravel-enum-helpers

Je zult waarschijnlijk de uitgebreide configuratie moeten aanpassen, zodat je het config bestand kunt publiceren met:

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

Standaard config

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

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

    'post_migrate' => true,

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

1. enum_locations - pad waar enums zich bevinden. Sleutel is directory met enums, waarde - namespace voor gespecificeerde directory
2. post_migrate - post migrate event listener in- of uitschakelen
3. js_objects_file - pad voor gegenereerde js uitvoer
4. label.prefix - krijg standaard prefix voor vertalingen van enum velden
5. label.namespace - krijg standaard prefix voor vertalingen van enum namespace (bij gebruik als onderdeel van eigen pakket)

Beschikbare helpers

Migratie helper

De eenvoudige manier om alle enums toe te voegen aan database kolommen.

Voeg gewoon toe aan Enum eigenschap InteractWithCollection

use IsapOu\EnumHelpers\Concerns\InteractWithCollection;

enum ExampleEnum: string
{

    use InteractWithCollection;

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

En in migratieklasse

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());
            ...
        });
    }
}

Enum kolommen bijwerken in DB

Met het Artisan commando kun je beschikbare (mogelijke) waarden bijwerken voor een specifieke enum kolom.

Wijzig enum:

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'
        ];
    }
}

En voer het commando uit

php artisan enum-helpers:migrate:enums

Er is ook standaard een listener ingeschakeld die wordt uitgevoerd na een succesvolle migratie. Om deze uit te schakelen bewerk enum-helpers.php:

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

PHP enums converteren naar JS objecten

Met het Artisan commando kun je js objecten genereren op basis van enums

Enum wijzigen:

use IsapOu\EnumHelpers\Contracts\UpdatableEnumColumns;

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

En voer het commando uit

php artisan enum-helpers:js:export

Uitvoer zal

export const ExampleEnum = Object.freeze({ENUM_ONE: 'enum_one', ENUM_TWO: 'enum_two'})

Je kunt het uitvoerpad opgeven in de configuratie enum-helpers.php

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

Label helper

Met de Label helper kun je een enum instantie omzetten in een tekstlabel, waardoor het handig is om menselijk leesbare, vertaalbare enum waarden weer te geven in je UI.

use IsapOu\EnumHelpers\Concerns\HasLabel;

enum ExampleEnum: string
{
    use HasLabel;

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

Je kunt een tekstlabel ophalen voor een enum instantie met de getLabel methode:

ExampleEnum::ENUM_ONE->getLabel()

Standaard probeert de methode getLabel een vertaalsleutel te vinden volgens deze opmaak: ExampleEnum.ENUM_ONE. 1. ExampleEnum - De class naam van de enum. 2. ENUM_ONE - De naam van de enum-case.

Parameters

De methode getLabel accepteert drie optionele parameters: 1. prefix: Hiermee wordt een voorvoegsel voorafgegaan aan de vertaalsleutel. 2. namespace: Voegt een naamruimte toe aan de vertaalsleutel. Dit is vooral handig bij het ontwikkelen van pakketten. 3. locale hiermee kun je de locale voor vertaling opgeven. Als deze niet wordt opgegeven, wordt de standaardtaal van de app gebruikt.

Voorbeeld met aangepaste parameters:

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

Hiermee wordt de Franse (fr) vertaling met de opgegeven prefix en naamruimte opgehaald.

methode getLabels

De getLabels methode retourneert een verzameling labels voor alle enum gevallen, waardoor het handig is om vertaalbare labels voor meerdere enum waarden tegelijk op te halen of weer te geven.

$labels = ExampleEnum::getLabels();

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

Voorvoegsel, naamruimte en locale aanpassen

Je kunt het voorvoegsel, de naamruimte en de locale voor de vertalingen aanpassen bij het ophalen van labels voor alle gevallen:

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

Globale configuratie voor voorvoegsel en naamruimte

Je kunt de prefix en namespace globaal definiëren in het configuratiebestand enum-helpers.config of overschrijven op enumniveau door de volgende methoden te definiëren:

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

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

De globale of per-enum configuraties worden gebruikt tenzij je aangepaste waarden opgeeft bij het aanroepen van getLabel of getLabels.

Optioneel. Interface \IsapOu\EnumHelpers\Contracts\HasLabel voor betere IDE-ondersteuning

Voor betere IDE ondersteuning kun je de interface \IsapOuEnumHelpers\HasLabel implementeren. Dit helpt bij het geven van autocomplete suggesties en verbetert de code hinting voor de getLabel methode bij het werken met enums.

FilamentPHP compatibiliteit

Deze helper is volledig compatibel met Enums in FilamentPHP

use Filament\Support\Contracts\HasLabel;

enum ExampleEnum: string implements HasLabel
{
    use HasLabel;

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

Bijdragen

Gelieve bugs of functieverzoeken in te dienen via de Github issues.

Pull requests zijn welkom!

Bedankt!

Licentie

Dit project is open-sourced software gelicenseerd onder de MIT Licentie.

Je bent vrij om het te gebruiken, aan te passen en te verspreiden in je projecten, zolang je voldoet aan de voorwaarden van de licentie.