Scrivere codice per WordPress e il tuo collega continua a chiederti di «sistemare spazi e indentazione» a ogni code review? Oppure il sito va in crash dopo l'aggiornamento di un plugin e non riesci a trovare l'errore nei log perché il codice è stato scritto senza uno standard coerente?

È uno scenario familiare per chiunque sviluppi WordPress in team. Abitudini di formattazione diverse, alcuni usano le Yoda conditions e altri no, e l'output escaping manca in diversi punti.

PHP CodeSniffer lo risolve in automatico: verifica il codice rispetto ai coding standard di WordPress direttamente nell'editor, evidenzia le violazioni e può correggerle con un solo comando. Qui sotto trovi una guida alla configurazione da zero per PhpStorm 2026.

💡 Panoramica rapida:

• Installa PHP CodeSniffer e i WordPress Coding Standards via Composer, nel progetto o globalmente
• Imposta il percorso di phpcs nella configurazione e aggiungi lo standard WordPress
• Configura un interprete PHP remoto se lavori tramite Vagrant, Docker o SSH
• Attiva l'ispezione PHP CodeSniffer Validation in PhpStorm e gli errori verranno evidenziati in tempo reale
• Imposta la formattazione automatica con PHP Code Beautifier and Fixer per correggere il codice con un solo comando

Video passo passo in inglese (stessi passaggi del testo):

Step 1: configurare un interprete PHP remoto

Se sviluppi con PHP in locale (XAMPP, MAMP, Local, server built-in), salta questo passaggio. Per Vagrant, Docker o un server remoto via SSH, devi specificare l'interprete in modo esplicito.

Apri Impostazioni → PHP (Ctrl+Alt+S), clicca […] accanto a CLI Interpreter e seleziona SSH Credentials o Docker Compose.

Compila:

• Indirizzo IP dell'host, lo stesso usato per il sito (ping example.dev ti aiuta)
• vagrant come nome utente e password (se usi Vagrant)
• /usr/bin/php, percorso dell'eseguibile PHP sul server

Salva e seleziona l'interprete creato dalla lista:

PhpStorm userà questo PHP specifico per eseguire CodeSniffer e altri strumenti di qualità del codice.

Step 2: installare PHP CodeSniffer via Composer

L'approccio più affidabile è installare PHPCS come dipendenza di progetto. Aggiungi al tuo composer.json:

1
{
2
  "require-dev": {
3
    "squizlabs/php_codesniffer": "^3.10"
4
  }
5
}

Poi esegui composer install. PhpStorm rileverà automaticamente phpcs e phpcbf in vendor/bin, quindi non dovrai impostare i percorsi manualmente.

Per un'installazione globale (se ti serve su tutti i progetti):

1
composer global require "squizlabs/php_codesniffer=*"

Verifica: l'eseguibile phpcs dovrebbe trovarsi in ~/.composer/vendor/bin/ (Linux/Mac) o %APPDATA%/Composer/vendor/bin/ (Windows).

Step 3: installare i WordPress Coding Standards

WPCS è un insieme di regole (sniff) per PHPCS che verifica la conformità specifica agli standard WordPress: escaping dell'output, Yoda conditions, prefissi delle funzioni e tutto quanto previsto dal WordPress Coding Standards Handbook.

Tramite Composer nel tuo progetto:

1
composer require --dev wp-coding-standards/wpcs:"^3.0"

Oppure globalmente (il vecchio metodo collaudato):

1
composer create-project wp-coding-standards/wpcs:dev-master --no-dev

Assicurati che lo standard compaia in ~/.composer/wpcs/ o vendor/wp-coding-standards/wpcs/.

Step 4: impostare il percorso dello standard nella configurazione di PHPCS

Vai nella cartella phpcs e specifica dove si trovano gli standard installati:

1
cd ~/.composer/vendor/bin
2
phpcs --config-set installed_paths ~/.composer/wpcs

Verifica che WordPress compaia nell'elenco degli standard disponibili:

1
phpcs -i

L'output dovrebbe mostrare quattro standard: WordPress, WordPress-Core, WordPress-Docs e WordPress-Extra.

Step 5: aggiungere phpcs al PATH

Apri ~/.bash_profile (o ~/.zshrc per ZSH) e aggiungi la riga:

1
PATH=$PATH:~/.composer/vendor/bin

Riavvia il terminale o esegui source ~/.bash_profile. Ora il comando phpcs è disponibile da qualsiasi cartella.

Testalo su un file di un tema o plugin qualsiasi:

1
cd wp-content/themes/your-theme
2
phpcs --standard=WordPress functions.php

Un output corretto si presenta così:

Gli errori sono suddivisi in due livelli: ERROR per le violazioni gravi e WARNING per i suggerimenti. Ogni riga contiene il numero della regola e una descrizione del problema.

Step 6: configurare PHP CodeSniffer in PhpStorm

Apri Impostazioni → PHP → Quality Tools → PHP_CodeSniffer (Ctrl+Alt+S).

Se hai installato tramite Composer nel progetto, PhpStorm rileverà automaticamente phpcs da vendor/bin. Se installato globalmente, clicca […] accanto a Configuration e specifica il percorso dell'eseguibile: ~/.composer/vendor/bin/phpcs.

Seleziona l'interprete PHP dall'elenco, lo stesso configurato nello step 1.

Step 7: attivare l'ispezione PHP CodeSniffer Validation

Vai a Impostazioni → Editor → Ispezioni, espandi PHP → Quality Tools e seleziona PHP_CodeSniffer validation.

Nel menu a tendina Standard di codifica, seleziona WordPress. Salva le impostazioni.

Da questo momento, PhpStorm controlla i file PHP aperti in tempo reale. Le violazioni vengono evidenziate con sottolineature ondulate, proprio come i normali errori dell'IDE. Passaci sopra con il cursore e apparirà un tooltip con la descrizione: cosa non va e come correggerlo.

Step 8: verifica che funzioni

Crea o apri un file PHP di un tema e scrivi intenzionalmente del codice non standard:

1
if(true){echo 'Spaces? Never heard of them';}

PhpStorm sottolineerà la riga: mancano gli spazi dopo if, intorno alle parentesi graffe e all'interno della condizione. Passa il cursore sopra la sottolineatura e vedrai il testo dell'errore e il numero della regola WordPress.

Step 9: configura la correzione automatica con PHP Code Beautifier and Fixer

Non devi correggere ogni violazione a mano. PHP Code Beautifier and Fixer (phpcbf) è installato insieme a PHPCS e può correggere automaticamente il codice secondo lo standard selezionato.

Apri Impostazioni → PHP → Quality Tools, nella sezione External Formatters seleziona PHP Code Beautifier and Fixer. Ora quando richiami Codice → Reformat Code (Ctrl+Alt+L / Cmd+Option+L), PhpStorm non solo allineerà l'indentazione con il suo formattatore interno, ma applicherà anche le regole WordPress tramite phpcbf.

Inoltre, configura lo stile di codice WordPress per il formattatore integrato: Impostazioni → Editor → Stile codice → PHP → Imposta da → Stile predefinito → WordPress. In questo modo entrambi gli strumenti lavorano nella stessa direzione e non entrano in conflitto.

Step 10: cosa fare per i nuovi progetti

Per ogni nuovo progetto WordPress, ti basta ripetere lo step 1 (interprete, se remoto), lo step 6 (imposta phpcs nelle impostazioni) e lo step 7 (abilita l'ispezione). Se nel progetto usi Composer, gli step 2-4 si risolvono con una sola riga: composer require --dev wp-coding-standards/wpcs.

⁉️🤔 Domande frequenti

Qual è la differenza tra WordPress, WordPress-Core, WordPress-Docs e WordPress-Extra?

WordPress è il set base di tutte le regole tranne la documentazione. WordPress-Core contiene solo le regole della guida ufficiale allo sviluppo (indentazione, nomenclatura, Yoda conditions). WordPress-Extra aggiunge i controlli di sicurezza: escaping dell'output, validazione dei dati in ingresso. WordPress-Docs verifica gli standard di documentazione del codice (PHPDoc). Nella pratica, usa WordPress perché include Core ed Extra.

PhpStorm non vede phpcs dopo l'installazione. Cosa devo fare?

Verifica che la cartella vendor/bin (o ~/.composer/vendor/bin) sia aggiunta al PATH e contenga l'eseguibile phpcs. In PhpStorm, apri Impostazioni → PHP → Quality Tools → PHP_CodeSniffer, clicca […] e specifica manualmente il percorso di phpcs. Dopo aver cambiato l'interprete o reinstallato le dipendenze, potrebbe essere necessario resettare la configurazione usando il pulsante Reset nella stessa finestra.

Posso usare PHPCS senza Composer, semplicemente scaricando l'archivio phar?

Sì, ma lo sconsigliamo. Con l'installazione via Composer, PhpStorm rileva automaticamente phpcs, phpcbf e tutti gli standard registrati. Con l'archivio phar, dovrai impostare i percorsi manualmente e gestire gli aggiornamenti separatamente. Per la collaborazione in team, una dipendenza Composer nel composer.json blocca la versione, così tutti gli sviluppatori hanno lo stesso set di regole.

Come escludo file o cartelle specifici dalla verifica?

Crea un file phpcs.xml nella root del progetto. Puoi escludere directory (<exclude-pattern>vendor/*</exclude-pattern>), impostare lo standard e modificare la severità delle singole regole. PhpStorm rileverà automaticamente questo file se si trova nella root del progetto e si chiama phpcs.xml o phpcs.xml.dist.

Perché PHPCS segnala un errore su wp_redirect() senza exit?

Lo standard WordPress richiede exit o wp_die() dopo ogni redirect: wp_redirect() imposta solo l'header ma non interrompe l'esecuzione dello script. Senza exit, il codice dopo il redirect continuerà a essere eseguito, il che rappresenta una falla di sicurezza. L'uso corretto è: wp_redirect( home_url() ); exit;.

Cosa fare se la codebase è già grande e stai solo implementando gli standard

Lanciare PHPCS su un progetto con migliaia di violazioni è un modo sicuro per demotivare il team. Inizia in piccolo: correggi gli errori critici (error, non warning) usando phpcbf, poi abbassa gradualmente la soglia. Aggiungi un phpcs.xml con esclusioni per il codice legacy e attiva le nuove regole una alla volta, ogni mese.

Ecco un piano passo passo per implementare gli standard su un progetto attivo:

• Esegui phpcs --standard=WordPress --report=summary per vedere il numero totale di errori.
• Correggi automaticamente tutto il possibile: phpcbf --standard=WordPress .
• Ordina gli errori rimanenti per severità, affrontando prima quelli critici.
• Aggiungi la verifica alla CI (GitHub Actions, GitLab CI): fai fallire la build in caso di nuove violazioni nelle pull request.

Inizia con un semplice composer require --dev wp-coding-standards/wpcs in un progetto. Dopo una settimana, il team si sarà abituato all'evidenziazione. Dopo un mese, si sarà abituato al codice pulito. Quale standard di codifica usi? Facci sapere nei commenti.