Suggerimenti per l'uso di Composer
**********************************

<div class=perex>

Composer è uno strumento per la gestione delle dipendenze in PHP. Permette di dichiarare le librerie da cui dipende il progetto e le installerà e aggiornerà per voi. Impareremo:

- come installare Composer
- usarlo in un progetto nuovo o esistente

</div>


Installazione .[#toc-installation]
==================================

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


Windows .[#toc-windows]
-----------------------

Utilizzare il programma di installazione ufficiale [Composer-Setup.exe |https://getcomposer.org/Composer-Setup.exe].


Linux, macOS .[#toc-linux-macos]
--------------------------------

Tutto ciò di cui avete bisogno sono 4 comandi, che potete copiare da [questa pagina |https://getcomposer.org/download/].

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

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


Utilizzo nel progetto .[#toc-use-in-project]
============================================

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:

```js
{
	"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:

```shell
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:

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

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


Aggiornare i pacchetti alle ultime versioni .[#toc-update-packages-to-the-latest-versions]
==========================================================================================

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:

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

Il che è poco pratico. Pertanto, si può utilizzare un semplice script "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff che lo farà per voi:

```shell
php composer-frontline.php
```


Creazione di un nuovo progetto .[#toc-creating-new-project]
===========================================================

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

```shell
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 |nette:troubleshooting#setting-directory-permissions] 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 |#PHP Version].


Versione PHP .[#toc-php-version]
================================

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:

```shell
composer config platform.php 8.2.3
```

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

```js
{
	"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:

```shell
composer require php 8.2.3 --no-update
```

Oppure direttamente nel file `composer.json`:

```js
{
	"require": {
		"php": "8.2.3"
	}
}
```


Ignorare la versione di PHP .[#toc-ignoring-php-version]
========================================================

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 .[#toc-false-reports]
====================================

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 .[#toc-packagist-org-global-repository]
==========================================================================

[Packagist |https://packagist.org] è 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? .[#toc-what-if-we-don-t-want-the-central-repository]
---------------------------------------------------------------------------------------------------------

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 |https://getcomposer.org/doc/05-repositories.md#repositories].


Caricamento automatico .[#toc-autoloading]
==========================================

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`:

```js
{
	"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 |robot-loader:], che svolge la stessa attività automaticamente in background e molto più velocemente.

La seconda opzione consiste nel seguire [PSR-4 |https://www.php-fig.org/psr/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:

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

Vedere la [documentazione di Composer |https://getcomposer.org/doc/04-schema.md#psr-4] per sapere esattamente come configurare questo comportamento.


Testare le nuove versioni .[#toc-testing-new-versions]
======================================================

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:

```js
{
	"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:

```shell
composer require nette/utils:4.0.x-dev
```

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

```shell
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`:

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


Comandi di chiamata .[#toc-calling-commands]
============================================

È 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 |tester:] per eseguire i test:

```js
{
	"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 .[#toc-send-thanks]
==================================

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`:

```shell
composer global require symfony/thanks
```

E poi eseguire:

```shell
composer thanks
```

Provate!


Configurazione .[#toc-configuration]
====================================

Composer è strettamente integrato con lo strumento di controllo di versione [Git |https://git-scm.com]. Se non si usa Git, è necessario comunicarlo a Composer:

```shell
composer -g config preferred-install dist
```

{{sitename: Migliori pratiche}}