Da Zero a Packagist: pubblicare una libreria PHP su Composer

Pubblicare un pacchetto Composer significa rendere il proprio codice installabile con un semplice comando da CLI

composer require vendor/package

e tenere aggiornamenti, versioni e dipendenze sotto controllo. Per seguire la guida abbiamo bisogno di:

• Git versione maggiore o uguale alla 2.0 installata e configurata
• Un account GitHub e token con permesso repo
• Composer con versione maggiore o uguale alla 2.5 in $PATH
• Account gratuito su Packagist.org (che si registra tramite GitHub via OAuth)

Rifacendoci all’articolo in cui avevamo visto come sviluppare una libreria di Statistica descrittiva la struttura della repository era la seguente:

descriptive-statistics-php/
├─ composer.json
├─ composer.lock
├─ phpunit.xml
├─ examples/
│  └─ geometric_mean_demo.php
│  └─ harmonic_mean_demo.php
│  └─ iqr_demo.php
│  └─ mad_demo.php
│  └─ mean_demo.php
│  └─ median_demo.php
│  └─ min_max_demo.php
│  └─ mode_demo.php
│  └─ percentile_demo.php
│  └─ range_demo.php
│  └─ standard_deviation_demo.php
│  └─ trimmed_mean_demo.php
│  └─ variance_demo.php
├─ src/
│  └─ DescriptiveStats.php
├─ tests/
│  └─ DescriptiveStatsTest.php
└─ vendor/
    └─ autoload.php

Nel terminale, all’interno della cartella del progetto digitiamo il comando:

composer init

Composer ci chiederà alcune informazioni partendo dal Package name che viene espresso come vendor/package-name. Nel mio caso essendo il mio account denominato “thesimon82” il nome del pacchetto sarà thesimon82/descriptive-statistics. Confermiamo con invio.

Ora ci viene chiesta la descrizione, per questo progetto inseriamo: Lightweight PHP class for descriptive statistics.

L’autore e ci viene restituito l’autore di default se l’avevamo già impostato, altrimenti inseriamo il nostro nome e cognome.

Minimum stability, se è una versione stabile inseriamo “stable”.

Per Package Type inseriamo: “library”

In license: MIT

Ci viene chiesto se vogliamo inserire, uno per uno, i pacchetti di produzione (require) che la libreria necessita per funzionare. In questo caso la classe è stand-alone (usa solo funzioni native di PHP), quindi non abbiamo altre dipendenze oltre alle versione minima di PHP pertanto possiamo anche dichiarare “no”. Se stai pensando a PHPUnit per i test sui metodi della classe, ti ricordo che PHPUnit è stato settato solo per la fase di sviluppo e test pertanto va inserito in require-dev e non in require. In questo modo chi installerà il pacchetto in produzione non si troverà PHPUnit tra le dipendenze di runtime.

La domanda successiva infatti richiede proprio se ho intenzione di definire le mie dipendenze dev in modo interattivo (require-dev), qui digitiamo “yes” e ci chiederà di inserire il nome del pacchetto. Digitiamo ora phpunit/phpunit. Ci darà una lista di pacchetti trovati e selezioniamo phpunit/phpunit con il numero corrispondente. Confermiamo con invio e ci viene chiesto quale versione intendiamo includere. Confermiamo semplicemente con invio per installare l’ultima versione.

Ci chiederà ora se vogliamo installare altri pacchetti di dipendenze, ma non ne abbiamo altri quindi premiamo semplicemente invio.
Ora ci chiederà se intendiamo aggiungere un mapping PSR-4 per l’autoload delle classi chiedendoci di mappare il namespace Thesimon82DescriptiveStatistics ma nel progetto avevamo utilizzato Renor\Statistics quindi digitiamo n per skippare la proposta.

Finalmente otteniamo un resoconto dei dati inseriti:

{
    "name": "thesimon82/descriptive-statistics",
    "description": "Lightweight PHP class for descriptive statistics",
    "type": "library",
    "require-dev": {
        "phpunit/phpunit": "^12.1"
    },
    "license": "MIT",
    "authors": [
        {
            "name": "Simone Renzi",
            "email": "info@simonerenzi.com"
        }
    ],
    "minimum-stability": "stable",
    "require": {},
    "autoload": {
        "psr-4": {
            "Renor\Statistics\": "src/"
        }
    }
}

Do you confirm generation [yes]? 

Qui controlliamo i dati e se tutto è giusto confermiamo con “yes” e installiamo le dipendenze.

Al termine digitiamo il comando:

composer dump-autoload per rigenerare l’autoloader delle classi.

È arrivato il momento di fare il commit con questa serie di comandi:

git add .
git commit -m "feat: first stable release"
git tag v1.0.0
git push origin main v1.0.0

Ora ci muoviamo su GitHub e dovremmo vedere la nostra repo con l’ultimo commit, nel mio caso thesimon82 feat: first stable release.

Copiamo l’URL in alto sulla barra degli indirizzi e ci spostiamo su packagist.

Clicchiamo in alto su “Submit” e incolliamo nel campo di testo il link di GitHub che abbiamo copiato. Poi premiamo il pulsante Check. A questo punto Packagist analizzerà il composer.json e mostrerà subito la scheda del pacchetto. Cliccando sul pulsante in basso “Submit” viene creato il Package.

Abbiamo terminato, ora è il momento di testare il funzionamento.

Creiamo una nuova cartella “Stats Test” poi andiamo su terminale ed entriamo all’interno della cartella.
Qui digitiamo:

composer require thesimon82/descriptive-statistics

Ora importiamo questa cartella all’interno del nostro ambiente di sviluppo e creiamo un nuovo file nella root: test.php

<?php
require_once 'vendor/autoload.php';
use RenorStatisticsDescriptiveStats;

$stats = new DescriptiveStats([1, 2, 3, 4, 5,6.22]);
echo $stats->mean();

Come possiamo vedere, stiamo includendo l’autoloader generato da Composer in cui tutti le classi mappate con PSR-4 diventano disponibili senza ulteriori require.

Definiamo il namespace utilizzato nella classe DescriptiveStats e istanziamo un nuovo oggetto con un dataset numerico. Ti ricorderai che il costruttore della classe filtrava automaticamente eventuali valori non numerici, riallineava le chiavi dell’array e lanciava un’eccezione se l’insieme fosse risultato vuoto. Viene quindi richiamato il metodo mean() che esegue la media e lo visualizza a schermo.

Se adesso dal terminale lanci il comando php test.php se hai fatto tutto correttamente dovresti avere come risultato 3.5366666666667 che è proprio la media approssimata dei valori che abbiamo passato al costruttore della classe.

Conclusioni

Abbiamo visto come trasformare una semplice classe PHP in un pacchetto Composer distribuito su Packagist. Ora la libreria può essere installata con un unico comando, beneficia di versionamento semantico, integrazione continua e di un’automazione che aggiorna automaticamente la scheda su Packagist a ogni nuovo tag.

Da questo momento il ciclo di vita è lineare: implementi una funazionalità, esegui i test, incrementi la versione, crei il tag e fa il push su GitHub. Packagist e Composer faranno il resto!

[starbox]