Come installare PHP Composer su Debian 12 Bookworm

Composer su Debian 12: scelta pratica e punto di partenza

Su Debian 12 Bookworm hai due strade sensate per portare Composer in macchina: usare il pacchetto distribuito da Debian oppure installare il binario ufficiale di Composer verificandone l’integrità. La scelta non è cosmetica. Il pacchetto del sistema è più comodo per gestione centralizzata e aggiornamenti via APT; il binario ufficiale spesso è più allineato alla release corrente di Composer e riduce il ritardo tra upstream e repository.

Se stai preparando un server applicativo, il criterio giusto è semplice: vuoi stabilità operativa e manutenzione lineare oppure vuoi la versione più recente con controllo esplicito del binario. In entrambi i casi, prima verifica che PHP sia presente e che il sistema abbia i prerequisiti minimi per eseguire Composer senza intoppi.

Prerequisiti reali: PHP, estensioni e strumenti base

Composer non è un’applicazione autonoma: è un gestore dipendenze per PHP e si appoggia a un interprete funzionante. Su Bookworm, il primo controllo da fare è la presenza di PHP CLI e di alcune estensioni che nella pratica servono quasi sempre nei progetti moderni.

Verifica lo stato con questi comandi:

php -v
php -m | egrep 'curl|mbstring|openssl|zip|xml|intl'
apt-cache policy php-cli curl unzip git

Se `php -v` fallisce, non ha senso andare avanti: installa prima PHP. Se mancano estensioni come `curl`, `zip`, `mbstring` o `intl`, Composer può anche partire, ma molti progetti poi si fermano in fase di installazione delle dipendenze. Il punto non è farlo “accendere”, ma evitare un ambiente mezzo configurato che ti farà perdere tempo al primo `composer install`.

Su Debian 12, per un setup tipico puoi aggiungere i pacchetti più comuni così:

sudo apt update
sudo apt install php-cli php-curl php-mbstring php-xml php-zip unzip git curl

Non tutte le estensioni sono obbligatorie in assoluto, ma questo set copre gran parte dei casi reali. Se il tuo stack usa framework o librerie con requisiti specifici, controlla i vincoli del progetto prima di procedere.

Installazione via APT: quando conviene davvero

La via più semplice, e spesso la più pulita per un server che vuoi mantenere con strumenti Debian, è installare Composer dai repository ufficiali:

sudo apt update
sudo apt install composer

Dopo l’installazione, controlla subito versione e path:

composer --version
which composer
composer diagnose

Con APT ottieni integrazione con il sistema, aggiornamenti coerenti con il resto del parco pacchetti e meno gestione manuale. Per molte macchine questa è la scelta corretta, soprattutto se il nodo non è un ambiente di sviluppo ma un host applicativo dove vuoi ridurre gli interventi ad hoc.

Il limite è noto: la versione in Debian può non essere la più recente. Se ti serve una release nuova per un bugfix o una feature specifica, il pacchetto distro può essere troppo conservativo. In quel caso ha senso passare al binario ufficiale, ma con verifica della firma e installazione ordinata.

Installazione ufficiale: binario verificato in /usr/local/bin

Se vuoi la versione upstream di Composer, installa il PHAR ufficiale e verifica l’hash prima di eseguirlo. Non è un dettaglio da puristi: è il minimo sindacale quando scarichi un eseguibile da Internet.

Il flusso corretto è questo:

1. scarichi l’installer;
2. verifichi la firma o l’hash pubblicato da Composer;
3. installi in un path di sistema come /usr/local/bin;
4. controlli che il binario risolva correttamente.

Ecco un esempio operativo con il metodo consigliato dal progetto Composer, usando il controllo dell’hash dell’installer:

cd /tmp
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
EXPECTED_CHECKSUM="$(curl -s https://composer.github.io/installer.sig)"
ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"
if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]; then
  echo 'ERROR: Invalid installer checksum'
  rm -f composer-setup.php
  exit 1
fi
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
rm -f composer-setup.php

Il risultato atteso è che `composer` sia eseguibile da qualsiasi shell e che la versione venga mostrata correttamente:

composer --version
/usr/local/bin/composer --version

Se il comando non viene trovato, il problema è quasi sempre nel path. Su una shell standard, `/usr/local/bin` deve stare prima di `/usr/bin`, ma conviene verificare senza dare nulla per scontato:

echo $PATH
command -v composer

Se `command -v composer` restituisce un path diverso da quello atteso, stai probabilmente usando una versione installata dal sistema o da uno strato precedente. È un punto importante nei server condivisi o nei container, dove possono coesistere più installazioni e creare confusione durante il troubleshooting.

Permessi, utenti e uso corretto in produzione

Composer non va eseguito come root per abitudine. Il problema non è solo teorico: durante l’installazione delle dipendenze, Composer può scrivere nella directory del progetto, generare cache e interagire con script post-install. Se lo lanci come root in un tree applicativo che poi dovrà essere gestito da un utente diverso, ti ritrovi con file proprietari sbagliati e permessi incoerenti.

La regola pratica è questa: installa Composer a livello di sistema, ma esegui i comandi del progetto con l’utente che gestisce il codice. Un caso tipico:

cd /var/www/app
sudo -u www-data composer install --no-dev --optimize-autoloader

Se il progetto è in una home di sviluppo, usa l’utente proprietario del repository. Se invece sei su un server web, allinea l’utente operativo con il modello di permessi della tua applicazione, senza allargare inutilmente i diritti.

Un controllo utile, spesso trascurato, è la cache di Composer. Puoi vedere dove scrive così:

composer config --global cache-dir
composer config --global home

Se la home globale punta a un path non scrivibile, i problemi emergono in modo intermittente: download lenti, cache non persistente, installazioni che falliscono senza una causa evidente. Meglio correggere subito il contesto utente che inseguire sintomi sparsi.

Verifica funzionale: non fermarti a composer --version

Una versione stampata a schermo non basta. Il controllo serio è una diagnosi completa e, meglio ancora, una prova su un progetto reale o su un repository di test.

Usa questi comandi per una verifica minima:

composer diagnose
composer about
php -r 'echo PHP_VERSION, PHP_EOL;'

`composer diagnose` è particolarmente utile perché intercetta problemi di rete, TLS, configurazione PHP e permessi. Se qualcosa non torna, è meglio leggerlo subito che scoprire il guasto durante un deploy.

Per un test più concreto, puoi creare un progetto temporaneo e vedere se risolve dipendenze e autoload senza errori:

mkdir -p /tmp/composer-test
cd /tmp/composer-test
composer init --no-interaction
composer require psr/log

Se qui fallisce, il problema non è Composer “in astratto”, ma una delle condizioni di contorno: DNS, proxy, CA bundle, estensioni PHP, permessi o rete in uscita. A quel punto il debug va fatto layer per layer, non con tentativi casuali.

Aggiornamento, rimozione e convivenza con il sistema

Con il pacchetto Debian, l’aggiornamento passa normalmente da APT:

sudo apt update
sudo apt upgrade composer

Con l’installer ufficiale, l’aggiornamento è altrettanto semplice ma va rifatto esplicitamente. In pratica, ripeti la procedura di download e installazione del PHAR. Non c’è una magia nascosta: stai sostituendo un binario con un altro.

Se vuoi controllare quale installazione stai usando, confronta questi elementi:

which composer
ls -l /usr/bin/composer /usr/local/bin/composer 2>/dev/null
dpkg -S $(command -v composer) 2>/dev/null

Questo ti evita il classico caso in cui il pacchetto Debian è installato ma il sistema sta eseguendo il binario manuale in `/usr/local/bin`, o viceversa. In ambienti amministrati da più persone è una delle cause più frequenti di “a me funziona, a te no”.

Se devi rimuovere Composer, fallo in modo coerente con il metodo usato per installarlo. Con APT:

sudo apt remove composer

Con il binario ufficiale, elimina il file installato, tipicamente:

sudo rm -f /usr/local/bin/composer

Se hai dubbi su quale copia sia attiva, non fare pulizie a caso: prima risolvi il path e identifica il binario realmente in uso. È il modo più rapido per evitare di lasciare in giro installazioni duplicate.

Errori tipici su Debian 12 e come leggerli

Quando Composer non parte, i messaggi d’errore di solito sono più utili di quanto sembri. Il problema è che spesso si legge solo la prima riga e si salta la causa vera.

Se vedi errori su TLS o certificati, controlla il bundle CA e la configurazione di PHP:

php -i | grep -i 'curl.cainfo\|openssl.cafile'
apt install ca-certificates

Se il problema è la rete, verifica risoluzione DNS e raggiungibilità:

getent hosts getcomposer.org
curl -I https://getcomposer.org/

Se invece compare un errore di memoria o di processi che vengono terminati, il problema non è Composer in sé ma i limiti della macchina. In quel caso, prima osserva `dmesg`, `journalctl` e l’uso RAM/swap, poi decidi se intervenire sul processo o sull’host.

Per gli ambienti con proxy aziendale, ricordati che Composer eredita variabili e configurazioni di rete. Un check utile è:

env | grep -i proxy
composer config -g --list

Se il proxy è richiesto ma non configurato, Composer può sembrare “rotto” mentre in realtà sta solo provando a uscire su Internet senza la strada giusta.

Scelta consigliata in pratica

Se il server è un nodo Debian 12 standard, la scelta più lineare è installare Composer da APT e verificare subito con `composer diagnose`. Se invece ti serve una release più fresca o vuoi allinearti esattamente all’upstream, usa l’installer ufficiale con controllo dell’hash e posiziona il binario in `/usr/local/bin`.

In entrambi i casi il vero lavoro non è “installare Composer”, ma portare il sistema in uno stato coerente: PHP CLI presente, estensioni corrette, permessi puliti, path senza ambiguità e rete funzionante. Se questi pezzi sono a posto, Composer diventa uno strumento affidabile; se li ignori, diventa solo il punto dove emerge un problema già presente altrove.

Assunzione operativa: Debian 12 Bookworm recente, PHP già disponibile o installabile dai repository ufficiali, nessun vincolo speciale di hardening o proxy non documentato.