Le bundle EasyAdmin pour Symfony

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 ?

Les bundles d’administration conçus pour Symfony

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.

• Sonata est un bundle très riche en fonctionnalités. Ces dernières ne sont néanmoins pas toutes documentées. De ce fait, l’outil reste assez complexe lorsque l’on débute.
• EasyAdmin est, quant à lui, un peu plus limité en features. Il est cependant très simple d’utilisation et possède une documentation très complète.

Que propose EasyAdmin ?

• Le bundle EasyAdmin supporte Symfony 2.x, 3.x et 4.x.
• Il propose de réaliser des opérations SCRUD (Search/Create/Read/Update/Delete) très facilement sur nos entités Doctrine (ORM seulement, ODM non supporté).
• La configuration des entités se fait via des fichiers yaml où il est possible déterminer à quoi ressembleront les 5 vues/actions disponibles : Search, List, Show, Edit et New. Le but de l’article n’étant pas de répéter ce qui est dit dans la documentation du bundle, je vous invite à y faire un tour pour voir à quoi ressemblent ces “vues”.
• Le mode “listing” propose un champ de recherche full-text, une pagination et la possibilité de trier les colonnes par défaut.
• Le bundle est traduit dans des dizaines de langues différentes, ce qui représente une grosse valeur ajoutée si vous avez des besoin d’internationalisation.
• EasyAdmin est rapide et performant dans ses tâches, permettant une navigation fluide.

L’installation

L’installation se fait simplement grâce à l’utilisation des recettes Symfony Flex.

composer require admin

Cette recette va automatiquement générer les fichiers de configuration nécessaires au bon fonctionnement de EasyAdmin. Vous aurez un fichier de route vous permettant de sélectionner le préfixe à utiliser pour accéder à l’administration, et un fichier de configuration pour définir les entités qui seront administrables (vous pourrez aussi gérer le design du backoffice).

Utilisation

L’utilisation du bundle se fait très simplement grâce à la configuration YAML.

easy_admin:
    entities:
        # List the entity class name you want to manage
        - App\Entity\Product
        - App\Entity\Category
        - App\Entity\User

Quelques conseils pour enrichir EasyAdmin

Contrôle d’accès

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.

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.

Améliorer les listings

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.

Surcharger les templates

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'

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 :

• Remplacer le template par défaut de votre listing par un template custom qui étend celui d’EasyAdmin. Il suffit de rajouter cette ligne à votre template twig :

{% extends 'bundles/EasyAdminBundle/default/list.html.twig' %}

• Il faut ensuite récupérer les informations nécessaires dans l’URL du listing, comme l’entité sur laquelle on est, l’action, les informations du menu, les colonnes triées et la page courante :

{% 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')
   }) %}

• Maintenant qu’on a le chemin sans les informations liées aux filtres, il suffit de rajouter le bouton au composant de filtres. Pour cela, il faut surcharger le bloc twig des filtres :

{% 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.