Depurar errores PHP con WP_DEBUG

Contents

Depurar errores PHP con WP_DEBUG

En el desarrollo de sitios WordPress, detectar y corregir errores PHP es esencial para garantizar la estabilidad, la seguridad y el rendimiento. WP_DEBUG es una herramienta integrada en WordPress que facilita la identificación de fallos en tus themes y plugins, así como en el propio core. A continuación encontrarás una guía amplia y detallada para aprovechar al máximo esta función.

¿Qué es WP_DEBUG

WP_DEBUG es una constante de configuración en WordPress que habilita la visualización de notificaciones, advertencias y errores generados por PHP. Activa un modo de desarrollo más riguroso, ayudándote a detectar prácticas obsoletas y potenciales problemas antes de que afecten a los usuarios finales.

1. Activación de WP_DEBUG

Para activar WP_DEBUG, edita el archivo wp-config.php y añade o modifica las siguientes líneas justo antes de / Thats all, stop editing! Happy blogging. /:

define(WP_DEBUG, true)
define(WP_DEBUG_LOG, true)
define(WP_DEBUG_DISPLAY, false)
@ini_set(display_errors, 0)

WP_DEBUG: activa o desactiva el modo debug.
WP_DEBUG_LOG: registra los errores en wp-content/debug.log.
WP_DEBUG_DISPLAY: controla si se muestran errores en pantalla.
@ini_set(display_errors, 0): asegura que no se muestren errores en producción.

2. Configuraciones complementarias

Además de las constantes anteriores, existen otras que debes considerar:

Constante	Descripción
`SCRIPT_DEBUG`	Fuerza el uso de archivos no minificados de JavaScript y CSS.
`SAVEQUERIES`	Almacena las consultas SQL en un array para análisis posterior.

3. Interpretación de los registros de error

Accede a wp-content/debug.log para revisar las entradas generadas. Cada línea sigue un formato:

[fecha hora] nivel: mensaje en archivo.php en la línea X

Los niveles principales son:

Notice: advertencias informativas (variables no inicializadas).
Warning: problemas menores (funciones deprecadas, argumentos incorrectos).
Fatal Error: errores críticos que detienen la ejecución de PHP.

4. Mejores prácticas al depurar

Ambiente de desarrollo separado: Nunca actives WP_DEBUG en un entorno público o de producción.
Registro continuo: Mantén activado WP_DEBUG_LOG para revisiones periódicas.
Uso de herramientas complementarias: Plugins como Query Monitor o sistemas externos de logging (Monolog, Sentry).
Corrección inmediata: Prioriza la solución de Fatal Errors y Warnings, luego aborda los Notices.
Actualización de versiones: Comprueba siempre la documentación oficial en developer.wordpress.org y en php.net.

5. Estrategias avanzadas

5.1 Manipulación de errores personalizados

Puedes reemplazar el manejador de errores estándar con set_error_handler() para filtrar o transformar mensajes:

function mi_manejador_errores(errno, errstr, errfile, errline) {

      nbspnbsp// Filtrar tipo de error

      nbspnbspif (error_reporting() ampamp (errno === E_NOTICE)) return true

      nbspnbsp// Registrar en sistema externo

      nbspnbsperror_log([errno] errstr en errfile:errline)

      }

      set_error_handler(mi_manejador_errores)

5.2 Monitorización de consultas SQL

Con define(SAVEQUERIES, true), WordPress guarda en wpdb-gtqueries los tiempos y detalles de cada llamada a la base de datos. Útil para detectar cuellos de botella:

Recorre wpdb-gtqueries al final de la carga de la página.
Ordena por tiempo de ejecución para priorizar optimización.

5.3 Integración con sistemas externos

Sistemas como Sentry (sentry.io) permiten:

Captura de errores en tiempo real.
Notificaciones por correo o Slack.
Contextualización avanzada (usuario, URL, stack trace).

6. Errores comunes y soluciones

6.1 Cabeceras ya enviadas

Error: Cannot modify header information – headers already sent by. Ocurre cuando hay espacios en blanco o texto antes de las etiquetas ltphp o después de gt. Revisa tu editor para eliminar BOM y espacios extra.

6.2 Función o clase no encontrada

Verifica que los archivos estén incluidos correctamente con require_once o include, y respeta la capitalización en sistemas sensibles como Linux.

6.3 Uso de funciones obsoletas

Los warnings te informan de funciones y hooks deprecados. Reemplázalos siguiendo la documentación oficial:

Funciones deprecadas en WordPress

7. Desactivación segura para producción

Antes de desplegar tu sitio en un servidor público:

Cambia define(WP_DEBUG, true) por define(WP_DEBUG, false).
Verifica que no existan registros accesibles públicamente en wp-content/debug.log.
Comprueba el correcto funcionamiento con user roles y flujos de interacción.

Conclusión

WP_DEBUG es una herramienta poderosa para cualquier desarrollador de WordPress. Su correcta configuración y uso sistemático te ayudará a reducir errores, mejorar la calidad del código y entregar proyectos más robustos. Complementa su uso con buenas prácticas de desarrollo, entornos diferenciados y herramientas de monitorización externa para obtener resultados óptimos.

Acepto donaciones de BAT's mediante el navegador Brave 🙂

Depurar errores PHP con WP_DEBUG