Il file composer.json: le basi

La struttura del file di configurazione

L'eseguibile del progetto Composer, che abbiamo imparato ad installare e ad avviare da linea di comando, si aspetta un file di configurazione di nome composer.json nella directory root del progetto di cui vogliamo gestire le dipendenze. Si tratta di un semplice file di testo in formato JSON quindi con una leggibilità molto alta. Composer supporta alcuni comandi per la generazione e la modifica di questo file ma vedremo come modificarlo manualmente in modo da avere una maggiore padronanza dello strumento.

Il file di configurazione supporta numerose proprietà che concettualmente si possono dividere in:

• proprietà per la gestione delle dipendenze;
• proprietà per l'autoloading;
• metadata per le informazioni sullo sviluppo, utili per la pubblicazione del pacchetto.

Le prime due categorie saranno oggetto di questa e delle prossime due lezioni perché sono strettamente legate all'utilizzo di Composer, mentre la terza sarà trattata in una lezione successiva che avrà come argomento la pubblicazione del proprio lavoro su Packagist.

Le proprietà per la gestione delle dipendenze

Composer gestisce le dipendenze del nostro progetto dividendole in due categorie:

• dipendenze di produzione, cioè le librerie che servono al nostro progetto per funzionare;
• dipendenze di sviluppo, cioè le librerie necessarie allo svolgimento dei test o allo sviluppo vero e proprio.

Ad esempio, se il nostro progetto fa uso di un ORM per l'accesso ad un database dovremo dichiarare questa dipendenza tra quelle di produzione, se invece vogliamo usare un framework per l'esecuzione dei test come PHPUnit dovremo dichiarare la dipendenza tra quelle di sviluppo. Questa differenziazione è molto utile perché è possibile generare un autoloader ottimizzato per gli ambienti di produzione che tra le altre cose non installa le dipendenze di sviluppo per aumentare ulteriormente le prestazioni.

Ogni pacchetto che possiamo richiedere per il nostro progetto ha alcune caratteristiche descritte tra le proprietà dei metadata, quelle che ci interessano in questo contesto sono name e version. Per dichiarare una dipendenza di produzione dobbiamo usare la proprietà require mentre per le dipendenze di sviluppo require-dev indicando in entrambi i casi il nome completo del pacchetto e la versione che vogliamo installare.

Tutti i pacchetti installati verranno inseriti in una cartella di nome vendor nella directory del file composer.json.

Gestire i livelli di stabilità

Per il numero di versione da installare possiamo dichiarare una versione specifica, una versione minima, una versione massima, un ramo di sviluppo (ad esempio alpha, dev, stable) o addirittura un codice di riferimento ad un commit eseguito con Git. Vedremo in dettaglio come richiedere una versione compatibile con i nostri sistemi.

L'altro parametro utile per la gestione delle dipendenze è minimum-stability che indica al gestore di pacchetti di ignorare qualsiasi versione che sia al di sotto del livello indicato a meno di specificare una release meno stabile in maniera esplicita per un singolo pacchetto. Il consiglio per i progetti che andranno in produzione è di dipendere solo da pacchetti "stable", se possibile, in quanto per le altre versioni non è in genere garantita la retrocompatibilità e quindi un aggiornamento potrebbe causare la comparsa di errori o malfunzionamenti. Dalla versione più instabile a quella più stabile:

• dev
• alpha
• beta
• RC (release candidate)
• stable

Un'altra proprietà che può essere utile nella gestione delle dipendenze è prefer-stable che accetta come valori true o false. Se la proprietà è impostata a true verranno installate versioni stabili anche se sono disponibili versioni più recenti ma con un livello di stabilità minore.

Lo schema del file composer.json con le proprietà che abbiamo indicato diventa quindi il seguente:

{
    "require": {
        "vendor-name/project-name":   "version",
        "vendor-name/project-name-2": "version"
    },
    "require-dev": {
        "vendor-name/project-name-dev": "version",
        "vendor-name/dev-project-name": "version"
    },
    "minimum-stability": "stable",
    "prefer-stable": "true"
}

Installare le dipendenze per un sistema di produzione

Se non abbiamo accesso via ssh al nostro server di produzione non possiamo richiamare l'eseguibile composer per l'installazione e quindi non possiamo essere sicuri che le dipendenze che verranno installate saranno compatibili una volta caricate sul server, ad esempio perché la versione dell'interprete PHP è diversa dal nostro ambiente di sviluppo o perché sono presenti solo alcune estensioni. In questi casi infatti in genere si lancia l'eseguibile per l'installazione delle dipendenze nel nostro ambiente di sviluppo per poi caricare tutti i file compresa la directory vendor via FTP.

Esiste una proprietà del file di configurazione che ci permette di far credere all'eseguibile di trovarsi sul nostro sistema di produzione: platform dentro la proprietà config. In questo modo è possibile indicare la versione di PHP e addirittura delle estensioni, tutte informazioni reperibili con la funzione phpinfo(). Lo snippet di codice in questo caso diventa simile al seguente:

{
    ...
    "config": {
        ...
        "platform": {
            "php": "5.5",
            "ext-gd": "2.0"
        }
    }
}