Upgrade Status
Revisa la preparación del entorno y los componentes del sitio para actualizaciones mayores de Drupal, escaneando el código en busca de uso de APIs obsoletas.
upgrade_status
Install
composer require 'drupal/upgrade_status:^4.3'
Overview
Upgrade Status es una herramienta integral para desarrolladores que escanea el código base de tu sitio Drupal para identificar problemas de compatibilidad con la próxima versión mayor de Drupal. Analiza módulos contribuidos e instalados, módulos personalizados, temas y perfiles para detectar código obsoleto que debe ser reemplazado antes de actualizar.
El módulo utiliza PHPStan con la extensión mglaman/phpstan-drupal para realizar análisis estático de código, junto con analizadores especializados para plantillas Twig, selectores CSS, definiciones de bibliotecas, archivos de enrutamiento, funciones de tema y metadatos de extensiones. Los resultados se categorizan por severidad y siguientes pasos accionables, ayudando a los desarrolladores a priorizar su trabajo de actualización.
Upgrade Status se integra con el módulo Update de Drupal para mostrar actualizaciones disponibles para proyectos contribuidos e indica si esas actualizaciones son compatibles con la próxima versión mayor de Drupal. Soporta exportaciones en formatos HTML y ASCII para compartir informes con las partes interesadas, y proporciona comandos Drush para integración con CI/CD.
Features
- Realiza análisis estático de código basado en PHPStan para detectar uso de APIs PHP obsoletas en módulos, temas y perfiles
- Analiza plantillas Twig en busca de sintaxis y filtros obsoletos (como la etiqueta spaceless)
- Escanea archivos CSS en busca de selectores obsoletos (ej. #drupal-off-canvas)
- Verifica definiciones de bibliotecas (*.libraries.yml) en busca de dependencias de bibliotecas obsoletas
- Valida archivos de enrutamiento en busca de requisitos de ruta obsoletos (ej. _access_node_revision, _access_media_revision)
- Detecta uso y sobreescrituras de funciones de tema obsoletas (eliminadas en Drupal 9/10)
- Valida metadatos de extensiones (*.info.yml) en busca de core_version_requirement faltante o incompatible
- Verifica configuraciones de Views en busca de ajustes obsoletos (ej. default_argument_skip_url)
- Proporciona verificaciones de compatibilidad del entorno para Drupal 10, 11 y 12 incluyendo versión de PHP, tipo/versión de base de datos, soporte JSON y versión de Drush
- Categoriza proyectos por siguientes pasos recomendados: Eliminar desinstalados, Actualización disponible, Escaneo necesario, Colaborar con mantenedores, Corregir con rector, Corregir manualmente o Compatible
- Distingue entre proyectos personalizados y contribuidos basándose en la estructura de directorios o metadatos de despliegue de composer/git
- Se integra con el módulo Update para mostrar actualizaciones de proyectos disponibles y compatibilidad con la próxima versión mayor
- Muestra un indicador visual de progreso mostrando el porcentaje de preparación del sitio para la actualización
- Exporta resultados de escaneo como archivos HTML o de texto ASCII descargables
- Proporciona vista en diálogo modal de resultados detallados de escaneo por proyecto
- Soporta procesamiento por lotes con sandboxing HTTP para manejar errores fatales de PHP de forma elegante
- Incluye comandos Drush para análisis desde línea de comandos e integración CI/CD con múltiples formatos de salida (plain, checkstyle XML, Code Climate JSON)
- Categoriza obsolescencias como 'corregir ahora', 'corregir después', 'puede corregirse con rector' o 'ignorar' basándose en la versión y línea temporal de eliminación
- Detecta obsolescencias cubiertas por drupal-rector para correcciones automatizadas
Use Cases
Preparación para actualización de Drupal 10 a 11
Antes de actualizar de Drupal 10 a 11, navega a Administración > Informes > Estado de actualización. Primero revisa las verificaciones de entorno para asegurar que tu hosting cumple los requisitos de D11 (PHP 8.3+, MySQL 8.0+/MariaDB 10.6+/PostgreSQL 16+, Drush 13+). Luego selecciona todos los proyectos y haz clic en 'Escanear seleccionados' para analizar tu código base. Revisa los resultados categorizados: actualiza primero cualquier proyecto con actualizaciones disponibles, luego aborda las obsolescencias en código personalizado. Los proyectos marcados como 'Corregir con rector' pueden usar drupal-rector para correcciones automatizadas. Exporta los resultados como HTML para compartir con tu equipo o partes interesadas.
Verificación de obsolescencias en Integración Continua
Añade escaneo de Upgrade Status a tu pipeline CI/CD usando comandos Drush. Ejecuta 'drush upgrade_status:analyze --all --ignore-uninstalled --format=codeclimate > gl-code-quality-report.json' para generar un informe compatible con Code Climate para GitLab CI. Para Jenkins u otros sistemas CI, usa '--format=checkstyle' para generar salida XML compatible con herramientas de análisis estático. Configura el comando para fallar (código de salida > 0) cuando se encuentren obsolescencias para bloquear merges que introduzcan uso de APIs obsoletas.
Auditoría de compatibilidad de módulos contribuidos
Al evaluar módulos contribuidos para un nuevo proyecto, usa Upgrade Status para verificar su compatibilidad con futuras versiones de Drupal. Instala los módulos candidatos, ejecuta un escaneo y revisa cuáles módulos ya son compatibles, cuáles necesitan actualizaciones y cuáles requieren colaboración con los mantenedores. Esto ayuda a priorizar la selección de módulos e identificar posibles bloqueadores de actualización temprano en la planificación del proyecto.
Identificación de obsolescencias corregibles con Rector
Para bases de código grandes con muchas obsolescencias, usa Upgrade Status para identificar qué problemas pueden corregirse automáticamente. Los proyectos categorizados como 'Corregir con rector' contienen obsolescencias cubiertas por reglas de drupal-rector. Ejecuta 'drush upgrade_status:analyze mycustommodule' para escanear tu módulo, luego instala drupal/rector y ejecuta 'vendor/bin/rector process web/modules/custom/mycustommodule' para aplicar correcciones automáticamente. Vuelve a escanear para verificar que las correcciones se aplicaron correctamente.
Generación de informes para partes interesadas
Genera informes profesionales para gerentes de proyecto o clientes seleccionando todos los proyectos y haciendo clic en 'Exportar seleccionados como HTML'. El archivo HTML exportado contiene un resumen completo de todas las obsolescencias organizadas por tipo de proyecto (personalizado vs contribuido), con clara categorización de urgencia de corrección. Para equipos técnicos que prefieren salida de terminal, usa 'Exportar seleccionados como texto' para un informe ASCII que puede incluirse en correos electrónicos o documentación.
Tips
- Comienza la preparación de actualización temprano ejecutando Upgrade Status en tu versión actual de Drupal, incluso si aún no estás listo para actualizar
- Enfócate primero en corregir las obsolescencias de categoría 'ahora' - estas se eliminan en la siguiente versión mayor inmediata
- Actualiza los módulos contribuidos antes de escanear - las versiones más nuevas a menudo contienen correcciones de obsolescencias
- Usa el comando Drush con --skip-existing para reutilizar resultados en caché cuando iteres sobre correcciones
- La categoría 'Corregir con rector' indica que drupal-rector puede automatizar correcciones - considera usarlo para bases de código grandes
- Revisa la categoría 'Colaborar con mantenedores' para issues de drupal.org y parches a los que puedes contribuir
- Exporta informes antes y después de corregir obsolescencias para seguir el progreso y demostrar el trabajo completado
- Para verificaciones de entorno precisas, asegúrate de estar ejecutando la misma versión de PHP y base de datos que tu entorno de producción
Technical Details
Admin Pages 2
/admin/reports/upgrade-status
La página principal del informe de estado de actualización que muestra información completa sobre la preparación de tu sitio para la próxima versión mayor de Drupal. La página muestra dinámicamente 'Estado de actualización de Drupal 10', 'Estado de actualización de Drupal 11' o 'Estado de actualización de Drupal 12' dependiendo de tu versión actual de Drupal.
/admin/reports/upgrade-status/project/{project_machine_name}
Muestra resultados detallados de escaneo para un único proyecto en un diálogo modal. Muestra todas las obsolescencias detectadas organizadas por categoría con rutas de archivo, números de línea y correcciones sugeridas.
Permissions 1
Hooks 2
hook_upgrade_status_operations_alter
Permite a los módulos alterar las operaciones por lotes ejecutadas al escanear proyectos. Útil para añadir procesamiento adicional como ejecutar rector.
hook_upgrade_status_result_alter
Permite a los módulos alterar la visualización del resultado renderizado para un proyecto específico y grupo de resultados. Útil para añadir información personalizada o modificar descripciones.
Drush Commands 2
drush upgrade_status:analyze
Analiza proyectos en busca de obsolescencias y muestra los resultados. Soporta múltiples formatos de salida para diferentes casos de uso incluyendo integración CI/CD.
drush upgrade_status:checkstyle
Obsoleto. Analiza proyectos y muestra resultados en formato XML checkstyle. Usa 'drush upgrade_status:analyze --format=checkstyle' en su lugar.
Troubleshooting 6
Asegúrate de haber instalado el módulo usando Composer: 'composer require drupal/upgrade_status'. El módulo requiere PHPStan y phpstan-drupal que solo se instalan a través de Composer. Si usas un bin-dir o vendor-dir personalizado en composer.json, el módulo detectará automáticamente estas ubicaciones.
Aumenta el límite de memoria de PHPStan usando Drush con la opción --phpstan-memory-limit: 'drush upgrade_status:analyze --phpstan-memory-limit=2G mymodule'. Para escaneo basado en web, considera aumentar memory_limit de PHP en php.ini.
El módulo usa solicitudes HTTP para aislar errores fatales de PHP durante el escaneo. Esto puede fallar en algunas configuraciones de contenedores o proxy inverso. Verifica que el sitio pueda hacer solicitudes HTTP a sí mismo. Si usas el servidor PHP incorporado (php -S), el sandboxing HTTP se desactiva automáticamente ya que no soporta solicitudes concurrentes.
Ejecuta primero la verificación de actualizaciones de Drupal: navega a Administración > Informes > Actualizaciones disponibles > Verificar manualmente, o ejecuta 'drush pm:security' para actualizar la información de actualizaciones. Luego regresa a Upgrade Status para ver los datos de compatibilidad actualizados.
Instala Composer Deploy (drupal/composer_deploy) para sitios gestionados con Composer o Git Deploy (drupal/git_deploy) para sitios desplegados con Git. Estos módulos proporcionan identificación precisa de proyectos basada en metadatos de despliegue en lugar de heurísticas de estructura de directorios.
El módulo categoriza automáticamente como 'ignorar' las obsolescencias eliminadas después de la próxima versión mayor. Por ejemplo, las obsolescencias eliminadas en Drupal 13 se ignoran al actualizar a Drupal 11. Revisa el mensaje completo de obsolescencia para entender la línea temporal de eliminación y planifica en consecuencia para futuras actualizaciones.
Security Notes 4
- El módulo requiere el permiso 'administer software updates' que típicamente está restringido a administradores de confianza
- Los resultados de escaneo se almacenan en el almacenamiento clave-valor de Drupal y persisten entre sesiones
- El módulo hace solicitudes HTTP a sí mismo durante el procesamiento por lotes para aislar errores fatales de PHP - asegúrate de que tu firewall permita solicitudes localhost
- Los informes HTML/ASCII exportados pueden contener rutas de archivo que revelan la estructura de directorios del servidor - trata las exportaciones como documentación interna