Coding Standards con PHPCS e WPCS

  • 4 min

Sesto articolo della serie sui fondamenti dello sviluppo di plugin WordPress. Abbiamo un repository, Composer, un ambiente locale e una pipeline CI. Ora facciamo in modo che il codice segua automaticamente gli standard WordPress.

Uno stile di codice coerente non è una questione estetica — riduce i bug, rende le revisioni più veloci e facilita la collaborazione. WordPress ha i propri standard di codifica (WPCS) e PHP_CodeSniffer (PHPCS) è lo strumento che li fa rispettare automaticamente.

Alla fine di questo articolo avrai PHPCS configurato per il tuo plugin, funzionante sia in locale che nella pipeline CI di GitHub Actions.

Cos’è PHPCS e perché servono gli standard

PHPCS è un linter per PHP: analizza il codice e segnala le violazioni rispetto a un insieme di regole definite. I WordPress Coding Standards (WPCS) sono il set di regole ufficiale per il codice WordPress.

L’aspetto interessante è che WPCS va oltre lo stile: include regole per la sanitizzazione dell’input, l’escaping dell’output e altre best practice di sicurezza. Non si tratta solo di indentazione e spazi — si tratta di scrivere codice più sicuro.

Installazione via Composer

Installa PHPCS e i relativi pacchetti come dipendenze di sviluppo:

composer require --dev squizlabs/php_codesniffer \
    wp-coding-standards/wpcs \
    phpcompatibility/phpcompatibility-wp \
    dealerdirect/phpcodesniffer-composer-installer

Ogni pacchetto ha un ruolo preciso: php_codesniffer è lo strumento PHPCS stesso. wpcs contiene le regole degli standard WordPress. phpcompatibility-wp aggiunge controlli di compatibilità con diverse versioni di PHP, calibrati per WordPress. Il pacchetto phpcodesniffer-composer-installer registra automaticamente tutti gli standard con PHPCS — senza questo dovresti configurare i percorsi manualmente.

Verifica che tutto sia installato correttamente:

vendor/bin/phpcs -i

Dovresti vedere WordPress, WordPress-Core, WordPress-Extra e WordPress-Docs nell’elenco degli standard disponibili.

Configurazione con phpcs.xml.dist

PHPCS cerca un file di configurazione nella root del progetto. La convenzione .dist significa che il file viene committato nel repository, ma può essere sovrascritto localmente con un file phpcs.xml (che andrebbe aggiunto al .gitignore).

Crea phpcs.xml.dist nella root del plugin:

<?xml version="1.0"?>
<ruleset name="My Awesome Plugin">
    <description>PHPCS configuration for My Awesome Plugin.</description>

    <!-- What to scan -->
    <file>./src/</file>
    <file>./my-awesome-plugin.php</file>

    <!-- What to ignore -->
    <exclude-pattern>/vendor/*</exclude-pattern>
    <exclude-pattern>/node_modules/*</exclude-pattern>
    <exclude-pattern>/tests/*</exclude-pattern>

    <!-- WordPress standard -->
    <rule ref="WordPress"/>

    <!-- PHP compatibility -->
    <config name="testVersion" value="8.1-"/>
    <rule ref="PHPCompatibilityWP"/>

    <!-- Minimum supported WordPress version -->
    <config name="minimum_supported_wp_version" value="6.4"/>

    <!-- Plugin text domain -->
    <config name="text_domain" value="my-awesome-plugin"/>
</ruleset>

Una nota sugli standard disponibili: WordPress è il set completo e include WordPress-Core (stile del codice), WordPress-Extra (best practice aggiuntive) e WordPress-Docs (documentazione inline). Per iniziare, usa WordPress — è il più completo. Potrai sempre escludere singole regole in seguito se necessario.

Eseguire PHPCS

Con il file di configurazione in posizione, esegui PHPCS:

vendor/bin/phpcs

PHPCS legge automaticamente phpcs.xml.dist e analizza i file specificati. L’output mostra errori e warning con il percorso del file, il numero di riga e il nome della regola violata.

Molte violazioni di stile possono essere corrette automaticamente con PHP Code Beautifier and Fixer:

vendor/bin/phpcbf

Aggiungi entrambi i comandi come script Composer, come abbiamo impostato nell’articolo su GitHub Actions:

{
    "scripts": {
        "phpcs": "phpcs",
        "phpcbf": "phpcbf"
    }
}

Ora composer run phpcs funziona sia in locale che in CI – stesso comando, stesso risultato.

Integrazione in GitHub Actions

Nell’articolo su GitHub Actions avevamo già preparato uno step placeholder per PHPCS. Ora è il momento di attivarlo. Nel file .github/workflows/ci.yml, lo step è semplicemente:

      - name: Check coding standards
        run: composer run phpcs

Nient’altro da configurare. Composer installa PHPCS come dipendenza di sviluppo, il file phpcs.xml.dist fornisce la configurazione, e lo script Composer esegue il controllo. Se PHPCS trova violazioni, il workflow fallisce — ed è esattamente quello che vogliamo: nessun codice non conforme arriva su main senza essere notato.

Prossimi passi

Ora hai gli standard di codifica WordPress applicati automaticamente, sia durante lo sviluppo locale che nella pipeline CI. Il tuo plugin segue le convenzioni dell’ecosistema WordPress fin dalla prima riga di codice.

Nel prossimo articolo configureremo PHPStan per l’analisi statica. Mentre PHPCS si occupa dello stile e delle best practice, PHPStan va più in profondità: trova errori di tipo, codice irraggiungibile e problemi logici prima ancora di eseguire il codice.

Autore: realloc

Prossimo articolo: Analisi statica con PHPStan →

Condividi

Articoli correlati