EasyAdmin : un admin bundle simple et efficace pour Symfony
Nicolas Chevalier, Développeur web 30 avril 2019
Nicolas Chevalier, Développeur web 30 avril 2019
Un admin bundle (ou module d’administration en bon français) est un ensemble d’outils permettant de créer des interfaces d’administration plus ou moins avancées, et ce, sans réinventer la roue.
Tout ceux qui ont déjà eu à développer des back-offices customs savent à quel point ils peuvent être pénibles à faire évoluer et à maintenir dans le temps. Alors pourquoi s’embêter quand un admin bundle peut facilement faire 70% du travail et nous permettre de se concentrer sur les features spécifiques des clients ?
Côté Symfony, il existe 2 bundles d’administration réputés dont les documentations sont officiellement référencées : EasyAdmin et Sonata. Lequel choisir et dans quelles circonstances ?
Il faut noter que les deux bundles, bien qu’ayant la même mission, n’ont pas les mêmes cibles.
Il existe un bundle complémentaire permettant d’augmenter le nombre de fonctionnalités d’EasyAdmin. Nous le verrons un peu plus tard dans cet article.
Pour récapituler : EasyAdmin cible principalement les applications simples et de petite ou moyenne envergure (un site de news, un blog, des petits sites marchands, etc.).
Il est préférable d’utiliser Sonata si votre application comporte d'innombrables règles de gestion et de sécurité (un domaine qu’EasyAdmin ne maîtrise pas encore).
Comme expliqué plus haut, en dehors des fonctionnalités SCRUD du bundle, ce dernier se retrouve assez limité quand on aborde le sujet de “vues sécurisées”. En effet, il n’est pas possible de configurer une entité pour qu’elle ne soit utilisée que par tel ou tel rôle.
Cependant, grâce au côté Open Source du projet, il possible de combler ces lacunes soi-même ou, encore mieux, au travers d’un bundle complémentaire : EasyAdminExtension.
Ce bundle vise à apporter quelques fonctionnalités supplémentaires, dont un contrôle d’accès basé sur les rôles. Grâce à cela, il est possible de dire : “l’administration des produits ne doit être accessible que des Product Manager”. Ce qui se concrétise de cette manière :
easy_admin:
entities:
Product:
class: App\Entity\Product
role_prefix: ROLE_PRODUCT_MANAGER
Ainsi, toutes les vues liées à l’entité Product seront bloquées si l’utilisateur n’a pas le rôle ROLE_PRODUCT_MANAGER. En revanche le lien est toujours affiché dans le menu. Ceci n’est pas forcément toujours utile, voire encombrant pour les autres rôles. Un petit bout de configuration pour régler ceci :
easy_admin:
menu:
- { entity: 'Product', role: ROLE_PRODUCT_MANAGER }
Voilà, le lien n’est visible que par les personnes autorisées ! Il faut toutefois noter que seule l’entrée dans le menu est cachée. Ceci n’empêche pas d’accéder à la page par URL. C’est pour cela qu’il faut bien préciser le rôle sur la configuration de l’entité et pas uniquement dans celle du menu.
Le scénario que je viens de présenter est relativement simple et conviendra dans la plupart des cas. Il est cependant possible de pousser le concept un peu plus loin grâce à la mise en place d’une hiérarchie de rôles.
Si je reprends mon exemple, le Product Manager ne peut que manager l’entité Product. Dorénavant, il sera également en charge des Stocks et du Shipping.
Voici comment configurer le fichier security.yaml en conséquence :
security:
role_hierarchy:
ROLE_SUPER_MANAGER: [ROLE_PRODUCT_MANAGER,
ROLE_STOCK_MANAGER, ROLE_SHIPPING_MANAGER]
On pourra affecter ce nouveau rôle aux Product Manager qui hériteront automatiquement des responsabilités des stocks et des envois.
Il est également possible de dire que le rôle de Product Manager hérite des deux autres rôles et ainsi de se passer du rôle Super Manager. Cependant, pour de potentielles futures évolutions, il est préférable de garder les rôles liés à une entité le plus simple possible. En faisant ainsi, on peut garder une configuration des rôles simple du côté de nos fichiers EasyAdmin.
Il est possible que vous ayez besoin de proposer un champ de type “autocomplete” basé sur l’une de vos entité à vos utilisateurs. Pour cela, vous avez utilisé le type “EasyAdminAutocompleteType”. Celui-ci permet très facilement de proposer des résultats basés sur la classe que vous avez spécifié dans l’attribut “class” du field.
Un comportement gênant peut être engendré si vous avez paramétré un rôle sur la vue “list” de l’entité en question. Si l’on tente d’utiliser le champ avec un utilisateur au rôle inférieur, aucun résultat ne sera retourné.
L’origine du problème vient du fait que l’on ne peut pas différencier les configurations des actions “list” et “autocomplete” quand on spécifie un rôle (plus de détails dans cette issue github).
Pour résoudre ce problème, il existe deux options :
Les listings acceptent une configuration de filtres DQL. Ceci permet de limiter les données affichées par défaut. On peut, par exemple, vouloir un listing des produits dont les stocks sont quasiment écoulés :
list:
dql_filter: 'entity.stock < 50'
Et voilà, seulement les produits dont le stock est inférieur à 50 seront affichés dans la liste. A noter que par défaut, le DQL paramétré dans l’action “list” s’applique également à l’action “search”. Il est néanmoins possible de définir un autre filtre DQL sur cette dernière afin d’avoir deux comportements différents, si besoin.
Il est également possible de rendre le listing d’une entité plus dynamique grâce aux filtres apportés par le bundle EasyAdminExtension. On peut paramétrer des filtres de plusieurs types : select simple/multiple, booléen, chaîne de caractères ou numérique et même des champs en autocomplete. Les relations many-to-many ne sont toutefois pas supportées…
Vous l’aurez compris, ce bundle est un complément important, voire indispensable de par les fonctionnalités supplémentaires qu’il apporte !
Bien que tout à fait correcte, l’interface de base reste très basique (basée sur Bootstrap et suivant le template AdminLTE). Et c’est tout ce qu’on demande à un module d’administration : de la fonctionnalité, pas de l'esthétique.
Alors n’hésitez pas à customiser vos interfaces afin d'y apporter votre propre identité visuelle ou des fonctionnalités supplémentaires.
Vous pouvez tout simplement rajouter des assets custom via la configuration :
easy_admin:
design:
assets:
css:
- 'bundles/app/css/custom_admin.css'
js:
- 'bundles/app/js/custom_admin.js'
Ou bien surcharger n’importe quel template de la façon suivante :
easy_admin:
design:
templates:
# Twig namespace template syntax
paginator: '@App/Default/fragments/_paginator.html.twig'
Si la surcharge du template n’est nécessaire que pour certaines entités, il est possible de déplacer la configuration globale à l’intérieur de celles des entités concernées :
easy_admin:
entities:
Product:
# ...
templates:
# Twig namespace template syntax
paginator: '@App/Default/fragments/_paginator.html.twig'
Un exemple concret d’ajout de fonctionnalité par template custom : sur le screenshot des filtres (visible un peu plus haut dans le point “Améliorer les listings”), il y a un bouton “Réinitialiser les filtres”. Ce bouton n’est pas disponible par défaut mais se révèle très pratique. Voici comment le rajouter :
{% extends 'bundles/EasyAdminBundle/default/list.html.twig' %}
{% set path = path('easyadmin', {
'entity': app.request.query.get('entity'),
'action': app.request.query.get('action'),
'menuIndex': app.request.query.get('menuIndex'),
'submenuIndex': app.request.query.get('submenuIndex'),
'sortField': app.request.query.get('sortField'),
'sortDirection': app.request.query.get('sortDirection'),
'page': app.request.query.get('page')
}) %}
{% block list_form_filters %}
...
{% endblock list_form_filters %}
Un simple lien <a> avec un href pointant sur le chemin précédemment calculé fera l’affaire :
<a class="button" href="{{ path }}">
<small>Réinitialiser les filtres</small>
</a>
Et voilà ! Simple et efficace.
Il est facile et très rapide de créer une interface d’administration avec EasyAdmin, alors n’ayez crainte de perdre une semaine de développement !
Il est également possible d’utiliser EasyAdmin pour prototyper un Back Office pour une démonstration client et le remplacer par un autre admin bundle ou du custom après coup. Cela vous évite d’investir du temps dans un projet au cahier des charges encore incomplet ou auquel on ne donnera peut-être pas suite.
