Aide pour les Enums Laravel

Ce paquetage apporte des aides pour les Enums PHP natifs

Installation

Vous pouvez installer le paquet via composer :

composer require isap-ou/laravel-enum-helpers

Vous aurez probablement besoin d'éditer la configuration étendue, de sorte que vous pouvez publier le fichier de configuration avec :

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

Configuration par défaut

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

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

    'post_migrate' => true,

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

enum_locations - chemin où se trouvent les enums. La clé est le répertoire avec les enums, la valeur - l'espace de noms pour le répertoire spécifié
post_migrate - activer ou désactiver l'écouteur d'événements post-migration
js_objects_file - chemin pour la sortie js générée
label.prefix - obtenir le préfixe par défaut pour les traductions des champs de l'énumération
label.namespace - obtenir le préfixe par défaut pour les traductions de l'espace de noms des enums (lors de l'utilisation en tant que partie de son propre package)

Aides disponibles

Aide à la migration

La façon la plus simple d'ajouter tous les enums aux colonnes de la base de données.

Il suffit d'ajouter le trait Enum InteractWithCollection

use IsapOu\EnumHelpers\Concerns\InteractWithCollection;

enum ExampleEnum: string
{

    use InteractWithCollection;

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

Et dans la classe de migration

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

Mise à jour des colonnes d'énumérations dans la base de données

La commande Artisan permet de mettre à jour les valeurs disponibles (possibles) pour une colonne d'énumération spécifique.

Modifiez l'énumération :

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

Et exécutez la commande

php artisan enum-helpers:migrate:enums

Il existe également un listener activé par défaut qui s'exécute après une migration réussie. Pour le désactiver, éditez enum-helpers.php:

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

Convertir les enums PHP en objets JS

La commande Artisan permet de générer des objets JS basés sur des enums

Modifiez enum :

use IsapOu\EnumHelpers\Contracts\UpdatableEnumColumns;

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

Et lancez la commande

php artisan enum-helpers:js:export

Le chemin de sortie

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

Vous pouvez spécifier le chemin de sortie dans la configuration enum-helpers.php

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

Aide à l'étiquetage

L'aide Label vous permet de transformer une instance d'énumération en un libellé textuel, ce qui est utile pour afficher des valeurs d'énumération traduisibles et lisibles par l'homme dans votre interface utilisateur.

use IsapOu\EnumHelpers\Concerns\HasLabel;

enum ExampleEnum: string
{
    use HasLabel;

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

Vous pouvez récupérer un libellé textuel pour une instance d'enum à l'aide de la méthode getLabel :

ExampleEnum::ENUM_ONE->getLabel()

Par défaut, la méthode getLabel tente de trouver une clé de traduction, selon le format suivant : ExampleEnum.ENUM_ONE. 1. ExampleEnum - Le nom de la classe de l'énumération. 2. ENUM_ONE - Le nom du cas de l'énumération.

Paramètres

La méthode getLabel accepte trois paramètres facultatifs : 1. prefix la méthode getLabel accepte trois paramètres facultatifs : : Prépare un préfixe pour la clé de traduction. 2. namespace la méthode getLabel accepte trois paramètres facultatifs: : Prépare un préfixe à la clé de traduction. Ceci est particulièrement utile lors du développement de paquets. 3. locale: Vous permet de spécifier la langue locale pour la traduction. Si ce paramètre n'est pas fourni, c'est la locale par défaut de l'application qui sera utilisée.

Exemple avec des paramètres personnalisés :

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

Cette méthode permet de récupérer la traduction en français (fr) avec le préfixe et l'espace de noms spécifiés.

méthode getLabels

La méthode getLabels renvoie une collection d'étiquettes pour tous les cas d'énumération, ce qui permet de récupérer ou d'afficher des étiquettes traduisibles pour plusieurs valeurs d'énumération à la fois.

$labels = ExampleEnum::getLabels();

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

Personnalisation du préfixe, de l'espace de nommage et de l'échelle locale

Vous pouvez personnaliser le préfixe, l'espace de noms et la langue locale pour les traductions lors de la récupération des étiquettes pour tous les cas :

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

Configuration globale du préfixe et de l'espace de noms

Vous pouvez définir les préfixes prefix et namespace globalement dans le fichier de configuration enum-helpers.config, ou les remplacer au niveau de l'énumération en définissant les méthodes suivantes :

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

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

Les configurations globales ou par enum seront utilisées à moins que vous ne fournissiez des valeurs personnalisées lorsque vous appelez getLabel ou getLabels.

Facultatif. Interface \IsapOu\EnumHelpers\Contracts\HasLabel pour un meilleur support IDE

Pour une meilleure prise en charge de l'IDE, vous pouvez mettre en œuvre l'interface \IsapOu\EnumHelpers\Contrats\HasLabel. Cela permet de fournir des suggestions d'autocomplétion et d'améliorer les indications de code pour la méthode getLabel lorsque vous travaillez avec des enums.

Compatibilité avec FilamentPHP

Cette aide est entièrement compatible avec les Enums dans FilamentPHP


use Filament\Support\Contracts\HasLabel;

enum ExampleEnum: string implements HasLabel
{
    use HasLabel;

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

Contribuer

Veuillez soumettre des bogues ou des demandes de fonctionnalités via les problèmes Github.

Les demandes d'extension sont les bienvenues !

Merci d'avance !

Licence

Ce projet est un logiciel open-source sous licence MIT.

Vous êtes libre de l'utiliser, de le modifier et de le distribuer dans vos projets, tant que vous respectez les termes de la licence.