Páginas personalizadas de error
Muestra una página amigable cuando ocurre un error fatal o excepción, con seguimiento UUID para referencia de soporte.
error_page
Instalar
composer require 'drupal/error_page:^2.0'
Overview
El módulo Error custom pages reemplaza las páginas de error simples de Drupal core con páginas personalizables y amigables cuando ocurren excepciones o errores fatales. Cada error se etiqueta con un Identificador Único Universal (UUID), permitiendo a los usuarios referenciar errores específicos al contactar soporte. El UUID también se registra en el watchdog de Drupal y en el log de errores de PHP para facilitar la depuración.
A diferencia de los módulos típicos de Drupal, este módulo utiliza settings.php para la configuración en lugar del sistema de gestión de configuración de Drupal. Esta decisión de diseño es intencional: cuando ocurre una excepción no capturada, los servicios de Drupal (incluyendo la fábrica de configuración) pueden no estar disponibles. Al depender de settings.php, el módulo puede funcionar incluso cuando el contenedor de Drupal está roto o no disponible.
El módulo proporciona plantillas HTML personalizables para páginas de error y mensajes. Dado que el motor de renderizado Twig requiere servicios de Drupal, el módulo utiliza archivos HTML estáticos simples con reemplazo de tokens de variables. Estas plantillas pueden copiarse y personalizarse mientras se mantienen protegidas del acceso web público.
Features
- Muestra páginas de error amigables en lugar de la salida de error simple de Drupal core cuando ocurren excepciones o errores fatales
- Genera un UUID único para cada error/excepción, mostrado a los usuarios y registrado para referencia de soporte
- Proporciona plantillas HTML personalizables para páginas de error (error_page.html) y mensajes de error (error_message.html)
- Registra errores tanto en el log de base de datos de Drupal (watchdog) como en el log de errores de PHP con referencia UUID
- Utiliza configuración en settings.php en lugar del sistema de configuración de Drupal para asegurar funcionalidad incluso cuando los servicios de Drupal no están disponibles
- Soporta destinos personalizados de log de errores mediante la configuración de la función error_log() de PHP
- Protege las plantillas de marcado del acceso público con reglas de seguridad .htaccess
- Compatible con Drupal 10 y Drupal 11
Use Cases
Manejo de errores en sitios de producción
Reemplaza los mensajes de error técnicos de Drupal con páginas amigables en sitios de producción. Los usuarios ven un mensaje cortés con un UUID que pueden referenciar al contactar soporte, mientras los desarrolladores pueden buscar el UUID en los logs para encontrar los detalles exactos del error.
Correlación de tickets de soporte
Cuando los usuarios reportan errores a tu mesa de ayuda, pueden proporcionar el UUID mostrado en la página de error. El personal de soporte puede entonces buscar ese UUID en el log de base de datos de Drupal (dblog) o los logs de errores de PHP para identificar rápidamente el error exacto, stack trace y contexto.
Páginas de error con marca personalizada
Personaliza las plantillas de página de error para que coincidan con la marca de tu sitio. Copia error_page.html y error_message.html a un directorio seguro, agrega el logo de tu sitio, CSS y mensajes, luego configura la opción template_dir para usar tus plantillas personalizadas.
Destinos personalizados de log de errores
Enruta los logs de errores a un archivo específico para monitoreo o integración con sistemas de logging externos. Configura el método de log 3 con una ruta de destino para recopilar todos los errores en un archivo de log dedicado.
Tips
- Coloca las plantillas personalizadas fuera del directorio web raíz o protégelas con .htaccess para prevenir el acceso público directo
- Usa logging de errores detallado durante el desarrollo ($config['system.logging']['error_level'] = 'verbose') para ver backtraces completos en las páginas de error
- La variable {{ error_report }} en las plantillas está vacía cuando la visualización de errores está deshabilitada en la configuración de logging de Drupal
- Habilita el submódulo error_page_test (requiere $settings['extension_discovery_scan_tests'] = TRUE) para probar diferentes tipos de error en /error_page_test/exception, /error_page_test/fatal_error, /error_page_test/user_error y /error_page_test/php_notice
- El módulo registra errores críticos tanto en el log de base de datos de Drupal como en el log de errores de PHP para redundancia
Technical Details
Troubleshooting 4
Asegúrate de haber agregado las llamadas a set_error_handler() y set_exception_handler() en tu archivo settings.php. El módulo requiere el registro explícito de sus manejadores de errores en settings.php.
Si no usas Composer para autoloading, agrega esta línea antes de las llamadas a set_error_handler en settings.php: require_once 'modules/contrib/error_page/src/ErrorPageErrorHandler.php'; Los usuarios de Composer obtienen esto automáticamente a través de la entrada autoload classmap.
Verifica que $settings['error_page']['uuid'] no esté explícitamente establecido en FALSE en tu settings.php. El valor predeterminado es TRUE, pero puede haber sido deshabilitado.
Verifica que $settings['error_page']['template_dir'] apunte al directorio correcto y que los archivos de plantilla se llamen exactamente error_page.html y error_message.html. La ruta del directorio debe ser absoluta o relativa a DRUPAL_ROOT.
Security Notes 4
- Nunca habilites $settings['extension_discovery_scan_tests'] en sitios de producción, ya que permite el descubrimiento de módulos de prueba
- Los directorios de plantillas personalizadas deben estar protegidos del acceso web público usando .htaccess o colocándolos fuera del directorio web raíz
- El módulo automáticamente elimina DRUPAL_ROOT de las rutas de archivo en los mensajes de error para prevenir la divulgación de rutas completas (mejor práctica de seguridad OWASP)
- El directorio markup/ predeterminado incluye un archivo .htaccess que deniega todo acceso público a los archivos de plantilla