Symfony 5: La Vía Rápida | Paso 9 – Configurando el panel de administración

Hoy continuamos con el paso 9 del libro oficial de Symfony 5: La Vía Rápida y nos toca entender como configurar el panel de administración para tu sitio.

Ahora que tenemos nuestros 2 entities creados: el de conferencia y el de comentarios, resulta muy sencillo y rápido crear la sección de administración para nuestro sitio. Si bien también lo podemos crear por nuestra cuenta y en ocasiones esto nos proporciona mucha flexibilidad, Symfony disponibiliza un bundle llamado EasyAdmin, que nos permite realizar por medio de «configuraciones» y no con «codificaciones» muchas de las funcionalidades más requeridas a la hora de crear CRUDs.

Un CRUD es el acrónimo de: Crear, Leer, Actualizar y Eliminar, pero, aunque muchas veces pensamos que un CRUD solo tiene una página de lista, un formulario de
creación y actualización, y una funcionalidad de borrado, existen varios conceptos muy importantes que sin ellos se podría decir que está incompleto, como por ejemplo: la capacidad de filtrado de registros, ordenamiento de columnas, paginaciones, validaciones de tipos de datos, mensajes de confirmación, etcétera.

Como estos conceptos son estándares para todos los CRUDs, EasyAdmin nos los da de fábrica y no tenemos que preocuparnos por implementar estos detalles, sino más bien configurar cómo los queremos.

Primeramente, recordemos que en el capítulo anterior creamos nuestros dos entities a partir de la información de nuestro DER. Cada una de estas clases representan a cada tabla de la base de datos y nos permite que Doctrine tenga conocimiento de esta estructura. Uno de los puntos fuertes de utilizar esta metodología, en la que primeramente le enseñamos a Doctrine que es lo que tenemos como estructura y luego le dejamos que él se encargue de crear nuestra base de datos,es justamente la capacidad que tiene mediante la orientación a objetos para lograr este tipo de funcionalidades que vamos a ver en este capítulo. Tengamos en mente que cada conferencia puede tener asociados varios comentarios y que un comentario será realizado siempre sobre una conferencia. Cada fila de nuestra tabla de conferencias será representada por un objeto de tipo entidad de la clase Conference y de la misma forma cada fila de comentario será representada por un objeto Comment.

Podríamos también decir que un objeto Conference tiene una propiedad en plural llamada «comments», que contiene un array, a nivel de objetos, de los comentarios asociados a una instancia de conferencia en particular.

Configurando EasyAdmin

Entre los bundles de administración de backoffice existen dos grandes proyectos en Symfony: EasyAdmin y SonataAdmin. SonataAdmin es un proyecto con más años que EasyAdmin, desarrollado y mantenido por Sonata Project. Si lo buscamos dentro del sitio de recetas de Symfony Flex, podemos ver que se encuentra como una «contribución», sin embargo, si buscamos EasyAdmin, podemos ver que se encuentra clasificado como «oficial». Hace muchos años vengo trabajando con SonataAdmin y es un proyecto súper completo, útil e interesante. Podría decir que tiene solo dos problemas: (1) Por un lado su documentación no tiene el mismo nivel de mantenimiento que la documentación oficial de Symfony. Existen algunos temas sin contemplar y es necesario siempre recurrir a una búsqueda para solucionar ciertos problemas. (2) El segundo problema es que su actualización no corre tan rápido cuando se liberan nuevas versiones de Symfony, y nos toca esperar unos meses para poder utilizarlo con nuevos proyectos, o incluso cuando migramos una aplicación existente a una nueva versión del framework.

Este libro se basa en la versión 2 de EasyAdmin y recientemente fue lanzada la versión 3. La gran diferencia que puedo notar rápidamente es que la versión 2 de EasyAdmin siempre se basó en configuraciones mediante archivos yaml, a diferencia de SonataAdmin que siempre las configuraciones fueron basadas en clases PHP a la que se les llama «Admins».

Prácticamente se pueden realizar las mismas configuraciones, pero a mi gusto prefiero tener la flexibilidad de PHP a la hora de realizar configuraciones ya que nos proporciona muchas más herramientas.

EasyAdmin 3 realizó este gran salto, las configuraciones ahora ya pueden ser realizadas mediante código PHP, aunque ojo que siempre menciono la palabra configuración» y no «codificación», porque si bien es lo mismo, intento explicar que la diferencia es que no se tiene que programar por ejemplo un ordenamiento de columnas que implica ejecutar diferentes ORDER BY en las sentencias a la base de datos, sino que más bien se configuran que columnas que deberían de tener ordenamiento y el bundle ya lo tiene solucionado.

Para no romper la dinámica del libro, vamos a utilizar la versión 2 de EasyAdmin, dando un tiempo de madurez a la nueva versión.

El primer paso, es instalar EasyAdmin, que lo podemos hacer mediante composer con la siguiente línea: symfony composer require «admin:^2» Aquí van a ver y justamente para no instalar la versión 3 que se instalaría por defecto hacemos la indicación explícita. Algunos de ustedes podría llegar a tener el siguiente error, dependiendo del momento en que estén viendo este vídeo las dependencias internas de los vendors que vamos instalando durante estos capítulos pueden variar, así que aprovechemos para explicar este tipo de errores que son muy normales en composer.

Aquí nos avisa que la versión de EasyAdmin requiere doctrine-bundle en su versión 1.8 o superior, pero si vamos hasta abajo, podemos ver algo más específico. Nos indica que el problema en sí está con la librería doctrine/common, que fue instalada directamente por Doctrine por debajo. Hoy en día se encuentra instalada la versión 3.0.2 y sin embargo necesitamos la rama 2.12. Con esta información vamos a ir a composer.json a decirle a composer que se mantenga en la rama 2.12

A continuación vamos a ejecutar un composer update para actualizar las librerías y corroboramos que la versión instalada sea la que necesitamos.

Ahora sí, volvamos a intentar la instalación de EasyAdmin en su versión 2. Con esta instalación, flex nos agregó nuevos archivos. Por un lado tenemos un archivo de rutas se EasyAdmin que es donde el bundle le dice Symfony que se crea una nueva ruta que será /admin en nuestra web en donde estarán nuestros CRUDs y por otro lado tenemos la configuración del bundle de EasyAdmin que lo vemos ahora.

Aquí es donde vamos a listar cuáles son los entities sobre los cuales queremos que existen interfaces de tipo CRUD. Vamos a descontar el ejemplo y agregar nuestros dos entities. Antes de verlo en funcionamiento, asegurémonos de siempre tener el método __toString() en todos nuestros entities.

Este método, es un método especial que todas las clases pueden tener, en donde básicamente se retorna la representación de una instancia de un objeto en forma
directa. En otras palabras si hiciéramos un echo de un objeto persona obtendríamos un texto que diría «object» directamente, pero al configurar el método __toString(), podríamos decirle que si se quiere obtener la representación de este objeto muestre por ejemplo la propiedad «nombre» o la concatenación del «nombre y el apellido».

• Para el caso de la clase de conferencia, indicamos que la representación será dada mediante la «ciudad» concatenada con el «año».
• Para los comentarios, directamente retornemos el «email» de la persona que realiza el comentario.

Ahora sí hagamos la prueba de cómo funcionó esto. Iniciemos nuestro servidor interno, abramos la página en el navegador y vayamos directo a la ruta /admin. Aquí vemos nuestra interfaz de EasyAdmin con ambas tablas aún sin datos, con todas las funcionalidades activas habiendo solo indicado los nombres de
ambas entidades.

Creando una conferencia podemos ver que tenemos la primera conferencia creada, pero también tenemos: ordenamiento por columnas, paginación, búsquedas globales, cantidad de comentarios asociados, controles dinámicos. Vayamos al CRUD de comentarios y agreguemos unos comentarios de ejemplo.

Por el momento vamos a cargar una fecha manualmente, luego la vamos a automatizar. El campo de fotografía lo dejamos todavía en blanco. Tenemos automáticamente la lista de conferencias creadas para seleccionarla, incluso con un buscador. Desde esta pantalla, podemos editar los registros, borrarlos o incluso saltarnos a las conferencias asociadas, en donde vemos la pantalla de sólo lectura con enlaces directos a los comentarios.

Las eliminaciones cuentan con mensajes de confirmación. Como pueden ver un CRUD no solamente es una lista, un formulario y una opción de borrado, y lo bueno es que no hace falta que desarrollemos todas estas funcionalidades. Todo esto gracias a la potencia de la arquitectura basada en entities que tenemos.

Personalizando EasyAdmin

EasyAdmin nos permite muchas personalizaciones a estas pantallas: como la definición del menú, que campos mostrar y cuáles no, configuraciones de títulos y mucho más. Para entender vamos a ver un ejemplo sencillo haciendo unas pequeñas modificaciones en la configuración de EasyAdmin. Primero vamos a corregir la ruta del controlador público que creamos en el capítulo 6 con nuestra primera página. Vamos a cambiar el identificador de nuestra ruta a «homepage» y apuntar a la raíz del sitio, eliminando el parámetro de ejemplo tanto del controlador como de la plantilla, dejando solamente la imagen, ya que vamos a utilizar esta ruta desde el menú del admin. Ahora, si vamos a modificar nuestra configuración, primeramente podemos cambiar el título del administrador; a continuación podemos agregar una sección de diseño, en donde vamos a definir mejor nuestro menú. En el primer ítem del menú apuntamos a la ruta de la raíz de nuestro sitio que acabamos de corregir, indicando un texto a mostrar y un icono.

Luego podemos hacer referencia a los CRUDs, directamente apuntando a nuestros entities; en los textos le ponemos los títulos en plural y definimos iconos. A continuación vamos a cambiar la configuración de los entities de formato corto a formato largo, que nos daría el mismo resultado hasta aquí. Para la pantalla del listado de comentarios, vamos a configurar las columnas que queremos mostrar, eliminando de la lista la columna ID, manteniendo el autor, el email configurando lo como un campo de tipo email para que nos agregué directamente un enlace, el campo de fecha de creación lo definimos como un DateTime para que lo formatee mejor. Luego definimos que el ordenamiento de la lista que estaba por defecto por ID ascendente lo haga por fecha de creación y por último definimos que aparte de la búsqueda global, queremos permitir el filtrado de la tabla por la columna de conferencia, con esto vemos los cambios en las columnas, un link sobre el correo electrónico, fechas formateadas como DateTime, el filtro por conferencias en donde si lo activamos, tenemos la posibilidad de realizar búsquedas con criterios, y el
ordenamiento predeterminado de esta lista por fecha de creación.

Por último vamos a configurar la pantalla de edición de los comentarios, dejando los campos de: selección de conferencia, fecha de creación indicando que el tipo debe ser DateTime para que nos agregue una validación y como solo lectura, el campo autor en su forma más simple, el campo de correo electrónico con la validación de que debe ser de tipo email y por último el campo texto para el comentario. Estas personalizaciones son sólo una pequeña introducción a las posibilidades que ofrece EasyAdmin, en la descripción del vídeo te dejo algunos enlaces extras para revisar más posibilidades con este bundle.

En el siguiente vídeo, vamos a dejar de lado nuestro backoffice de administración por el momento y vamos a ir creando las pantallas públicas, más adelante volveremos a nuestro administrador para aplicarle seguridad de acceso.

[sc name=»posts_symfony5_la_via_rapida»]