Consigli per l'uso di Composer
******************************

<div class=perex>

Composer è uno strumento per gestire le dipendenze in PHP. Permette di dichiarare le librerie da cui il vostro progetto dipende e le installa e aggiorna per voi. Impareremo:

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

</div>


Installazione
=============

Composer è un file eseguibile `.phar` che scaricate e installate così.


Windows
-------

Usate l'installer ufficiale [Composer-Setup.exe|https://getcomposer.org/Composer-Setup.exe].


Linux, macOS
------------

Vi bastano 4 comandi, che potete copiare da [questa pagina |https://getcomposer.org/download/].

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

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


Uso nel progetto
================

Per iniziare a usare Composer nel vostro progetto vi basta il file `composer.json`. Questo file descrive le dipendenze del vostro progetto e può contenere anche altri metadati. Il `composer.json` più semplice può apparire così:

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

Diciamo qui che la nostra applicazione (o libreria) richiede il pacchetto `nette/database` (il nome del pacchetto è composto dal nome del vendor e dal nome del progetto) e che vuole una versione che corrisponda al vincolo `^3.0` (cioè l'ultima versione 3).

Con il file `composer.json` nella radice del progetto lanciamo quindi:

```shell
composer update
```

Composer scaricherà Nette Database nella directory `vendor/`. Crea anche il file `composer.lock`, che contiene l'informazione su quali versioni esatte delle librerie ha installato.

Composer genera il file `vendor/autoload.php`. Potete semplicemente includere questo file e iniziare a usare le classi delle librerie senza altro lavoro:

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

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


Aggiornare i pacchetti alle ultime versioni
===========================================

Per aggiornare le librerie usate alle ultime versioni secondo i vincoli definiti in `composer.json` serve il comando `composer update`. Per esempio con la dipendenza `"nette/database": "^3.0"` installerà l'ultima versione 3.x.x, ma non la versione 4.

Per aggiornare i vincoli nel file `composer.json`, per esempio a `"nette/database": "^4.1"`, e permettere così l'installazione dell'ultima versione, serve il comando `composer require nette/database`.

Per aggiornare tutti i pacchetti Nette usati bisognerebbe elencarli tutti sulla riga di comando, per esempio:

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

Il che è poco pratico. Usate quindi il semplice script "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff che lo fa per voi:

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


Creare un nuovo progetto
========================

Un nuovo progetto Nette lo create con un unico comando:

```shell
composer create-project nette/web-project nome-del-progetto
```

Al posto di `nome-del-progetto` inserite il nome della directory per il vostro progetto ed eseguite il comando. Composer scaricherà da GitHub il repository `nette/web-project`, che contiene già il file `composer.json`, e subito dopo installerà il Nette Framework stesso. Non resta che [impostare i permessi delle directory |nette:troubleshooting#Impostazione dei permessi delle directory] `temp/` e `log/` e il progetto dovrebbe essere vivo.

Se sapete su quale versione di PHP sarà ospitato il progetto, non dimenticate di [impostarla |#Versione di PHP].


Versione di PHP
===============

Composer installa sempre le versioni dei pacchetti compatibili con la versione di PHP che state usando (più precisamente con la versione di PHP usata sulla riga di comando quando lanciate Composer). Che però probabilmente non è la stessa versione usata dal vostro hosting. Per questo è molto importante aggiungere al file `composer.json` l'informazione sulla versione di PHP sull'hosting. Da quel momento verranno installate solo versioni dei pacchetti compatibili con l'hosting.

Per impostare per esempio che il progetto girerà su PHP 8.2.3 usate il comando:

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

Così la versione verrà scritta nel file `composer.json`:

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

Il numero di versione di PHP si indica però nel file anche in un altro punto, nella sezione `require`. Mentre il primo numero determina per quale versione vengono installati i pacchetti, il secondo dice per quale versione è scritta l'applicazione stessa. In base a esso, per esempio, PhpStorm imposta il *PHP language level*. (Naturalmente non ha senso che queste versioni differiscano, quindi la doppia indicazione è una svista.) Questa versione la impostate 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
===========================

I pacchetti indicano di solito sia la versione minima di PHP con cui sono compatibili, sia la versione massima con cui sono stati testati. Se avete intenzione di usare una versione di PHP ancora più recente, magari per fare delle prove, Composer si rifiuterà di installare un pacchetto del genere. La soluzione è l'opzione `--ignore-platform-req=php+`, che fa ignorare a Composer i limiti superiori della versione di PHP richiesta.


Segnalazioni false
==================

Aggiornando i pacchetti o cambiando i numeri di versione capitano dei conflitti. Un pacchetto ha requisiti che sono in conflitto con un altro e così via. Composer però a volte emette segnalazioni false. Segnala un conflitto che in realtà non esiste. In un caso del genere aiuta cancellare il file `composer.lock` e riprovare.

Se il messaggio di errore persiste, allora è serio e bisogna leggerlo per capire cosa e come modificare.


Packagist.org - repository globale
==================================

[Packagist |https://packagist.org] è il repository principale in cui Composer cerca i pacchetti per impostazione predefinita. Qui potete anche pubblicare i vostri pacchetti.


E se non volessimo il repository centrale
-----------------------------------------

Se abbiamo in azienda applicazioni o librerie interne che non possono essere ospitate pubblicamente, possiamo crearci i nostri repository.

Di più sui repository nella [documentazione ufficiale |https://getcomposer.org/doc/05-repositories.md#repositories].


Autoloading
===========

Una caratteristica fondamentale di Composer è che fornisce l'autoloading per tutte le classi che installa. Lo attivate includendo il file `vendor/autoload.php`.

Composer si può però usare anche per caricare altre classi al di fuori della directory `vendor/`. La prima possibilità è lasciare che Composer scandisca le directory e sottodirectory indicate, trovi tutte le classi e le includa nell'autoloader. Per ottenerlo impostate in `composer.json` `autoload > classmap`:

```js
{
	"autoload": {
		"classmap": [
			"src/",      # include la directory src/ e le sue sottodirectory
		]
	}
}
```

Dopo di che bisogna lanciare il comando `composer dumpautoload` a ogni modifica per rigenerare le tabelle di autoloading. Il che è estremamente scomodo. È molto meglio affidare questo compito a [RobotLoader|robot-loader:], che svolge la stessa attività automaticamente in background e molto più velocemente.

La seconda possibilità è rispettare lo standard [PSR-4 |https://www.php-fig.org/psr/psr-4/]. In parole semplici, è un sistema in cui i namespace e i nomi delle classi corrispondono alla struttura delle directory e ai nomi dei file, per esempio `App\Core\RouterFactory` si troverà nel file `/percorso/verso/App/Core/RouterFactory.php`. Esempio di configurazione:

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

Come configurare questo comportamento lo trovate nella [documentazione di Composer |https://getcomposer.org/doc/04-schema.md#psr-4].


Provare le versioni nuove
=========================

Volete provare una nuova versione di sviluppo di un pacchetto? Ecco come. Prima di tutto aggiungete al file `composer.json` questa coppia di opzioni, che permettono di installare versioni di sviluppo, ma Composer vi ricorrerà solo se nessuna combinazione di versioni stabili soddisfa i requisiti:

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

Consigliamo inoltre di cancellare il file `composer.lock`, perché a volte Composer rifiuta inspiegabilmente l'installazione e questo risolve il problema.

Diciamo che il pacchetto sia `nette/utils` e la nuova versione la 4.0. La installate con il comando:

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

Oppure potete installare una versione concreta, per esempio la 4.0.0-RC2:

```shell
composer require nette/utils:4.0.0-RC2
```

Se però un altro pacchetto dipende dalla libreria ed è vincolato a una versione più vecchia (per esempio `^3.1`), la soluzione ideale è aggiornare quel pacchetto perché funzioni con la nuova versione. Se però volete solo aggirare la limitazione e costringere Composer a installare la versione di sviluppo facendo finta che sia una versione più vecchia (per esempio la 3.1.6), potete usare la parola chiave `as`:

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


Richiamare comandi
==================

Tramite Composer potete richiamare comandi e script vostri predefiniti come se fossero comandi nativi di Composer. Per gli script che si trovano nella directory `vendor/bin` non serve indicare questo percorso.

Come esempio definiamo in `composer.json` uno script che usa [Nette Tester |tester:] per eseguire i test:

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

I test li lanciamo poi con `composer tester`. Potete richiamare il comando anche se non vi trovate nella directory radice del progetto, ma in una delle sue sottodirectory.


Mandate un grazie
=================

Vi mostriamo un trucco con cui farete piacere agli autori open source. In modo semplice date su GitHub una stella alle librerie che il vostro progetto usa. Basta installare la libreria `symfony/thanks`:

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

E poi lanciare:

```shell
composer thanks
```

Provate!


Configurazione
==============

Composer è strettamente integrato con lo strumento di versionamento [Git |https://git-scm.com]. Se non avete Git installato, bisogna dire a Composer di non usarlo:

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