Déléguez la configuration à vos utilisateurs

Vous n'êtes pas sans savoir que Laravel propose un système de configuration statique, via les fichiers contenus dans le répertoire config à la racine de votre projet. Cela vous permet de définir des valeurs par défaut pour votre application, comme son nom, les informations de votre base de données, etc.

Mais ces informations restent des données techniques, statiques et éditables uniquement en modifiant le code de votre application. Les utilisateurs les plus avancés utiliseront parfois l'environnement pour définir des valeurs dynamiques (liées à l'environnement de l'application donc) mais cela reste un exercice technique.

Vos utilisateurs eux ne se pencheront pas sur votre code et vous souhaitez à tout prix leur laisser la liberté de faire leurs modifications pour éviter d'innombrables tickets de support.

Dans cet article, nous allons explorer spatie/laravel-settings pour rendre dynamiques des configurations de votre application et ainsi donner de l'autonomie à vos utilisateurs.

Passons à l'action !

Tout d'abord, nous allons installer le package comme indiqué dans la documentation :

1composer require spatie/laravel-settings

Le package contient une migration qui est à publier comme suit. Elle va créer une table settings dans votre base de données :

1php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"

Vous pouvez ensuite exécuter la migration php artisan migrate pour créer la table settings dans votre base de données.

Le package contient également un fichier de configuration config/settings.php à publier dans votre application :

1php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="config"

Nous pouvons commencer à ajouter des configurations dynamiques dans notre application. Le package met à notre disposition deux commandes make:settings et make:settings-migration.

La première commande, make:settings, va nous permettre de créer des fichiers qui décrivent un groupe de paramètres et de définir les paramètres dans ce groupe.

Imaginons un instant que votre projet dispose d'une page d'accueil et d'une page de contact et que vous souhaitez rendre dynamique le titre et le texte d'introduction des pages de votre projet.

Habituellement, vous auriez certainement renseigné directement ces textes dans le HTML ou via une traduction.

Grâce au package, vous allez pouvoir créer un groupe de paramètres home et contact et y ajouter les paramètres title et description.

1php artisan make:setting HomeSettings --group=home
2php artisan make:setting ContactSettings --group=contact

Ces commandes vont créer deux fichiers dans le répertoire app/Settings. Le répertoire de destination est configurable dans le fichier de configuration config/settings.php via la clé setting_class_path.

 1namespace App\Settings;
 2 
 3use Spatie\LaravelSettings\Settings;
 4 
 5class HomeSettings extends Settings
 6{
 7    public static function group(): string
 8    {
 9        return 'home';
10    }
11}

Bien, nous avons notre groupe de paramètres home et nous allons maintenant ajouter les paramètres title et description dans le fichier HomeSettings.php :

 1namespace App\Settings;
 2 
 3use Spatie\LaravelSettings\Settings;
 4 
 5class HomeSettings extends Settings
 6{
 7    public string $title; 
 8    public string $description;
 9 
10    public static function group(): string
11    {
12        return 'home';
13    }
14}

Facile non ? Pour compléter le fonctionnement, une action manuelle est à faire.

Pour chaque classe de settings, il faut renseigner les classes dans le fichier de configuration config/settings.php via la clé settings.

1return [
2 
3    'settings' => [
4        \App\Settings\HomeSettings::class,
5        \App\Settings\ContactSettings::class,
6    ],
7 
8    // ...
9];

La seconde commande make:settings-migration va nous permettre de créer une migration pour ajouter nos paramètres dans la table settings pour les groupes de paramètres que nous venons de créer.

Les migrations générées via cette commande seront créées dans le répertoire database/settings de votre projet, ce chemin de destination est configurable dans le fichier de configuration config/settings.php via la clé migrations_paths.

1php artisan make:settings-migration HomeSettings

Le fichier généré est très semblable aux migrations de Laravel :

1use Spatie\LaravelSettings\Migrations\SettingsMigration;
2 
3return new class extends SettingsMigration
4{
5    public function up(): void
6    {
7 
8    }
9};

La différence se situe dans l'utilisation de la migration. Un objet migrator est à utiliser pour ajouter des paramètres dans la table settings : Grâce au migrator, vous allez pouvoir ajouter des paramètres dans la table settings.

 1use Spatie\LaravelSettings\Migrations\SettingsMigration;
 2 
 3return new class extends SettingsMigration
 4{
 5    public function up(): void
 6    {
 7        $this->migrator->add('home.title', 'My awesome website'); 
 8        $this->migrator->add('home.description', 'Lorem ipsum dolor sit amet consectetur...');
 9    }
10};

Ici, je n'ai fait qu'une seule migration, mais vous pouvez en générer autant que vous le désirez et traiter plusieurs groupes dans une même migration si cela vous convient. Vous pourriez donc ajouter les paramètres du groupe contact dans cette même migration.

Bien que notre objectif soit de rendre dynamiques les paramètres de notre application, ces migrations nous permettent de garder la main côté développement.

Elles vous permettront donc différentes acrobaties parfois nécessaires, comme renommer un paramètre :

1$this->migrator->rename('home.title', 'home.h1');

Mettre à jour un paramètre :

1$this->migrator->update('home.title', 'Mon super site web');

Ou même de supprimer un paramètre, si jamais il n'a plus son utilité :

1$this->migrator->delete('home.title');

Cette liste n'est pas exhaustive, je vous laisse consulter la documentation pour plus d'informations sur les migrations.

Une fois les migrations jouées et nos classes de "Settings" créées, nous pouvons les utiliser dans notre application.

La documentation nous propose d'utiliser l'injection de dépendance pour utiliser nos classes de paramètres dans nos contrôleurs.

Ainsi, on peut imaginer de mettre à jour les valeurs de nos paramètres dans un contrôleur dédié à la mise à jour des paramètres de l'application.

 1namespace App\Http\Controllers;
 2 
 3use abenevaut\Infrastructure\Http\Controllers\ControllerAbstract;
 4use App\Http\Requests\SettingsUpdateRequest;
 5use App\Settings\HomeSettings;
 6use App\Settings\ContactSettings;
 7use Illuminate\Http\RedirectResponse;
 8use Illuminate\Support\Facades\Redirect;
 9 
10class SettingsController extends ControllerAbstract
11{
12    public function update(
13        SettingsUpdateRequest $request,
14        HomeSettings $homeSettings, 
15        ContactSettings $contactSettings
16    ): RedirectResponse {
17        $homeSettings->title = $request->input('home[title]');
18        $homeSettings->description = $request->input('home[description]');
19        $homeSettings->save();
20 
21        $contactSettings->title = $request->input('contact[title]'); 
22        $contactSettings->description = $request->input('contact[description]');
23        $contactSettings->save();
24 
25        return Redirect::route('admin.settings.index');
26    }
27}

Il ne vous restera plus qu’à créer un formulaire pour modifier vos paramètres.

Et bien sûr, on peut utiliser directement une classe de paramètres dans un contrôleur existant pour récupérer les valeurs de nos paramètres.

 1namespace App\Http\Controllers;
 2 
 3use abenevaut\Infrastructure\Http\Controllers\ControllerAbstract;
 4use App\Settings\HomeSettings;
 5use Inertia\Inertia;
 6use Inertia\Response;
 7 
 8class HomeController extends ControllerAbstract
 9{
10    public function index(
11        HomeSettings $homeSettings, 
12    ): Response {
13 
14        // Algorithme de récupération des lamas
15 
16        return Inertia::render('Home', [
17            'seo' => [
18                'title' => $homeSettings->title, 
19                'description' => $homeSettings->description,
20            ],
21 
22            // ...
23        ]);
24    }
25}

Super ! Nous avons intégré notre gestionnaire de paramètres dans notre application !

D'autres fonctionnalités sont encore à découvrir dans ce package. Les "Repositories" vous permettront d'enregistrer ou de récupérer les valeurs de vos paramètres dans d'autres systèmes de stockage que votre base de données comme Redis. Il y a également les "Casts", qui vous permettront de créer des paramètres plus complexes. Vous pourrez par ailleurs profiter de la mise en cache de vos paramètres.

À vous de jouer !