Come creare un pacchetto Composer

Riutilizzare il codice comporta il problema della gestione delle dipendenze, storicamente un processo piuttosto manuale e soggetto a errori. Fortunatamente, negli ultimi anni la maggior parte dei linguaggi di programmazione ha risolto questo problema introducendo diversi strumenti per la gestione delle dipendenze. Nell’ecosistema PHP, Composer è diventato lo standard grazie alla sua semplicità d’uso, alla sua flessibilità e alla sua ampia adozione.

Anche se Composer è stato creato per la gestione delle dipendenze, potete utilizzarlo anche per attività quali:

• Autoloading: caricare automaticamente classi e funzioni da librerie esterne per renderle facilmente accessibili dal vostro codice e semplificare il processo di integrazione del codice esterno nel progetto.
• Generazione di codice: genera codice di base per il vostro progetto, come i file di configurazione o altri frammenti di codice comunemente usati per accelerare il processo di sviluppo e garantire la coerenza.
• Scripting: un sistema di scripting integrato può automatizzare attività comuni, come l’esecuzione di test o la generazione di documentazione dalla vostra base di codice. Questo può aiutare a snellire il flusso di lavoro dello sviluppo e a ridurre il lavoro manuale.

Questo tutorial vi guiderà passaggio per passaggio nella creazione del vostro pacchetto Composer e nella sua pubblicazione su Packagist, un repository di pacchetti PHP che gli sviluppatori di tutto il mondo possono utilizzare nei loro progetti.

Come funziona Composer?

Per prima cosa, assicuriamoci di aver compreso Composer. In parole povere, Composer funziona utilizzando un file composer.json che contiene le definizioni delle dipendenze del progetto PHP. Cerca questi pacchetti da un repository centralizzato e poi scarica e installa automaticamente le dipendenze utilizzando il repo dei pacchetti.

Supponendo che abbiate già installato Composer nel vostro ambiente di lavoro PHP, ecco come si presenta il processo di download e installazione delle dipendenze:

1. Definite le dipendenze necessarie per il vostro progetto in un file composer.json nella directory principale del progetto. Questo file include le informazioni sulle librerie necessarie e le loro versioni, nonché qualsiasi altra impostazione di configurazione o dipendenza per tali librerie.
2. Risolvete le dipendenze in Composer con comandi come install per installare le dipendenze richieste; update per aggiornare le dipendenze esistenti e require per aggiungere nuove dipendenze al file composer.json. Quando eseguite un comando, Composer legge il file composer.json per determinare le dipendenze necessarie, controlla il repo dei pacchetti per trovare l’ultima versione di ogni dipendenza adatta al vostro ambiente PHP e verifica eventuali conflitti o vincoli di versione.
3. Composer scarica e installa le dipendenze necessarie, comprese le librerie, nella directory vendor del vostro progetto. Composer crea un file composer.lock che registra le versioni esatte delle dipendenze installate.
4. Composer imposta un autoloader che carica automaticamente le classi e le funzioni dalle dipendenze installate. In questo modo è facile utilizzare le librerie installate nel vostro progetto senza dover includere manualmente ogni file.

Per farla breve, Composer semplifica la gestione delle dipendenze nei progetti PHP, rendendo più facile l’installazione, l’aggiornamento e l’utilizzo di librerie e framework esterni.

Creare e pubblicare un pacchetto Composer

Questo tutorial vi mostra come creare una semplice libreria PHP chiamata tempconv che converte la temperatura Celsius in Fahrenheit e viceversa e come pubblicarla come pacchetto Composer.

Prerequisiti

Prima di iniziare, dovrete avere a disposizione un paio di cose:

• PHP e Composer installati correttamente sul vostro sistema. Al momento in cui scriviamo, l’ultima versione di Composer è la v2.6.6, ma queste istruzioni dovrebbero funzionare con qualsiasi variante della v2.
• Un account GitHub per creare un repository per ospitare il vostro codice.
• Un account Packagist per pubblicare la vostra libreria.

Creare un repository del progetto

Create il vostro repository GitHub per questo tutorial, dove potrete inserire il codice e i file della vostra libreria finita.

Questo tutorial utilizza il nome del progetto tempconv. Nel campo Descrizione, fornite brevi dettagli sull’applicazione. Selezionate la casella per aggiungere un file README, scegliete il modello Composer per l’opzione Aggiungi .gitignore e selezionate una licenza a vostra scelta – questo tutorial utilizza la licenza MIT. Infine, cliccate su Create repository.

Clonare il repository

Clonate il repository appena creato sul vostro computer locale. Non dimenticate di sostituire l’URL con il vostro, sia qui che in tutto il tutorial:

$ git clone https://github.com/rexfordnyrk/tempconv.git

Questo crea una directory chiamata tempconv nella vostra directory di lavoro corrente. A questo punto, contiene solo i file README.md, LICENSE e .gitignore, ma anche qui creerete i file del vostro pacchetto.

Creare la libreria PHP

Nella cartella del progetto, aggiungete un file chiamato TemperatureConverter.php con il seguente codice:

<?php

namespace RexfordnyrkTempconv;

class TemperatureConverter
{
    //Caller must provide the temperature value and the unit either C Celsius or F Fahrenheit
    public function convert($temperature, $unit)
    {
        //Checking whether the unit we're working with is Celsius or Fahrenheit
        if ($unit === 'C') {
            $fahrenheit = ($temperature * 9 / 5) + 32;
            return $fahrenheit;
        } elseif ($unit === 'F') {
            $celsius = ($temperature - 32) * 5 / 9;
            return $celsius;
        } else {
            //Throwing error if the unit provided is neither C nor F
            throw new InvalidArgumentException('Invalid unit, only C (Celsius) or F (Fahrenheit) are allowed');
        }
    }
}

Questa classe ha un unico metodo chiamato convert che accetta la temperatura e l’unità come argomenti e restituisce la temperatura convertita. Lancia un’eccezione se l’unità non è valida.

Per ora è sufficiente. In uno scenario reale, probabilmente scriverete dei test unitari per assicurarvi che il vostro codice funzioni come previsto dopo le modifiche o gli aggiornamenti.

Creare il pacchetto composer.

Una volta creato il codice della libreria, è il momento di creare un pacchetto Composer. Genererete un file composer.json per il vostro pacchetto utilizzando una procedura guidata passo dopo passo, e tratteremo alcune best practice per organizzare il codice come pacchetto prima di inviarlo al repository.

Generare un file di pacchetto composer.json

Sebbene possiate scrivere manualmente il contenuto di un file composer.json nella cartella principale del vostro progetto, è meglio generarlo usando il seguente comando di Composer:

$ composer init

Questo comando dà inizio a una piccola procedura guidata passo dopo passo. Le risposte che darete a richieste come il nome del pacchetto, la descrizione, le informazioni sull’autore e il tipo di licenza genereranno il file composer.json del vostro pacchetto.

La documentazione di Composer illustra i valori attesi e le altre opzioni che potete utilizzare per definire il composer. json del vostro progetto.

Notate che la procedura guidata fornisce delle risposte predefinite alle domande dove possibile, come ad esempio la derivazione del vostro nome e della vostra email da git. Sentitevi liberi di cambiarle se volete.

Questa libreria non dipende da altri pacchetti per le sue funzionalità, quindi potete rispondere No alle domande che specificano le dipendenze.

La procedura guidata mostra un’anteprima del contenuto del file generato e chiede di confermarlo per completare la procedura.

Organizzare i file del pacchetto

Il completamento della procedura guidata crea due directory oltre al file composer.json:

• src per il codice sorgente
• vendor per le dipendenze scaricate

Spostate il file TemperatureConverter.php nella cartella src. Se la vostra libreria ha delle dipendenze, eseguite composer install per generare l’autoloader e installare le dipendenze del pacchetto.

Caricare il codice su GitHub

Aggiungete le modifiche e i nuovi file a git:

$ git add -A

Eseguite il commit delle modifiche apportate al repository locale ed effettuate il push al repo remoto su GitHub in modo da poter pubblicare facilmente il progetto nella prossima sezione:

$ git commit -am "Initial Release" && git push

Creare una versione release per la libreria

Con il codice nel vostro repository, potete creare una versione della vostra libreria con un numero di versione in modo che gli altri sviluppatori possano tenere traccia degli aggiornamenti stabili e significativi.

Andate al vostro repo su GitHub e cliccate su Releases sotto la sezione About. Nella pagina delle release, in cui si suppone che non ci sia nulla al momento, cliccate su Create a new release.

Inserite alcuni dettagli sulla vostra release, come la versione del tag e il titolo della release. La versione del tag deve essere un identificativo unico per questa release (ad esempio: v1.0.0) e il titolo della release deve descrivere le modifiche che include (ad esempio: Initial release).

Opzionalmente, potete aggiungere una descrizione della versione. Se volete caricare un file, ad esempio un file binario compilato o un archivio di codice sorgente, potete trascinare il file nell’area Attach binaries by dropping them here or selecting them, ma non è necessario per questo tutorial.

Cliccate su Publish release per creare la release.

Il vostro progetto dovrebbe ora essere disponibile nella pagina delle Release del vostro repository. Gli utenti possono scaricare i file che avete allegato e visualizzare le note di rilascio. Inoltre, se avete aggiunto un tag per la release, gli altri sviluppatori possono utilizzarlo per verificare il codice esatto incluso.

La vostra libreria è pronta per essere condivisa con il mondo. Pubblichiamola come pacchetto su Packagist.

Come iniziare con Packagist

Packagist è il principale repository di pacchetti per PHP. Offre una posizione centrale agli sviluppatori per pubblicare e condividere i loro pacchetti PHP e agli altri sviluppatori per scoprire e utilizzare questi pacchetti nei loro progetti. Pubblichiamo il vostro pacchetto!

Andate sul sito web di Packagist, cliccate su Login e selezionate GitHub come metodo di accesso per utilizzare il vostro account GitHub per l’autenticazione.

Cliccate su Authorize per concedere a Packagist il permesso di accedere all’account.

Inviare il pacchetto Composer su Packagist

Per pubblicare un pacchetto su Packagist, inviate il repository GitHub contenente il file composer.json che descrive il vostro pacchetto e le sue dipendenze. Cliccate su Submit sul sito di Packagist, fornite l’URL del vostro repository nella pagina che appare e cliccate su Check per convalidarlo.

Se il repository è valido, Packagist rileva il nome del pacchetto e il pulsante Check diventa Submit.

Fate clic su Submit e Packagist si prenderà un attimo per configurare e pubblicare il vostro progetto.

Ecco fatto! Il vostro pacchetto è ora disponibile su Packagist per essere utilizzato da altri sviluppatori come dipendenza nei loro progetti.

Utilizzare il pacchetto Composer in altri progetti

Da adesso in poi, potrete utilizzare il vostro pacchetto pubblicato in altri progetti aggiungendolo come dipendenza nel file composer.json. Potete creare e modificare manualmente il file, ma è meglio usare il comando Composer come segue:

$ composer require rexfordnyrk/tempconv

Composer crea automaticamente il file composer.json se non esiste già, quindi trova, scarica e carica automaticamente il pacchetto da Packagist. L’output dovrebbe essere simile a questo:

Create un file demo.php che contenga il codice della vostra applicazione dimostrativa per lavorare con la vostra libreria.
Potete quindi utilizzare la classe TemperatureConverter nel codice della vostra applicazione in questo modo:

<?php
use RexfordnyrkTempconvTemperatureConverter;

require_once './vendor/autoload.php';

$converter =  new TemperatureConverter();

$fahrenheit = $converter->convert(20, 'C');
echo "20°C is equivalent to $fahrenheit °Fn";

$celsius = $converter->convert(68, 'F');
echo "68°F is equivalent to $celsius °Cn";

Questo codice utilizza la classe TemperatureConverter per convertire le temperature di 20 Celsius e 68 Fahrenheit e fornire i risultati. Il file autoloader.php importato è stato creato da Composer per caricare tutte le dipendenze necessarie. Questo si occupa di caricare automaticamente la classe quando necessario.

Infine, eseguite questo codice nel vostro terminale:

$ php demo.php

Dovreste ottenere un risultato simile a questo:

$ php demo.php
20°C is equivalent to 68 °F
68°F is equivalent to 20 °C

Riepilogo

Ed eccoci qui, avete appena creato una semplice libreria PHP che converte la temperatura da Celsius a Fahrenheit e viceversa in una classe orientata agli oggetti che può essere riutilizzata in altre applicazioni. Abbiamo visto insieme come utilizzare Composer per creare un pacchetto dalla classe con il comando Composer Init e abbiamo appreso alcune pratiche di base per l’organizzazione del codice della vostra libreria. Infine, avete pubblicato la vostra libreria su Packagist, in modo che voi e altri sviluppatori possiate utilizzarla come dipendenza in altri progetti.

Naturalmente, una volta terminato lo sviluppo della vostra applicazione, dovrete scegliere un host. Portate il vostro sviluppo PHP a un livello superiore con l’Hosting di Applicazioni web di Kinsta. Potete distribuire la vostra applicazione PHP basata su Composer in pochi minuti. Basta aggiungere la vostra applicazione tramite il repository git del progetto e Kinsta si occuperà di tutto il resto. Rileva automaticamente il file Composer e costruisce automaticamente la vostra applicazione. Iniziate oggi stesso senza rischi!

Rexford Nyarko

Rexford Nyarko is a solution architect with a background in software and network systems, cloud environments, server administration, and various database technologies. Rexford particularly enjoys explaining technical concepts to non-technical audiences.