Configurazione di Composer per lo sviluppo di plugin WordPress

  • 4 min

Terzo articolo della serie sui fondamenti dello sviluppo di plugin WordPress. Nell’articolo precedente abbiamo creato un repository Git ben strutturato su GitHub. Ora aggiungiamo Composer per gestire le dipendenze e l’autoloading.

Se hai mai scritto una catena di require o include per caricare le tue classi PHP, sai quanto diventa fragile in fretta. Composer risolve questo problema e molto altro.

Alla fine di questo articolo avrai un file composer.json funzionante con autoloading PSR-4, pronto per far crescere il tuo plugin in modo pulito e professionale.

Prerequisiti: Questo articolo presuppone che Composer sia installato sulla tua macchina. In caso contrario, segui la guida ufficiale all’installazione. Partiamo dal repository creato nell’articolo precedente.

Cos’è Composer e perché usarlo

Composer è il gestore di dipendenze per PHP (pensa a npm per JavaScript o pip per Python). Per chi sviluppa plugin WordPress offre due vantaggi principali:

  • Autoloading: le tue classi vengono caricate automaticamente quando le usi, senza bisogno di require manuali.
  • Gestione delle dipendenze: puoi integrare librerie esterne in modo pulito e riproducibile.

Un malinteso comune è che Composer sia solo per progetti grandi e complessi. Non è così. Anche un plugin semplice beneficia dell’autoloading fin dal primo giorno.

Creare il file composer.json

Nella directory del plugin creata nell’articolo precedente, esegui:

composer init

Composer ti guiderà con una serie di domande interattive. Ecco i campi chiave e come compilarli:

{
    "name": "your-vendor/my-awesome-plugin",
    "description": "A short description of what this plugin does.",
    "type": "wordpress-plugin",
    "license": "GPL-2.0-or-later",
    "require": {
        "php": ">=8.1"
    },
    "prefer-stable": true,
    "config": {
        "sort-packages": true
    }
}

Alcuni dettagli: il campo name segue il formato vendor/package. Il type impostato su wordpress-plugin è una convenzione che strumenti come WordPress Packagist riconoscono. Il vincolo su PHP garantisce che il tuo plugin non venga installato su versioni non supportate.

Autoloading con PSR-4

PSR-4 è uno standard che associa i namespace PHP alle directory del filesystem. In pratica significa: se dai al tuo codice un namespace e dici a Composer dove trovarlo, ogni classe viene caricata automaticamente.

Aggiungi la sezione autoload al tuo composer.json:

{
    "autoload": {
        "psr-4": {
            "YourVendor\\MyAwesomePlugin\\": "src/"
        }
    }
}

Poi genera l’autoloader:

composer dump-autoload

Ora crea una classe di esempio in src/Plugin.php:

<?php

declare(strict_types=1);

namespace YourVendor\MyAwesomePlugin;

class Plugin
{
    public static function init(): void
    {
        // Il plugin parte da qui.
    }
}

E nel file principale del plugin, carica l’autoloader e usa la classe:

<?php
/**
 * Plugin Name: My Awesome Plugin
 * Description: A short description of what this plugin does.
 * Version:     0.1.0
 * Author:      Your Name
 * License:     GPL-2.0-or-later
 */

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

YourVendor\MyAwesomePlugin\Plugin::init();

Una riga per includere l’autoloader, una per avviare il plugin. Niente più catene di require.

La directory vendor/ e il .gitignore

Quando esegui composer install o composer dump-autoload, Composer crea una directory vendor/ che contiene l’autoloader e tutte le dipendenze installate.

Questa directory non va committata. Nel primo articolo l’abbiamo già aggiunta al .gitignore, ecco perché. La cartella vendor/ può essere ricreata in qualsiasi momento a partire dai file di configurazione.

Il file importante qui è composer.lock: registra le versioni esatte di ogni pacchetto installato. Questo file va committato, perché garantisce che chiunque cloni il repository ottenga le stesse identiche versioni con composer install.

In sintesi: composer.json e composer.lock vanno nel repository. vendor/ no.

Aggiungere dipendenze

Per aggiungere un pacchetto al tuo plugin:

composer require vendor/package-name

I pacchetti si trovano su packagist.org, il repository centrale di Composer.

Una distinzione importante: require è per le dipendenze di produzione, require-dev è per gli strumenti di sviluppo che non servono in produzione:

composer require --dev vendor/dev-tool

Più avanti nella serie useremo require-dev per installare strumenti come PHPCS per gli standard di codifica, PHPStan per l’analisi statica e PHPUnit per i test. Il Composer setup che abbiamo creato oggi è la base su cui si appoggiano tutti questi strumenti.

Prossimi passi

Ora hai Composer che gestisce l’autoloading e le dipendenze del tuo plugin. Insieme al repository Git del primo articolo, la struttura del progetto è già professionale e pronta a crescere.

Nel prossimo articolo configureremo wp-env, un ambiente di sviluppo locale basato su Docker che ti permette di testare il plugin in un’installazione WordPress completa, senza configurazioni manuali.

Autore: realloc

Prossimo articolo: wp-env, ambiente di sviluppo locale per plugin WordPress →

Condividi

Articoli correlati