Composer: suggerimenti per l'uso

Installazione

Composer è un file .phar eseguibile, che si scarica e si installa nel seguente modo:

Windows

Utilizzare l'installer ufficiale Composer-Setup.exe.

Linux, macOS

Bastano 4 comandi, che possono essere copiati da questa pagina.

Inoltre, inserendolo in una cartella che si trova nel PATH di sistema, Composer diventa accessibile globalmente:

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

Utilizzo nel progetto

Per poter iniziare a usare Composer nel nostro progetto, è necessario solo il file composer.json. Questo descrive le dipendenze del nostro progetto e può anche contenere altri metadati. Un composer.json di base può quindi apparire così:

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

Qui specifichiamo che la nostra applicazione (o libreria) richiede il pacchetto nette/database (il nome del pacchetto è composto dal nome dell'organizzazione e dal nome del progetto) e richiede una versione che corrisponda alla condizione ^3.0 (cioè la versione più recente 3.x.x).

Quindi, con il file composer.json nella root del progetto, si esegue l'installazione:

composer update

Composer scaricherà Nette Database nella cartella vendor/. Inoltre, creerà il file composer.lock, che contiene informazioni su quali versioni esatte delle librerie ha installato.

Composer genererà il file vendor/autoload.php, che possiamo semplicemente includere e iniziare a usare le librerie senza alcun lavoro aggiuntivo:

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

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

Aggiornamento dei pacchetti alle versioni più recenti

L'aggiornamento delle librerie utilizzate alle versioni più recenti secondo le condizioni definite in composer.json è gestito dal comando composer update. Ad esempio, per la dipendenza "nette/database": "^3.0" installerà la versione più recente 3.x.x, ma non la versione 4.

Per aggiornare le condizioni nel file composer.json, ad esempio a "nette/database": "^4.1", in modo da poter installare la versione più recente, utilizzare il comando composer require nette/database.

Per aggiornare tutti i pacchetti Nette utilizzati, sarebbe necessario elencarli tutti nella riga di comando, ad esempio:

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

Il che è poco pratico. Utilizzare quindi il semplice script Composer Frontline, che lo farà al posto vostro:

php composer-frontline.php

Creazione di un nuovo progetto

È possibile creare un nuovo progetto Nette con un solo comando:

composer create-project nette/web-project nome-progetto

Come nome-progetto inserire il nome della directory per il proprio progetto e confermare. Composer scaricherà il repository nette/web-project da GitHub, che contiene già il file composer.json, e subito dopo Nette Framework. A questo punto, dovrebbe essere sufficiente solo impostare i permessi delle directory di scrittura sulle cartelle temp/ e log/ e il progetto dovrebbe prendere vita.

Se si sa su quale versione di PHP verrà ospitato il progetto, non dimenticate di impostarla.

Versione PHP

Composer installa sempre le versioni dei pacchetti compatibili con la versione di PHP attualmente in uso (meglio dire con la versione di PHP utilizzata nella riga di comando durante l'esecuzione di Composer). Che però probabilmente non è la stessa versione utilizzata dall'ambiente di hosting. Pertanto, è molto importante aggiungere al file composer.json l'informazione sulla versione di PHP nell'ambiente di hosting. Successivamente verranno installate solo le versioni dei pacchetti compatibili con l'ambiente di hosting.

Per specificare che il progetto verrà eseguito, ad esempio, su PHP 8.2.3, utilizzare 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 viene specificato anche in un altro punto del file, nella sezione require. Mentre il primo numero determina per quale versione verranno installati i pacchetti, il secondo numero indica per quale versione è scritta l'applicazione stessa. E in base ad esso, ad esempio, PhpStorm imposta il PHP language level. (Ovviamente non ha senso che queste versioni differiscano, quindi la doppia scrittura è un'imprecisione.) Questa versione si imposta con il comando:

composer require php 8.2.3 --no-update

O direttamente nel file composer.json:

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

Ignorare la versione di PHP

I pacchetti di solito specificano sia la versione minima di PHP con cui sono compatibili, sia la più alta con cui sono testati. Se si intende utilizzare una versione di PHP ancora più recente, ad esempio per motivi di test, Composer rifiuterà di installare tale pacchetto. La soluzione è l'opzione --ignore-platform-req=php+, che fa sì che Composer ignori i limiti superiori della versione PHP richiesta.

Messaggi falsi

Durante l'aggiornamento dei pacchetti o la modifica dei numeri di versione, capita che si verifichi un conflitto. Un pacchetto ha requisiti che sono in conflitto con un altro e simili. Composer però a volte stampa falsi messaggi. Segnala un conflitto che in realtà non esiste. In tal caso, può essere utile eliminare il file composer.lock e riprovare.

Se il messaggio di errore persiste, allora è reale ed è necessario interpretarlo per capire cosa e come modificare.

Packagist.org – repository centrale

Packagist è il repository principale in cui Composer cerca di trovare i pacchetti, a meno che non gli diciamo diversamente. Possiamo pubblicare qui anche i nostri pacchetti.

Cosa succede se non vogliamo usare il repository centrale?

Se abbiamo applicazioni interne all'azienda, che semplicemente non possiamo ospitare pubblicamente, allora creiamo per esse un repository aziendale.

Maggiori informazioni sul tema dei repository nella documentazione ufficiale.

Autoloading

Una caratteristica fondamentale di Composer è che fornisce l'autoloading per tutte le classi da esso installate, che si avvia includendo il file vendor/autoload.php.

Tuttavia, è possibile utilizzare Composer anche per caricare altre classi al di fuori della cartella vendor. La prima opzione è far sì che Composer esamini le cartelle e le sottocartelle definite, trovi tutte le classi e le includa nell'autoloader. Ciò si ottiene impostando autoload > classmap in composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      # include la cartella src/ e le sue sottocartelle
		]
	}
}

Successivamente, è necessario eseguire il comando composer dumpautoload ad ogni modifica e far rigenerare le tabelle di autoloading. Questo è estremamente scomodo ed è molto meglio affidare questo compito a RobotLoader, che esegue la stessa attività automaticamente in background e molto più velocemente.

La seconda opzione è rispettare PSR-4. In parole povere, si tratta di un sistema in cui i namespace e i nomi delle classi corrispondono alla struttura delle directory e ai nomi dei file, quindi ad esempio App\Core\RouterFactory sarà nel file /path/to/App/Core/RouterFactory.php. Esempio di configurazione:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # il namespace App\ è nella directory app/
		}
	}
}

Come configurare esattamente il comportamento è descritto nella documentazione di Composer.

Testare nuove versioni

Si desidera testare una nuova versione di sviluppo di un pacchetto. Come fare? Innanzitutto, aggiungere al file composer.json questa coppia di opzioni, che permetterà di installare versioni di sviluppo dei pacchetti, ma ricorrerà ad essa solo nel caso in cui non esista alcuna combinazione di versioni stabili che soddisfi i requisiti:

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

Inoltre, consigliamo di eliminare il file composer.lock, a volte infatti Composer rifiuta inspiegabilmente l'installazione e questo risolve il problema.

Supponiamo che si tratti del pacchetto nette/utils e che la nuova versione abbia il numero 4.0. Si installa con il comando:

composer require nette/utils:4.0.x-dev

Oppure è possibile installare una versione specifica, ad esempio 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Se però un altro pacchetto dipende dalla libreria ed è bloccato a una versione precedente (es. ^3.1), allora è ideale aggiornare il pacchetto affinché funzioni con la nuova versione. Se però si vuole solo aggirare la limitazione e costringere Composer a installare la versione di sviluppo e fingere che sia una versione precedente (es. 3.1.6), si può usare la parola chiave as:

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

Chiamata di comandi

Tramite Composer è possibile chiamare comandi e script personalizzati pre-preparati, come se fossero comandi nativi di Composer. Per gli script che si trovano nella cartella vendor/bin, non è necessario specificare questa cartella.

Come esempio, definiamo nel file composer.json uno script che, utilizzando Nette Tester, esegue i test:

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

Eseguiamo quindi i test con composer tester. Possiamo chiamare il comando anche se non siamo nella cartella principale del progetto, ma in una sottodirectory.

Invia un ringraziamento

Vi mostreremo un trucco che farà piacere agli autori open source. In modo semplice, si darà una stella su GitHub alle librerie che il vostro progetto utilizza. Basta installare la libreria symfony/thanks:

composer global require symfony/thanks

E poi eseguire:

composer thanks

Provate!

Configurazione

Composer è strettamente legato allo strumento di versioning Git. Se non è installato, è necessario indicare a Composer di non usarlo:

composer -g config preferred-install dist