Installare Composer su Windows, macOS e Linux: guida completa

Composer è il gestore di dipendenze di PHP. Installa le librerie di cui un progetto ha bisogno, risolve le loro dipendenze, blocca le versioni e genera l’autoload delle classi. Questo tutorial copre l’installazione sui tre sistemi, i comandi di tutti i giorni e gli errori che costano tempo. Verificato con Composer 2.10.3 su PHP 8.5.10.

Installare, verificando la firma

La ricetta che si trova ovunque è curl -sS https://getcomposer.org/installer | php. Esegue direttamente un file scaricato, senza controllare niente. La procedura ufficiale confronta l’impronta SHA-384 dello script con quella pubblicata dal progetto prima di lanciarlo.

#!/usr/bin/env bash
set -euo pipefail

ATTENDU=$(curl -sS https://composer.github.io/installer.sig)
curl -sS https://getcomposer.org/installer -o composer-setup.php
CALCULE=$(php -r "echo hash_file('sha384', 'composer-setup.php');")

if [ "$ATTENDU" != "$CALCULE" ]; then
    >&2 echo 'ERREUR : signature invalide, ne pas exécuter'
    rm composer-setup.php
    exit 1
fi

php composer-setup.php --quiet --install-dir=/usr/local/bin --filename=composer
rm composer-setup.php
composer --version

Composer version 2.10.3 2026-08-27 13:34:23

Le due impronte coincidono: il programma di installazione è autentico. Sono trenta secondi di lavoro in più contro l’esecuzione di uno script arbitrario con i diritti del tuo account.

Windows

Scarica ed esegui Composer-Setup.exe. Il programma di installazione rileva PHP, configura il PATH e si aggiorna da solo.

macOS

Lo script qui sopra funziona così com’è. Con Homebrew:

brew install composer

Una precisazione sui tutorial più vecchi: chiedono di aggiungere un alias in ~/.bash_profile. Da macOS Catalina (2019) la shell predefinita è zsh, e quel file non viene più letto. Il file da modificare è ~/.zshrc. E l’alias non serve comunque, se composer.phar è installato in /usr/local/bin/composer con il permesso di esecuzione.

Linux

sudo apt-get update
sudo apt-get install -y php-cli unzip curl
# poi lo script di verifica qui sopra

Il pacchetto composer dei repository Debian e Ubuntu è spesso indietro di diverse versioni. Meglio il programma di installazione ufficiale.

Avviare un progetto

mkdir mon-projet && cd mon-projet
composer init          # questionario interattivo
composer require monolog/monolog

Questo comando crea o aggiorna tre cose:

• composer.json, quello che chiedi. Va versionato.
• composer.lock, le versioni esatte installate, al commit preciso. Va versionato anche lui: è ciò che garantisce che tutta la squadra e la produzione abbiano lo stesso codice.
• vendor/, i file scaricati. Non va versionato, mettilo nel .gitignore.

/vendor/

install o update: la distinzione che conta

Lanciare composer update su un server di produzione installa versioni che nessuno ha testato. È la causa di un numero notevole di messe in produzione fallite.

# Aggiornare un solo pacchetto
composer update monolog/monolog

# Aggiornare un pacchetto e le sue dipendenze
composer update monolog/monolog --with-dependencies

# Vedere che cosa cambierebbe, senza cambiare niente
composer update --dry-run

I vincoli di versione

{
    "require": {
        "php": ">=8.2",
        "monolog/monolog": "^3.5",
        "symfony/console": "~6.4.0",
        "vendor/paquet": "2.1.3"
    }
}

Il ^ è la scelta predefinita giusta: consente le correzioni e le aggiunte, rifiuta le rotture di compatibilità. Fissare una versione esatta sembra prudente, ma blocca le patch di sicurezza.

Dichiarare la versione di PHP in require evita di installare un pacchetto che non girerà sul server. E se la macchina di sviluppo non ha la stessa versione della produzione, config.platform fa risolvere le dipendenze per la versione di destinazione:

{
    "config": {
        "platform": {
            "php": "8.4.0"
        }
    }
}

L’autoload

È la funzione più utile di Composer, e quella che si scopre per ultima. Lo standard PSR-4 associa un prefisso di namespace a una cartella.

{
    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "App\\Tests\\": "tests/"
        },
        "files": [
            "src/fonctions.php"
        ]
    }
}

I backslash vanno raddoppiati in un file JSON. È l’errore più frequente su questo file, ed è silenzioso fino al momento in cui Composer si rifiuta di leggerlo:

"App\": "src/"     -> JSON INVALIDE (l'antislash échappe le guillemet)
"App\\": "src/"    -> correct

Con questa configurazione la classe App\Personnages\Guerrier viene cercata in src/Personnages/Guerrier.php. Il percorso deriva dal nome: backslash nel codice, barre nelle cartelle.

<?php

declare(strict_types=1);

namespace App\Personnages;   // backslash, mai barre

final class Guerrier
{
    // …
}

<?php

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

use App\Personnages\Guerrier;

$conan = new Guerrier();

Dopo ogni modifica alla sezione autoload:

composer dump-autoload

Nessun commento in composer.json

JSON non ha commenti. Un // infilato nel file lo rende illeggibile:

In JsonFile.php line 398:
  "./composer.json" does not contain valid JSON
  Lexical error on line 5. Comments are not allowed.

Il comando composer validate controlla il file prima che il problema salti fuori altrove.

Controllare le vulnerabilità

composer audit confronta i pacchetti installati con il database di avvisi di sicurezza dell’ecosistema PHP.

composer audit

No security vulnerability advisories found.

È un comando da mettere nell’integrazione continua, dopo composer install: senza cartella vendor/ risponde solo « No installed packages found ». Restituisce un codice di uscita diverso da zero quando un avviso riguarda il progetto.

Individuare i pacchetti abbandonati

Composer segnala i pacchetti il cui autore ne ha dichiarato l’abbandono, al momento dell’installazione. L’avviso passa spesso inosservato nel flusso dell’output:

Package facebook/php-sdk is abandoned, you should avoid using it.
Use facebook/graph-sdk instead.

Un pacchetto abbandonato non riceve più correzioni, comprese quelle di sicurezza. Su questo messaggio vale la pena fermarsi, invece di lasciarlo scorrere.

Andare in produzione

composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

E una regola che vale la pena ripetere: non lanciare mai Composer con sudo. I file di vendor/ apparterrebbero a root, il server web non riuscirebbe più a leggerli, e la cache di Composer finirebbe in /root/.composer. Se l’installazione globale chiede sudo, è solo per scrivere in /usr/local/bin, una volta sola.

I comandi di tutti i giorni

# Che cosa è installato
composer show
composer show monolog/monolog        # dettaglio di un pacchetto
composer show --tree                 # albero delle dipendenze

# Che cosa si potrebbe aggiornare
composer outdated
composer outdated --direct           # solo le tue dipendenze dirette

# Perché questo pacchetto è qui?
composer why psr/log
composer why-not symfony/console 7.0 # che cosa blocca un passaggio di versione

# Rimuovere un pacchetto
composer remove monolog/monolog

# Riparare un'installazione dubbia
rm -rf vendor composer.lock && composer install

Due flag di Composer 1 girano ancora nei tutorial. composer show -i restituisce ormai un avviso, dato che i pacchetti installati sono l’output predefinito:

You are using the deprecated option "installed". Only installed packages are
shown by default now. The --all option can be used to show all packages.

E composer --V non esiste, si scrive -V oppure --version:

The "--V" option does not exist.

Sorgenti di pacchetti particolari

{
    "require": {
        "moi/mon-paquet": "dev-main"
    },
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/moi/mon-paquet"
        }
    ]
}

Per sviluppare un pacchetto in parallelo al progetto che lo usa, il repository di tipo path crea un collegamento simbolico: le modifiche si vedono subito, senza reinstallare niente.

{
    "repositories": [
        {
            "type": "path",
            "url": "../mes-paquets/mon-paquet",
            "options": {
                "symlink": true
            }
        }
    ]
}

Gli script

{
    "scripts": {
        "test": "phpunit",
        "analyse": "phpstan analyse src --level=8",
        "verifier": [
            "@analyse",
            "@test"
        ]
    }
}

composer verifier

Così non devi ricordare i percorsi verso vendor/bin, e tutta la squadra ha gli stessi comandi.

Da ricordare

• Verificare l’impronta del programma di installazione prima di eseguirlo.
• Versionare composer.lock, ignorare vendor/.
• install in produzione, update solo in sviluppo.
• Raddoppiare i backslash in composer.json, nessun commento.
• composer audit nell’integrazione continua, mai sudo.

Composer è la porta d’ingresso della maggior parte delle librerie: PHPMailer per inviare un’email e Ratchet per un server WebSocket si installano entrambi con composer require.

Per continuare: le buone pratiche di Composer, le basi della programmazione a oggetti in PHP per sfruttare l’autoload, e l’hub Sviluppo web.