Un tema personalizado había pasado las revisiones locales, pero WordPress mostraba un error al instalarlo en el hosting del cliente. El diseño, los plugins y los datos no eran el problema. El servidor ejecutaba PHP 7.2 y parte del código utilizaba sintaxis introducida en PHP 8.
Por qué ocurre aunque WordPress esté actualizado
WordPress, el tema y PHP tienen ciclos de actualización diferentes. Una instalación puede tener una versión moderna de WordPress y seguir utilizando un intérprete antiguo por limitaciones del hosting o compatibilidad con otras aplicaciones.
En desarrollo, el tema se había probado con una versión reciente. Al subirlo, PHP ni siquiera podía interpretar algunos archivos, por lo que el fallo aparecía antes de cargar WordPress.
La solución no fue esconder el error
Revisé todos los archivos PHP del tema para localizar declaraciones de tipos, funciones y construcciones no disponibles en 7.2. Después sustituí únicamente las incompatibilidades, manteniendo el comportamiento y las validaciones.
También actualicé la cabecera del tema para declarar una versión mínima realista. No tiene sentido afirmar compatibilidad con un entorno que nunca se ha probado.
Cómo validé el paquete final
- Análisis de sintaxis de todos los archivos PHP.
- Comprobación del ZIP y de la estructura esperada por WordPress.
- Revisión de activación e importación de contenido.
- Control de las funciones utilizadas frente a la versión mínima.
- Nueva versión del tema para distinguirla del paquete incompatible.
Actualizar PHP o adaptar el código
Siempre que sea posible recomiendo actualizar PHP, especialmente por seguridad y rendimiento. Pero una actualización debe comprobar plugins, tema y aplicaciones conectadas. Cuando no puede hacerse de inmediato, adaptar el código de manera consciente es preferible a aplicar parches al azar.
Mi recomendación para evitarlo
Antes de desarrollar, documento la versión de PHP de producción y la reproduzco en el entorno de pruebas. El proceso de entrega debe validar esa versión exacta. Así la compatibilidad deja de ser una suposición.