Introducción
Depurar WordPress correctamente es esencial para desarrollar plugins y temas robustos. WordPress ofrece constantes integradas como WP_DEBUG y WP_DEBUG_LOG que, combinadas con la configuración de PHP, permiten capturar errores, avisos y mensajes personalizados en un archivo de registro seguro. Este artículo detalla cómo usar esas herramientas, ejemplos prácticos, buenas prácticas, y soluciones a errores frecuentes.
Contents
Conceptos clave
- WP_DEBUG: activa el modo de depuración de WordPress. Cuando es true, WordPress mostrará advertencias y errores generados por PHP y por el propio núcleo.
- WP_DEBUG_LOG: si está activado, registra los errores en un archivo (por defecto wp-content/debug.log).
- WP_DEBUG_DISPLAY: controla si los errores se muestran en pantalla. En desarrollo suele estar a true, en producción debe ser false.
- SCRIPT_DEBUG: fuerza el uso de versiones no comprimidas de scripts y estilos del núcleo, útil al depurar problemas de JS/CSS.
- SAVEQUERIES: guarda en memoria las consultas SQL realizadas, permite analizar rendimiento (consume memoria).
Cómo habilitar la depuración en wp-config.php
La forma recomendada es editar el archivo raíz wp-config.php antes de la línea que dice / Thats all, stop editing! Happy publishing. /. Un bloque de configuración de ejemplo para un entorno de desarrollo:
Explicación rápida
- Con WP_DEBUG = true WordPress emitirá avisos, que ayudan a detectar funciones obsoletas y errores.
- Con WP_DEBUG_LOG = true los mensajes van a wp-content/debug.log. Si el archivo no existe, WordPress intentará crearlo.
- Con WP_DEBUG_DISPLAY = false se evita exponer errores a los visitantes los mensajes sólo estarán en el log.
Ubicación y permisos del archivo de log
Por defecto WordPress escribe en wp-content/debug.log. Si el archivo no se crea, verifica:
- Permisos del directorio wp-content (por ejemplo 755 para directorios, 644 para archivos).
- Propiedad del proceso web (el usuario que ejecuta PHP) debe poder escribir en wp-content o en el archivo debug.log.
- Si tu hosting bloquea la creación de archivos, usa logs del servidor web (error_log) o una ruta personalizada.
Forzar ruta personalizada al log
Si necesitas una ruta distinta o más control, puedes establecer la constante WP_DEBUG_LOG con una ruta absoluta (WordPress 5.8 ). Ejemplo:
Ejemplos prácticos de mensajes de depuración
Además de los errores automáticos, puedes registrar mensajes desde tu código.
123, nombre => Prueba ) if ( defined( WP_DEBUG ) WP_DEBUG ) { error_log( [MiPlugin] Datos: . print_r( datos, true ) ) } // Registrar excepciones try { // código que puede lanzar excepción } catch ( Exception e ) { if ( defined( WP_DEBUG ) WP_DEBUG ) { error_log( [MiPlugin] Excepción: . e->getMessage() ) } }Usar trigger_error para distintos niveles
PHP soporta distintos niveles de error. Puedes usar trigger_error para generar avisos/notices o warnings que WordPress registrará.
Configuración adicional de PHP
Para asegurarte de que PHP reporte todo lo necesario, modifica la configuración mediante error_reporting e ini_set:
Depuración de consultas SQL
Si activas SAVEQUERIES, WordPress guarda un array global wpdb->queries con cada consulta, su tiempo y pila de llamadas. Útil para detectar consultas lentas.
queries, function ( a, b ) { return b[1] <=> a[1] } ) for ( i = 0 i < min( 10, count( wpdb->queries ) ) i ) { error_log( [SQL] . print_r( wpdb->queries[ i ], true ) ) } }Buenas prácticas y seguridad
- No dejar WP_DEBUG activo en producción. Exponer avisos puede revelar rutas, nombres de funciones y otra información sensible.
- Usar WP_DEBUG_DISPLAY = false en entornos accesibles públicamente y revisar logs en lugar de mostrar errores en pantalla.
- Rotación de logs: controlar el tamaño de los archivos de log (logrotate en servidores Linux o escribir logs diarios con nombres únicos).
- Eliminar datos sensibles de logs: evita registrar contraseñas, tokens o datos de tarjetas.
- Control de permisos: asegurar que solo el usuario administrador o el proceso web tengan acceso al archivo de logs.
Integración con herramientas avanzadas
- Xdebug: para inspección paso a paso, breakpoints y perfiles. Recomendado en desarrollo local.
- Monolog: si necesitas capacidades avanzadas (niveles de logs, handlers remotos, rotación), puedes integrar Monolog en tu plugin o tema y enviar logs a servicios externos.
- WP-CLI: puedes revisar logs desde línea de comandos y automatizar tareas de diagnóstico.
Ejemplo: uso simple de Monolog
pushHandler( new StreamHandler( WP_CONTENT_DIR . /logs/mi_plugin.log, Logger::DEBUG ) ) log->info( Inicio proceso, array( step => 1 ) )
Problemas frecuentes y soluciones
- El debug.log no se crea: comprobar permisos del directorio, propietario del proceso PHP y si WP_DEBUG_LOG está configurado correctamente. También verificar que no hay open_basedir que impida escribir en la ruta.
- No aparecen errores en el log: asegurarse de que error_reporting y log_errors están habilitados y de que WP_DEBUG está activo. Algunos errores críticos pueden registrarse en el log del servidor en vez de en debug.log.
- Errores duplicados o imprecisos: limpiar logs antes de pruebas y usar mensajes identificables (prefijos) por plugin/tema para localizar el origen.
- Fugas de memoria al imprimir grandes objetos: usar print_r con segundo parámetro true y limitar la profundidad, o serializar grandes estructuras con precaución.
Checklist rápido para depurar correctamente
- Editar wp-config.php y activar WP_DEBUG y WP_DEBUG_LOG.
- Setear WP_DEBUG_DISPLAY = false en entornos no locales.
- Comprobar permisos de wp-content y existencia de debug.log.
- Usar error_log / trigger_error en puntos estratégicos del código.
- Revisar y rotar logs periódicamente.
- Desactivar debug y limpiar logs antes de pasar a producción.
Recursos
Notas finales
El uso correcto de WP_DEBUG y WP_DEBUG_LOG acelera la detección de problemas y mejora la calidad del código. Combínalos con herramientas como Xdebug para depuración avanzada y asegúrate siempre de no dejar información sensible accesible en entornos públicos.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |