Depura tu plugin como un profesional: WP_DEBUG, debug.log y cómo leer un error de PHP

Escribiste tu plugin, guardaste, recargaste y apareció: «Ha habido un error crítico en esta web». WordPress esconde los detalles del error a propósito, para no mostrar información de tu servidor a cualquier visitante. Pero tú sí necesitas verlos. Hoy aprenderás a encenderlos de forma segura y, sobre todo, a leerlos.

Paso 1. Activa la depuración en wp-config.php

Abre wp-config.php (en la raíz de tu WordPress) y busca la línea define( 'WP_DEBUG', false );. Reemplázala por:

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

• WP_DEBUG: enciende el modo de depuración. WordPress informa también avisos menores, como funciones obsoletas.
• WP_DEBUG_LOG: guarda todo en el archivo wp-content/debug.log.
• WP_DEBUG_DISPLAY en false y display_errors en 0: no muestra los errores en pantalla. Así puedes depurar sin que tus visitantes vean nada raro.

Mejor aún: el log fuera de la web

Por defecto, debug.log queda dentro de wp-content, y alguien podría abrirlo desde el navegador. Puedes indicarle a WordPress otra ruta, fuera de public_html:

define( 'WP_DEBUG_LOG', '/home/TU_USUARIO/logs/wp-debug.log' );

Cambia TU_USUARIO por tu usuario de cPanel y crea antes la carpeta logs en tu carpeta de inicio (al lado de public_html, no dentro).

Paso 2. Provoca el error y abre el log

Recarga la página que falla. Después, abre el archivo de log desde el Administrador de archivos (clic derecho → Ver) o, si tienes Terminal en cPanel, míralo en vivo:

tail -f ~/public_html/wp-content/debug.log

tail -f muestra las últimas líneas y se queda esperando las nuevas. Recarga tu sitio en el navegador y verás aparecer los errores al instante. Para salir, pulsa Ctrl + C.

Paso 3. Aprende a leer un error

Un error típico se ve así:

[27-Oct-2026 14:32:10 UTC] PHP Parse error:  syntax error, unexpected token "}", expecting ";" in /home/usuario/public_html/wp-content/plugins/caja-foro/caja-foro.php on line 42

Tiene cuatro partes. Léelas siempre en este orden:

1. El tipo: PHP Parse error.
2. El archivo: .../plugins/caja-foro/caja-foro.php. Te dice qué plugin o tema falló.
3. La línea: line 42.
4. El mensaje: unexpected token "}", expecting ";": PHP esperaba un punto y coma y encontró una llave.

En los errores de sintaxis, el problema real suele estar en la línea anterior a la que indica PHP. En este ejemplo, revisa la línea 41: casi seguro le falta el ; al final.

Los tipos de error, de más grave a menos

• Parse error: error de escritura (sintaxis). PHP ni siquiera pudo leer el archivo. Falta un ;, una comilla, un paréntesis o una llave.
• Fatal error: el código se pudo leer, pero falló al ejecutarse. Los más comunes:
  • Call to undefined function caja_foro_html(): llamaste a una función que no existe. ¿Error de tipeo? ¿Está en otro archivo que no cargaste? ¿Es de un plugin que no está activo?
  • Cannot redeclare caja_foro_html(): la función está definida dos veces. Pasa cuando pegas un código dos veces o cuando dos plugins usan el mismo nombre.
  • Allowed memory size exhausted: se acabó la memoria. A veces por un bucle infinito.
• Warning: algo salió mal, pero el código siguió. Por ejemplo, Undefined array key "titulo": intentaste leer una clave que no existe. Hay que corregirlo, aunque no rompa el sitio.
• Deprecated: estás usando algo que dejará de funcionar en una versión futura de PHP o WordPress. Anótalo y actualízalo con calma.
• Notice: avisos menores. Muchos vienen de otros plugins: concéntrate en los que mencionan tus archivos.

Paso 4. Escribe tus propios mensajes en el log

¿Tu código no da error pero no hace lo que esperas? Deja «migas de pan» con error_log() para ver qué está pasando por dentro:

function caja_foro_agregar( $contenido ) {
	error_log( 'caja_foro_agregar: entrada ' . get_the_ID() );

	if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
		error_log( 'caja_foro_agregar: no es una entrada individual, salgo' );
		return $contenido;
	}

	$o = caja_foro_opciones();
	error_log( 'caja_foro_agregar: opciones = ' . print_r( $o, true ) );

	return $contenido . caja_foro_html();
}

print_r( $variable, true ) convierte un arreglo en texto legible para el log. Cuando encuentres el problema, borra estas líneas: no dejes mensajes de diagnóstico en un plugin terminado.

Paso 5. Herramientas que ayudan

• Query Monitor: muestra en la barra superior los errores y avisos de PHP de la página que estás viendo, con el archivo y la línea, sin abrir el log.
• Un editor de código como Visual Studio Code marca en rojo los errores de sintaxis mientras escribes, antes de subir el archivo.
• Revisar la sintaxis por terminal: si tienes acceso, php -l caja-foro.php te dice si hay errores de sintaxis sin ejecutar el archivo.

Cuando termines

En un sitio en producción, vuelve a dejar WP_DEBUG en false y borra el archivo debug.log. Un log olvidado puede crecer hasta llenar tu espacio en disco y, si está dentro de la web, revelar rutas y datos de tu servidor.

¿Tienes un error que no logras descifrar? Pega la línea completa del log en el foro (puedes reemplazar tu usuario por «usuario») y junto con el fragmento de código, lo resolvemos.