Suggerimenti per l'uso di Composer

Installazione

Composer è un file eseguibile .phar che si scarica e si installa come segue.

Windows

Utilizzare il programma di installazione ufficiale Composer-Setup.exe.

Linux, macOS

Tutto ciò di cui avete bisogno sono 4 comandi, che potete copiare da questa pagina.

Inoltre, copiando nella cartella PATH del sistema, Composer diventa accessibile a livello globale:

$ mv ./composer.phar ~/bin/composer # or /usr/local/bin/composer

Utilizzo nel progetto

Per iniziare a usare Composer nel vostro progetto, tutto ciò che vi serve è un file composer.json. Questo file descrive le dipendenze del progetto e può contenere anche altri metadati. Il più semplice composer.json può essere simile a questo:

{
	"require": {
		"nette/database": "^3.0"
	}
}

Stiamo dicendo che la nostra applicazione (o libreria) dipende dal pacchetto nette/database (il nome del pacchetto è composto dal nome del fornitore e dal nome del progetto) e vuole la versione che corrisponde al vincolo di versione ^3.0.

Quindi, quando abbiamo il file composer.json nella radice del progetto ed eseguiamo:

composer update

Composer scaricherà il database Nette nella directory vendor. Crea anche un file composer.lock, che contiene informazioni sulle versioni delle librerie installate.

Composer genera un file vendor/autoload.php. Si può semplicemente includere questo file e iniziare a usare le classi fornite da queste librerie senza alcun lavoro aggiuntivo:

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

$db = new Nette\Database\Connection('sqlite::memory:');

Aggiornare i pacchetti alle ultime versioni

Per aggiornare tutti i pacchetti utilizzati all'ultima versione in base ai vincoli di versione definiti in composer.json, usare il comando composer update. Ad esempio, per la dipendenza "nette/database": "^3.0" verrà installata l'ultima versione 3.x.x, ma non la versione 4.

Per aggiornare i vincoli di versione nel file composer.json a "nette/database": "^4.1", per esempio, e consentire l'installazione dell'ultima versione, usare il comando composer require nette/database.

Per aggiornare tutti i pacchetti Nette utilizzati, è necessario elencarli tutti sulla riga di comando, ad es:

composer require nette/application nette/forms latte/latte tracy/tracy ...

Il che è poco pratico. Pertanto, si può utilizzare un semplice script Composer Frontline che lo farà per voi:

php composer-frontline.php

Creazione di un nuovo progetto

È possibile creare un nuovo progetto Nette eseguendo un semplice comando:

composer create-project nette/web-project name-of-the-project

Al posto di name-of-the-project si deve fornire il nome della directory del progetto ed eseguire il comando. Composer recupererà il repository nette/web-project da GitHub, che contiene già il file composer.json, e subito dopo installerà il framework Nette. L'unica cosa che resta da fare è controllare i permessi di scrittura sulle directory temp/ e log/ e il gioco è fatto.

Se si conosce la versione di PHP su cui verrà ospitato il progetto, assicurarsi di impostarla.

Versione PHP

Composer installa sempre le versioni dei pacchetti compatibili con la versione di PHP attualmente in uso (o meglio, la versione di PHP utilizzata dalla riga di comando quando si esegue Composer). Che probabilmente non è la stessa versione utilizzata dal vostro host web. Per questo motivo è molto importante aggiungere al file composer.json le informazioni sulla versione di PHP presente sul vostro hosting. In questo modo, verranno installate solo le versioni dei pacchetti compatibili con l'host.

Per esempio, per impostare il progetto in modo che venga eseguito su PHP 8.2.3, usare il comando:

composer config platform.php 8.2.3

In questo modo la versione viene scritta nel file composer.json:

{
	"config": {
		"platform": {
			"php": "8.2.3"
		}
	}
}

Tuttavia, il numero di versione di PHP è elencato anche altrove nel file, nella sezione require. Mentre il primo numero specifica la versione per la quale verranno installati i pacchetti, il secondo numero dice per quale versione è stata scritta l'applicazione stessa. (Naturalmente, non ha senso che queste versioni siano diverse, quindi la doppia indicazione è una ridondanza). La versione viene impostata con il comando:

composer require php 8.2.3 --no-update

Oppure direttamente nel file composer.json:

{
	"require": {
		"php": "8.2.3"
	}
}

Ignorare la versione di PHP

I pacchetti di solito specificano sia la versione più bassa di PHP con cui sono compatibili sia la versione più alta con cui sono stati testati. Se si prevede di usare una versione di PHP ancora più recente, magari a scopo di test, Composer si rifiuterà di installare tale pacchetto. La soluzione è usare l'opzione --ignore-platform-req=php+, che fa sì che Composer ignori i limiti superiori della versione PHP richiesta.

Rapporti falsi

Quando si aggiornano i pacchetti o si cambiano i numeri di versione, si verificano dei conflitti. Un pacchetto ha requisiti in conflitto con un altro e così via. Tuttavia, Composer a volte stampa dei falsi messaggi. Segnala un conflitto che in realtà non esiste. In questo caso, è utile cancellare il file composer.lock e riprovare.

Se il messaggio di errore persiste, allora è da intendersi seriamente e bisogna leggere da esso cosa modificare e come.

Packagist.org – Repository globale

Packagist è il principale repository di pacchetti, nel quale Composer cerca di cercare i pacchetti, se non gli viene detto altrimenti. È anche possibile pubblicare qui i propri pacchetti.

Cosa succede se non si vuole il repository centrale?

Se nella nostra azienda abbiamo applicazioni o librerie interne che non possono essere ospitate pubblicamente su Packagist, possiamo creare i nostri repository per questi progetti.

Maggiori informazioni sui repository nella documentazione ufficiale.

Caricamento automatico

Una caratteristica fondamentale di Composer è il caricamento automatico di tutte le classi installate, che si avvia includendo il file vendor/autoload.php.

Tuttavia, è anche possibile usare Composer per caricare altre classi al di fuori della cartella vendor. La prima opzione consiste nel lasciare che Composer analizzi le cartelle e le sottocartelle definite, trovi tutte le classi e le includa nel caricatore automatico. Per fare ciò, impostare autoload > classmap in composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      #  includes the src/ folder and its subfolders
		]
	}
}

Successivamente, è necessario eseguire il comando composer dumpautoload a ogni modifica e lasciare che le tabelle di autocaricamento si rigenerino. Questo è estremamente scomodo ed è molto meglio affidare questo compito a RobotLoader, che svolge la stessa attività automaticamente in background e molto più velocemente.

La seconda opzione consiste nel seguire PSR-4. In parole povere, si tratta di un sistema in cui gli spazi dei nomi e i nomi delle classi corrispondono alla struttura delle directory e ai nomi dei file, cioè App\Core\RouterFactory si trova nel file /path/to/App/Core/RouterFactory.php. Esempio di configurazione:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # the App\ namespace is in the app/ directory
		}
	}
}

Vedere la documentazione di Composer per sapere esattamente come configurare questo comportamento.

Testare le nuove versioni

Si vuole testare una nuova versione di sviluppo di un pacchetto. Come fare? Per prima cosa, aggiungete questa coppia di opzioni al file composer.json, che vi permetterà di installare le versioni di sviluppo dei pacchetti, ma lo farà solo se non esiste una combinazione di versioni stabili che soddisfi i requisiti:

{
	"minimum-stability": "dev",
	"prefer-stable": true,
}

Si consiglia anche di eliminare il file composer.lock, perché a volte Composer si rifiuta incomprensibilmente di installare e questo risolverà il problema.

Supponiamo che il pacchetto sia nette/utils e che la nuova versione sia la 4.0. Si installa con il comando:

composer require nette/utils:4.0.x-dev

Oppure si può installare una versione specifica, per esempio 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Se un altro pacchetto dipende dalla libreria ed è bloccato a una versione precedente (ad esempio ^3.1), è ideale aggiornare il pacchetto per farlo funzionare con la nuova versione. Tuttavia, se si vuole semplicemente aggirare la limitazione e forzare Composer a installare la versione di sviluppo e fingere che sia una versione precedente (ad esempio, 3.1.6), si può usare la parola chiave as:

composer require nette/utils "4.0.x-dev as 3.1.6"

Comandi di chiamata

È possibile richiamare i propri comandi e script personalizzati attraverso Composer come se fossero comandi nativi di Composer. Per gli script che si trovano nella cartella vendor/bin non è necessario specificare questa cartella.

A titolo di esempio, definiamo uno script nel file composer.json che utilizza Nette Tester per eseguire i test:

{
	"scripts": {
		"tester": "tester tests -s"
	}
}

Eseguiamo quindi i test con composer tester. Possiamo richiamare il comando anche se non ci troviamo nella cartella principale del progetto, ma in una sottocartella.

Inviare Grazie

Vi mostriamo un trucco che renderà felici gli autori open source. Potete facilmente assegnare una stella su GitHub alle librerie utilizzate dal vostro progetto. Basta installare la libreria symfony/thanks:

composer global require symfony/thanks

E poi eseguire:

composer thanks

Provate!

Configurazione

Composer è strettamente integrato con lo strumento di controllo di versione Git. Se non si usa Git, è necessario comunicarlo a Composer:

composer -g config preferred-install dist