| Laravel

Voyager est un outil pour créer facilement et automatiquement l'administration d'un site, c'est du moins la proposition. J'avais décrit déjà cet outil dans un article qui commence à dater, alors le présent article est une version actualisée du précédent pour lequel Voyager en était à une version alpha. Je vous propose de découvrir cet outil et de voir ce qu'il a à nous offrir et comment il a évolué depuis son lancement.

Installation

La première chose à faire est d'installer Voyager. Comme c'est un package standard c'est facile à faire. Il suffit dans un premier temps de créer une nouvelle installation de Laravel 8 (pas besoin de l'authentification) avec une base de données bien référencée dans le fichier .env puis d'ajouter le package :

composer require tcg/voyager

Ensuite il y a une commande d'artisan pour l'installer :

php artisan voyager:install

Mais comme cette commande fait une installation vierge on va lui préférer celle avec l'option qui ajoute un administrateur et du contenu :

php artisan voyager:install --with-dummy

C'est Voyager qui se charge de la création des tables dans la base, on n'a pas à se préoccuper des migrations. On dénombre 17 tables créées :

Précisez bien votre url de base dans le fichier .env, par exemple :

APP_URL=http://voyager.oo

A la base tout est en anglais mais évidemment on a la traduction des titres et autres boutons en français et on peut changer la locale dans config/app.php :

'locale' => 'fr',

On dispose d'ailleurs d'un grand nombre de langues disponibles :

Les éléments pour connecter l'administrateur sont :

email : admin@admin.com 
password : password

On peut maintenant accéder à l'administration avec

.../admin

Il faut alors se connecter avec un joli formulaire :

Et on arrive enfin dans l'administration :

Tout fonctionne et l'esthétique est au rendez-vous ! En plus on dispose de vidéos de présentation ici. Et d'une documentation fournie :

La configuration

On peut changer des réglages de Voyager dans config/voyager.php :

'user' => [
    'add_default_role_on_register' => true,
    'default_role'                 => 'user',
    'default_avatar'               => 'users/default.png',
    'redirect'                     => '/admin',
],

Ici on peut régler ce qui concerne les utilisateurs au niveau des rôles, de l'avatar et de la redirection.

On trouve dans le même fichier des réglages concernant :

l'espace de nom pour les contrôleurs
le storage
les fichiers masqués pour le medias manager
les réglages pour la base de données
les langues
le dashboard
les breads (on voit plus loin de quoi il s'agit)
les assets...

A priori on ne va pas toucher à tout ça pour nos essais mais c'est bon à savoir.

Les routes

On a évidemment de nouvelles routes pour l'administration qui seraient trop longues à lister ici. Dans notre fichier routes/web.php on trouve ce nouveau code :

Route::group(['prefix' => 'admin'], function () {
    Voyager::routes();
});

Il est ainsi facile de changer le préfixe ou d'ajouter un middleware.

Les entités

Voyons un peu ce qui est en place comme entités...

Les rôles

À partir de l'administration on peut gérer les rôles :

De base on n'en a que 2 (d'ailleurs la pagination n'est pas très heureuse là...).

On a les actions classiques (voir, modifier, supprimer, créer un nouveau).

En mode création ou modification on peut gérer très précisément les permissions :

Je n'ai pas tout mis sur l'illustration, on a aussi les users, les pages, les posts, les catégories. Je suppose que tout ça est modifié de façon dynamique quand on change des entités, je vérifierai plus loin.

Les utilisateurs

On peut aussi gérer les utilisateurs :

On n'a que l'administrateur au départ. On retrouve toutes les actions classiques à ce niveau également. On peut remarquer la gestion de l'avatar.

J'arrive facilement à ajouter un utilisateur :

Les petites icônes pour l'ordre de tri fonctionne bien (sauf pour les rôles), on se demande juste l'intérêt d'en avoir sur la colonne des avatars et des boutons...

Les catégories

On a aussi des catégories, de quoi ? D'articles.

On peut d'ailleurs avoir des catégories de catégories et ainsi avoir un système hiérarchisé.

Les articles

On a des articles (posts) :

On dispose des colonnes classiques (title, status, created_at) mais aussi on peut associer une image, du seo (pour les metas) et une mise en avant (featured).

En mode création ou édition, en plus des classiques titres et contenu, on peut agir sur les détails de l'article :

Les statuts sont : draft, pending et published. On a aussi un formulaire pour l'image :

Et un autre pour le SEO :

Enfin on dispose aussi d'une zone de saisie pour une courte description de l'article :

On a donc quelque chose de très complet pour les articles !

Les pages

On a aussi des pages :

Moins de colonnes que les articles : titre, corps, résumé, slug, metas, statut (actif ou non) et image.

Les médias

Les médias sont très bien gérés :

Ils sont organisés en dossiers :

Mais on peut complètement changer cette organisation. D'autre part on peut envoyer, déplacer, renommer, visualiser ou supprimer une image.

Par contre au niveau de l'insertion d'une image dans une page ou un article je n'ai pas vu la possibilité d'en prendre une dans la librairie, on peut juste en télécharger une :

On peut d'ailleurs voir que l'éditeur choisi est un grand classique : TinyMCE.

Gestion des tables de la base

On peut gérer les tables de la base à partir de l'administration :

On peut avec View analyser les colonnes de la table :

Mais on peut aussi modifier tout ça à partir d'un formulaire :

On a ainsi un contrôle direct total sur la table.

BREAD

Un aspect intéressant de Voyager est la facilité de mise en place des opérations de base sur la base de données :

BROWSE
READ
EDIT
ADD
DELETE

Ce qui donne l'acronyme BREAD, du pain sur la planche ! Lorsque le BREAD est déjà en place on a des boutons sinon on a un lien pour créer un BREAD :

Pour chaque colonne d'une table on peut définir précisément les opérations possibles, le type de contrôle (text, checkbox, textarea...) à prévoir et le nom à afficher :

Il y a en plus une zone de saisie (en JSON) pour apporter certains détails :

par exemple pour renseigner les options d'une boîte déroulante
pour préciser des règles de validation
pour définir les relations

Prenons des exemples, pour les pages la colonne status :

{
    "default": "INACTIVE",
    "options": {
        "INACTIVE": "INACTIVE",
        "ACTIVE": "ACTIVE"
    }
}

On définit ici les deux options ainsi que celle par défaut. Un exemple avec une relation dans la table des catégories pour la colonne parent_id :

{
    "default": "",
    "null": "",
    "options": {
        "": "-- None --"
    },
    "relationship": {
        "key": "id",
        "label": "name"
    }
}

Pour la relation (relationship) on se réfère à l'id et on va afficher le name. Évidemment la relation doit exister dans le modèle :

public function parentId()
{
    return $this->belongsTo(self::class);
}

Là c'est une autoréférence pour avoir des sous-catégories. Du coup quand on ajoute une catégorie on a un remplissage correct de la zone déroulante :

C'est astucieux comme approche...

Les menus

En plus Voyager permet la gestion de menus :

On dispose d'un builder graphique intuitif :

Et pour chaque item un réglage des paramètres à partir d'un formulaire :

L'intégration d'un menu se fait avec un helper dans une vue :

menu('main')

On obtient une simple liste sans style, pour avoir la version Bootstrap c'est facile :

menu('main', 'bootstrap')

Et évidemment on peut prévoir sa propre mise en forme.

Créer

On a vu ci-dessus l'existant mais évidemment ce qui est intéressant c'est de voir comment compléter tout ça en fonction de nos besoins. On va donc imaginer qu'on doit gérer une collection de livres et que ceux-ci ont comme auteurs les personnes de la table users.

On va donc pour commencer créer une table books en demandant la création du modèle :

La table se crée correctement :

On dispose d'un bouton pour créer le BREAD pour cette table :

Par contre le modèle ne va pas se loger là où on veut, on est encore à la mode antérieure à Laravel 8 :

Dans la configuration je trouve ce réglage :

/*
|--------------------------------------------------------------------------
| Models config
|--------------------------------------------------------------------------
|
| Here you can specify default model namespace when creating BREAD.
| Must include trailing backslashes. If not defined the default application
| namespace will be used.
|
*/

'models' => [
    //'namespace' => 'App\\',
],

Apparemment ça ne concerne que la création des BREAD, on va déplacer manuellement le modèle (sans oublier de changer l'espace de noms) :

Et changer la configuration pour la suite :

'models' => [
    'namespace' => 'App\\Models\\',
],

On crée le BREAD :

On se retrouve avec un item dans le menu latéral :

Et une page pour le moment vide :

On va prévoir une relation avec les users :

De cette manière quand on ajoute un livre on accède aux utilisateurs :

On peut ainsi facilement créer des livres :

On peut aussi les voir, les modifier et les supprimer. On a fait ça en quelques clics avec des formulaires relativement simples. Ça doit évidemment un peu se compliquer si on veut des choses particulières...

Conclusion

Voyager est très élégant, il se situe entre le générateur et le CMS en un lieu plutôt judicieux. On peut facilement le mettre à son goût par exemple en overridant les fichiers ou les routes, ce qui est bien expliqué dans la documentation.

Personnellement j'hésite toujours à utiliser ce genre d'outil parce que je me dis qu'à un moment donné je vais perdre le temps que j'ai gagné par ailleurs parce que je vais vouloir faire quelque chose qui ne rentre pas dans les possibilités du système et je vais devoir un peu jongler...