Debug WordPress per Agenzie: WP_DEBUG, Query Monitor e Xdebug in Produzione [2026]

TL;DR — Cosa Troverai in Questa Guida

Il debug WordPress è la competenza che separa le agenzie professionali da quelle che improvvisano. In questa guida condividiamo il workflow che usiamo in AgencyPilot per diagnosticare problemi su 50+ siti WordPress senza mai mostrare errori ai visitatori. Copriamo configurazione WP_DEBUG, wp_debug.log, Query Monitor, Xdebug, logging strutturato e troubleshooting dei problemi più comuni: white screen of death, errori REST API, conflitti tra plugin.

Nella nostra esperienza di gestione di 50+ siti WordPress per agenzie, un sistema di debug strutturato riduce i tempi di risoluzione del 70% e previene la maggior parte dei ticket di supporto prima che i clienti li aprano.

Cos’è il Debug WordPress e Perché le Agenzie Ne Hanno Bisogno

Il debug WordPress è l’insieme di strumenti, configurazioni e tecniche per identificare, diagnosticare e risolvere problemi nel codice PHP, nelle query database, negli hook, nelle API e nel frontend di un sito WordPress. Per un’agenzia che gestisce decine di siti, non è opzionale: è infrastruttura critica.

WordPress include un sistema di debugging nativo basato su costanti PHP definite in wp-config.php. Quando attivato, registra errori, warning, notice, funzioni deprecate e query database in file di log ispezionabili. Il problema è che la maggior parte delle agenzie lo configura una volta e dimentica di mantenerlo, oppure lo attiva in produzione mostrando errori ai visitatori.

Tabella: Strumenti di Debug WordPress a Confronto

Configurazione di WP_DEBUG in wp-config.php

WP_DEBUG è la costante PHP che attiva la modalità debug in WordPress. Per impostazione predefinita è disattivata, e per buone ragioni: in produzione, mostrare errori PHP ai visitatori è un rischio di sicurezza e un’esperienza utente disastrosa.

La configurazione corretta dipende dall’ambiente. WordPress 6.5+ supporta la costante WP_ENVIRONMENT_TYPE per distinguere automaticamente gli ambienti.

Configurazione per Sviluppo e Staging

Negli ambienti di sviluppo e staging, vuoi vedere tutti gli errori a schermo per fixarli immediatamente:

// wp-config.php — Ambiente di sviluppo
define( 'WP_ENVIRONMENT_TYPE', 'local' );
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );
define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );
@ini_set( 'display_errors', 1 );
error_reporting( E_ALL );

Questa configurazione mostra errori a schermo, li registra nel file wp-content/debug.log, carica le versioni non minificate di JS e CSS (utile per debug frontend), e salva tutte le query database per analisi performance.

Configurazione Production-Safe per Agenzie

In produzione, la regola è: logga tutto, non mostrare nulla. Questa è la configurazione che usiamo su tutti i siti clienti in AgencyPilot:

// wp-config.php — Produzione (safe)
define( 'WP_ENVIRONMENT_TYPE', 'production' );
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', false );
define( 'SAVEQUERIES', false );
@ini_set( 'display_errors', 0 );

// Path personalizzato per il file di log (fuori da wp-content)
define( 'WP_DEBUG_LOG', '/var/log/wordpress/sitename-debug.log' );

Attenzione: WP_DEBUG attivato in produzione non rallenta il sito se WP_DEBUG_DISPLAY è false e SAVEQUERIES è false. Il overhead è minimo e il valore di avere log disponibili quando qualcosa va storto è enorme. Per una gestione centralizzata dei log su più siti, consulta la nostra guida su come automatizzare la gestione WordPress con le API.

Configurazione Condizionale per Ambienti Multipli

Per le agenzie che usano workflow di automazione WordPress, una configurazione condizionale basata su WP_ENVIRONMENT_TYPE è più elegante:

// wp-config.php — Configurazione condizionale
$env_type = getenv( 'WP_ENVIRONMENT_TYPE' ) ?: 'production';
define( 'WP_ENVIRONMENT_TYPE', $env_type );

$is_dev = in_array( $env_type, [ 'local', 'development', 'staging' ], true );

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', $is_dev );
define( 'SCRIPT_DEBUG', $is_dev );
define( 'SAVEQUERIES', $is_dev );
@ini_set( 'display_errors', $is_dev ? 1 : 0 );

Query Monitor: Il Tool Indispensabile per WordPress

Query Monitor è il plugin di debug più importante per WordPress. Sviluppato da John Blackbourn, con oltre 600.000 installazioni attive, è gratuito e si integra nella barra di amministrazione di WordPress fornendo un accesso immediato a dati critici.

Cosa Mostra Query Monitor

• Query Database: ogni query eseguita durante il page load, con tempo di esecuzione, componente che l’ha generata (core, tema, plugin specifico), e stack trace completo
• Hook e Action: tutti gli hook do_action e apply_filters eseguiti, con funzioni registrate e ordine di esecuzione
• PHP Errors: errori, warning, notice e deprecation notice con file e riga esatta
• HTTP API: tutte le richieste HTTP effettuate dal sito (chiamate REST API, webhook, richieste a servizi esterni)
• Performance: tempo totale di generazione pagina, consumo memoria, picchi
• Environment: versione PHP, versione MySQL, variabili $_GET/$_POST, costanti definite

Come Usare Query Monitor per Diagnosticare Problemi

Il caso d’uso più comune per le agenzie è identificare quale plugin sta rallentando un sito. Query Monitor rende questo immediato:

1. Apri la pagina lenta nel browser
2. Clicca su “Query Monitor” nella barra di amministrazione
3. Vai al pannello “Queries by Component”
4. Ordina per tempo di esecuzione discendente
5. Identifica il componente (plugin/tema) con query lente o ridondanti

Nel nostro lavoro di ottimizzazione Core Web Vitals su siti clienti, Query Monitor ci ha permesso di identificare plugin che eseguivano oltre 200 query database per singolo page load. Disattivando o sostituendo quel plugin, i tempi di caricamento sono passati da 3.2s a 0.8s.

Query Monitor in Produzione: Sì o No?

Query Monitor può essere attivato in produzione, ma con cautela. Il plugin aggiunge overhead al page load (circa 5-15ms) e espone informazioni sensibili nella barra di amministrazione. La best practice per le agenzie è:

• Sviluppo/Staging: sempre attivo
• Produzione: attivo solo per utenti amministratore, disattivato per gli altri. Usare define( 'QM_DISABLE_ERROR_HANDLER', false ); per evitare conflitti

Xdebug: Debug Profondo con Breakpoint per Sviluppo Locale

Xdebug è un’estensione PHP che fornisce debugging step-by-step, profiling e stack traces formattati. A differenza di WP_DEBUG e Query Monitor, Xdebug è uno strumento per lo sviluppo locale e mai per produzione: l’impatto sulle performance è troppo alto.

Installazione di Xdebug con Docker

Per Docker (la configurazione più comune per le agenzie moderne), aggiungi al tuo docker-compose.yml:

# docker-compose.yml
services:
  wordpress:
    build: .
    environment:
      XDEBUG_MODE: debug,develop
      XDEBUG_CONFIG: client_host=host.docker.internal
    volumes:
      - ./php-xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini

; php-xdebug.ini
zend_extension=xdebug
xdebug.mode=debug,develop,profile
xdebug.start_with_request=trigger
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/var/log/xdebug.log

Per installazione diretta su server (utile per ambienti di automazione):

# Ubuntu/Debian
sudo apt install php-xdebug

# Configurazione base in /etc/php/8.x/mods-available/xdebug.ini
zend_extension=xdebug
xdebug.mode=debug,develop
xdebug.start_with_request=trigger

Configurazione VS Code per Xdebug

La configurazione più diffusa per le agenzie usa VS Code con l’estensione PHP Debug:

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      },
      "log": true
    }
  ]
}

Una volta configurato, imposti un breakpoint nel codice PHP, avvii il debugger in VS Code, carichi la pagina nel browser con il parametro XDEBUG_SESSION e l’esecuzione si ferma al breakpoint. Puoi ispezionare ogni variabile, lo stack trace, e procedere step-by-step.

Profiling con Xdebug

Xdebug può generare file di profile in formato cachegrind, analizzabili con strumenti come KCacheGrind o Webgrind:

; Abilita il profiling (attiva solo quando serve)
xdebug.mode=profile
xdebug.output_dir=/tmp/xdebug-profiles
xdebug.start_with_request=yes

Il profiling genera un file per ogni request. Analizzando questi file puoi identificare funzioni lente, chiamate ripetute e colli di bottiglia che Query Monitor non può mostrare con lo stesso livello di dettaglio.

Logging Strutturato Custom per Agenzie

WP_DEBUG e wp_debug.log registrano errori PHP, ma non sono sufficienti per un’agenzia che gestisce molti siti. Serve logging strutturato personalizzato per tracciare eventi applicativi specifici.

Funzione di Logging Custom

// mu-plugins/agencypilot-logger.php
function ap_log( $message, $context = [], $level = 'info' ) {
    if ( ! defined( 'WP_DEBUG_LOG' ) || ! WP_DEBUG_LOG ) {
        return;
    }

    $entry = sprintf(
        "[%s] [%s] %s %s\n",
        current_time( 'Y-m-d H:i:s' ),
        strtoupper( $level ),
        $message,
        ! empty( $context ) ? json_encode( $context, JSON_UNESCAPED_UNICODE ) : ''
    );

    error_log( $entry, 3, WP_CONTENT_DIR . '/agencypilot-debug.log' );
}

// Esempi di utilizzo
ap_log( 'Aggiornamento plugin completato', [
    'plugin'  => 'woocommerce',
    'version' => '9.2.0',
    'duration_ms' => 3400,
], 'info' );

ap_log( 'API esterna fallita', [
    'endpoint'     => 'https://api.example.com/v2/orders',
    'response_code' => 503,
    'attempt'      => 3,
], 'error' );

Questo approccio produce log strutturati, facili da analizzare con strumenti come grep, jq o sistemi di log aggregation. Per le agenzie che gestiscono molti siti, consigliamo di inviare i log a un servizio centralizzato come Better Stack o Grafana Loki.

Logging Condizionale per Ambiente

// Log solo in sviluppo
function ap_dev_log( $message, $context = [] ) {
    if ( 'production' === wp_get_environment_type() ) {
        return;
    }
    ap_log( $message, $context, 'debug' );
}

// Log sempre, anche in produzione (per eventi critici)
function ap_critical_log( $message, $context = [] ) {
    ap_log( $message, $context, 'critical' );
    // Invia anche notifica email
    wp_mail( 'alerts@agencypilot.it', 'WordPress Critical', $message );
}

White Screen of Death (WSOD): Diagnosi in 5 Step

Il White Screen of Death è il problema WordPress più temuto: il sito diventa completamente bianco, nessun errore visibile, nessun log. Ecco il workflow che usiamo in AgencyPilot per risolverlo in meno di 10 minuti.

Step 1: Attivare WP_DEBUG Emergency Mode

// Aggiungi temporaneamente in wp-config.php, PRIMA della riga "That's all"
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );
@ini_set( 'display_errors', 1 );
error_reporting( E_ALL );

Questo mostrerà l’errore fatale a schermo. Una volta identificato, disattiva WP_DEBUG_DISPLAY.

Step 2: Controllare il debug.log

# Leggi le ultime 50 righe del log
tail -n 50 wp-content/debug.log

# Cerca errori fatal
grep -i "Fatal\|Parse\|Uncaught" wp-content/debug.log | tail -20

Step 3: Disattivare Tutti i Plugin via WP-CLI

# Disattiva tutti i plugin
wp plugin deactivate --all

# Riattiva uno per uno testando il sito dopo ogni attivazione
wp plugin activate woocommerce
wp plugin activate elementor
# ...continua finché il sito non si rompe di nuovo

Se il sito funziona con tutti i plugin disattivati, il problema è un conflitto. Riattivali uno per uno per identificare il colpevole. Per gestire questo su più siti, consulta la nostra guida su come gestire aggiornamenti plugin su multi-sito.

Step 4: Attivare il Tema Default

wp theme activate twentytwentyfive
# Se il sito funziona, il problema è nel tema

Step 5: Verificare la Cache

# Svuota cache oggiettiva (oppure WP Super Cache, W3 Total Cache, ecc.)
wp cache flush

# Svuota OPcache PHP
wp eval 'opcache_reset();'

Debug della REST API WordPress

La REST API WordPress è fondamentale per integrazioni moderne, headless e automazioni. Il debugging richiede strumenti diversi dal PHP tradizionale.

Abilitare il Logging delle Richieste REST

// mu-plugins/rest-api-debug.php
add_filter( 'rest_pre_serve_request', function( $served, $result, $request, $server ) {
    $route  = $request->get_route();
    $method = $request->get_method();
    $params = $request->get_params();

    // Log solo delle richieste non-GET (mutazioni)
    if ( 'GET' !== $method ) {
        ap_log( 'REST API Request', [
            'route'         => $route,
            'method'        => $method,
            'params'        => $params,
            'response_code' => $server->get_status() ?: 200,
        ], 'info' );
    }

    return $served;
}, 10, 4 );

Testare Endpoint REST con WP-CLI

# Lista tutti gli endpoint registrati
wp rest list

# Testa un endpoint
wp rest get /wp/v2/posts --per_page=2

# Testa con autenticazione
wp rest get /wp/v2/users --user=admin

# Crea un post via REST API
wp rest post /wp/v2/posts --user=admin \
  --title="Test Post" --content="Test content" --status=draft

Debug degli Errori di Autenticazione REST

Gli errori 401 e 403 sono i più comuni nella REST API. Le cause tipiche:

Best Practice di Debug per Agenzie Multi-Sito

1. Configurazione Standardizzata

Ogni sito che gestiamo ha la stessa configurazione di base in wp-config.php, versionata in Git. Questo significa che qualsiasi sviluppatore dell’agenzia sa dove trovare i log e come configurarli. Per approfondire, consulta la nostra guida su gestione multi-sito WordPress per agenzie.

2. Rotazione dei Log

Il file debug.log può crescere enormemente su siti ad alto traffico. Implementa una rotazione automatica:

# /etc/logrotate.d/wordpress
/var/log/wordpress/*-debug.log {
    daily
    rotate 14
    compress
    missingok
    notifempty
    create 0640 www-data www-data
}

3. Monitoring dei Log con Alert Automatici

#!/bin/bash
# Cron giornaliero per monitoring errori critici
LOG_FILE="/var/log/wordpress/site-debug.log"
ALERT_EMAIL="alerts@agencypilot.it"

# Conta errori fatal nelle ultime 24 ore
FATAL_COUNT=$(grep "$(date -d 'yesterday' +'%Y-%m-%d')" "$LOG_FILE" | grep -ci "Fatal\|Critical")

if [ "$FATAL_COUNT" -gt 0 ]; then
    echo "Attenzione: $FATAL_COUNT errori fatali rilevati su $(hostname)" | \
    mail -s "WordPress Alert: $(hostname)" "$ALERT_EMAIL"
fi

Per un monitoring più avanzato, integra i log WordPress con il nostro sistema di automazione WordPress via REST API per ricevere alert su Discord o Slack. Per la sicurezza dei log, consulta anche la nostra guida su sicurezza WordPress per agenzie.

4. Debug su Docker: Configurazione Consigliata

Per le agenzie che usano Docker, la configurazione di debug deve essere isolata nel container con un override file:

# docker-compose.override.yml (non committare in production)
services:
  wordpress:
    environment:
      WP_DEBUG: "true"
      WP_DEBUG_LOG: "true"
      WP_DEBUG_DISPLAY: "true"
    volumes:
      - ./debug.log:/var/www/html/wp-content/debug.log

Strumenti di Debug Complementari

FAQ — Domande Frequenti sul Debug WordPress

Posso attivare WP_DEBUG in produzione senza rischi?

Sì, se configurato correttamente. La combinazione WP_DEBUG=true, WP_DEBUG_LOG=true e WP_DEBUG_DISPLAY=false registra errori nel file di log senza mostrarli ai visitatori. L’impatto sulle performance è trascurabile. Evita invece SAVEQUERIES=true in produzione: ogni query viene salvata in memoria, raddoppiando il consumo.

Dove si trova il file debug.log in WordPress?

Per impostazione predefinita, il file debug.log si trova in wp-content/debug.log. Puoi personalizzare il percorso definendo WP_DEBUG_LOG con un path assoluto: define( 'WP_DEBUG_LOG', '/var/log/wordpress/debug.log' );. Per motivi di sicurezza, consigliamo di posizionare il log fuori dalla directory pubblica web.

Come faccio il debug di un plugin senza disattivarlo?

Usa Query Monitor: il pannello “Queries by Component” mostra quale plugin sta generando errori o query lente senza bisogno di disattivarlo. Alternativamente, usa error_log() con il nome del plugin come prefisso per tracciare l’esecuzione nel file di log.

Xdebug rallenta il sito WordPress?

Sì, Xdebug aggiunge overhead significativo (30-50% più lento anche in modalità idle). Non deve mai essere installato in produzione. Per il debug in produzione usa WP_DEBUG_LOG e Query Monitor. Xdebug è riservato allo sviluppo locale o staging.

Come loggare una variabile complessa (array/oggetto) in WordPress?

Usa error_log( print_r( $variable, true ) ); per array e oggetti. Per una rappresentazione più leggibile, usa error_log( json_encode( $variable, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE ) );. Se la variabile è molto grande, considera di loggare solo le chiavi o un subset con array_slice().