Installare PHP 8.x su Debian 12: guida completa

PHP 8.x su Debian 12: scelta del ramo e impatto sul sistema

Su Debian 12 il punto non è solo “installare PHP”, ma decidere quale ramo 8.x ti serve e come vuoi esporlo al web server. La distribuzione include una versione stabile nel repository ufficiale, ma in molti casi serve un ramo più recente per compatibilità applicativa, estensioni specifiche o allineamento con un parco hosting già standardizzato. La strada più pulita, quando il ramo richiesto non è nel repository base, è usare un archivio mantenuto, installare solo i componenti necessari e tenere separati runtime, web server e configurazione per evitare effetti collaterali.

La regola pratica è semplice: se devi servire applicazioni PHP in produzione, preferisci PHP-FPM rispetto all’esecuzione embedded nel web server. Ti dà isolamento migliore, gestione più chiara dei pool, tuning dedicato e rollback meno doloroso. Se usi Apache, la combinazione più ordinata è apache2 + php-fpm + proxy_fcgi; con Nginx, PHP-FPM è di fatto la scelta naturale.

Verifica dello stato iniziale e del ramo disponibile

Prima di toccare i repository, verifica cosa hai già installato e quale versione è disponibile nei canali attivi. Questo evita di sovrapporre pacchetti di origine diversa senza volerlo.

1. Controlla la versione di sistema e i pacchetti PHP presenti:

cat /etc/debian_version
php -v
apt-cache policy php php-fpm php-cli

Se php -v non esiste, non è un problema: significa solo che il runtime non è ancora installato. Se invece compare una versione più vecchia di quella richiesta, devi decidere se aggiornare dal repository Debian o introdurre un archivio esterno. In Debian 12, per scenari generici, il ramo di sistema può bastare; per un vero “PHP 8.x” inteso come ramo specifico recente, spesso serve un repository dedicato.

2. Se vuoi vedere cosa offre il repository corrente senza installare nulla:

apt update
apt-cache search '^php[0-9]\.\?[0-9]*-fpm$'
apt-cache search '^php[0-9]\.\?[0-9]*-cli$'

La presenza o assenza di pacchetti con suffisso di versione ti dice subito se il ramo desiderato è già disponibile. Se il repository base non espone il ramo che ti serve, il problema non è tecnico: è di sorgente pacchetti. In quel caso conviene usare un archivio noto, con firma e policy di aggiornamento chiare, invece di mischiare pacchetti presi a caso.

Repository affidabile per PHP 8.x su Debian 12

Quando il repository Debian non basta, la via più usata in ambito amministrativo è un archivio dedicato a PHP, perché fornisce più versioni affiancabili e una matrice di moduli coerente. Il vantaggio operativo è che puoi installare php8.x-cli, php8.x-fpm e le estensioni in modo consistente, senza dover compilare nulla.

Il passaggio critico è la fiducia nella sorgente: aggiungi il repository solo se sai da dove arriva il pacchetto, verifica la chiave, e conserva traccia dello stato prima del cambio. Non serve fare acrobazie: bastano pochi comandi e un backup del file di configurazione APT.

3. Prerequisiti e strumenti per la gestione del repository:

sudo apt update
sudo apt install -y ca-certificates apt-transport-https lsb-release curl gnupg

4. Aggiungi il repository mantenendo la chiave in formato moderno. Un esempio tipico, da adattare al provider scelto, è questo schema:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://example.invalid/repo.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/php.gpg
printf 'deb [signed-by=/etc/apt/keyrings/php.gpg] https://example.invalid/debian %s main\n' "$(lsb_release -sc)" | sudo tee /etc/apt/sources.list.d/php.list

Qui il punto non è il dominio dell’esempio, ma il metodo: chiave separata in /etc/apt/keyrings, repository dedicato in /etc/apt/sources.list.d/, e nessuna chiave globale installata in modo opaco. Se il tuo archivio usa istruzioni diverse, segui quelle ufficiali, ma mantieni lo stesso principio operativo.

5. Aggiorna l’indice e controlla che i pacchetti compaiano con origine coerente:

sudo apt update
apt-cache policy php8.3-cli php8.3-fpm php8.3-common

Il controllo utile è nella colonna 500 o 100 dell’origine pacchetti: se vedi il repository atteso in cima, la priorità è corretta. Se il pacchetto continua a venire dal ramo Debian di base e non dal repository dedicato, fermati e correggi prima di installare.

Installazione del runtime minimo e delle estensioni utili

Per un server web reale non installare “tutto PHP”. Parti dal minimo: CLI, FPM e le estensioni richieste dall’applicazione. Poi aggiungi solo ciò che serve davvero. Questo riduce superficie di manutenzione, tempo di update e possibilità di conflitti.

6. Installazione base di PHP 8.x con FPM e CLI:

sudo apt install -y php8.3-cli php8.3-fpm php8.3-common

Se il tuo ramo è diverso, sostituisci 8.3 con il ramo effettivamente disponibile. Il criterio resta identico: cli per i test e gli script, fpm per il web, common come base condivisa. Dopo l’installazione, verifica subito la versione:

php8.3 -v
systemctl status php8.3-fpm --no-pager

7. Estensioni frequenti per CMS e applicazioni comuni:

sudo apt install -y \
  php8.3-mysql \
  php8.3-xml \
  php8.3-curl \
  php8.3-gd \
  php8.3-mbstring \
  php8.3-zip \
  php8.3-intl \
  php8.3-opcache

Non dare per scontato che ogni estensione serva sempre. Ad esempio, gd è utile per manipolazione immagini, intl per internazionalizzazione e ordinamenti corretti, opcache quasi sempre sì in produzione. Se un’applicazione richiede altro, lo scopri dal suo composer.json, dalla documentazione o dai log di errore PHP, non per intuizione.

8. Se vuoi mappare rapidamente i moduli caricati, usa:

php8.3 -m | sort
php8.3 --ini

Il primo comando ti dice cosa è attivo. Il secondo ti mostra dove PHP legge php.ini e quali file aggiuntivi sono inclusi. È fondamentale quando devi capire perché un parametro non cambia: spesso il valore corretto è in un file diverso da quello che stai modificando.

Configurazione di PHP-FPM: pool, socket e limiti

Il servizio FPM è il punto in cui si gioca la qualità del setup. Il demone deve essere attivo, il pool deve avere permessi corretti e il web server deve raggiungerlo via socket o TCP senza ambiguità. In un’installazione pulita, il socket Unix è la scelta più semplice e più sicura sullo stesso host.

9. Controlla il file di pool principale, di solito in /etc/php/8.3/fpm/pool.d/www.conf. I punti da verificare sono questi:

grep -E '^(user|group|listen|listen.owner|listen.group|pm\.|php_admin_value)' /etc/php/8.3/fpm/pool.d/www.conf

Se il sito gira con un utente dedicato, non lasciare il pool generico senza revisione. Un errore classico è usare il pool www con ownership non coerente rispetto al document root, e poi inseguire falsi problemi di permessi nel filesystem o nel CMS.

10. Un esempio ragionevole di configurazione del pool, da adattare al tuo host, è questo:

; /etc/php/8.3/fpm/pool.d/www.conf
user = www-data
group = www-data
listen = /run/php/php8.3-fpm.sock
listen.owner = www-data
listen.group = www-data
pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

I numeri del process manager non sono universali. Dipendono da RAM, concorrenza e peso medio delle richieste. Se il server è piccolo, partire con valori troppo alti è un modo elegante per finire in swapping. La metrica da guardare non è “quanti processi hai”, ma latenza p95, errori 502/504 e saturazione RAM/CPU sotto carico reale.

11. Dopo ogni modifica al pool, ricarica in modo controllato:

sudo php-fpm8.3 -t
sudo systemctl reload php8.3-fpm
systemctl status php8.3-fpm --no-pager

La validazione sintattica con -t va sempre prima del reload. Se il test fallisce, non forzare il riavvio: correggi il file, poi ricarica. Se il servizio non parte, il journal ti dice subito dove sta il problema:

journalctl -u php8.3-fpm -n 50 --no-pager

Apache con PHP 8.x via proxy_fcgi

Con Apache evita di caricare moduli PHP vecchi se stai già usando FPM. La configurazione corretta è passare le richieste PHP al socket FPM tramite proxy_fcgi. In questo modo mantieni il server web leggero e separi il ciclo di vita del runtime PHP da quello di Apache.

12. Abilita i moduli necessari e disabilita eventuali conflitti se presenti:

sudo a2enmod proxy_fcgi setenvif rewrite headers
sudo a2enconf php8.3-fpm

Se stai migrando da un vecchio schema con libapache2-mod-php, valuta di rimuoverlo solo dopo aver verificato che il sito risponda correttamente con FPM. Il rollback, in quel caso, consiste nel riabilitare il vecchio modulo o nel ripuntare la configurazione al socket corretto.

13. Un VirtualHost tipico con proxy verso FPM può includere una direttiva come questa:

<FilesMatch \.php$>
    SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost/"
</FilesMatch>

Il controllo pratico è immediato: una pagina phpinfo() o uno script minimale deve restituire la versione attesa e il percorso della configurazione corretta. Se vedi una pagina bianca o un 502, il problema è quasi sempre nel collegamento Apache-FPM, nei permessi del socket o in un pool che non è partito.

Nginx con PHP-FPM: configurazione essenziale

Con Nginx il flusso è più lineare: il web server gestisce gli statici e inoltra i file PHP a FPM. Qui gli errori tipici sono due: fastcgi_pass sbagliato e root non coerente con il percorso dei file reali. La verifica va fatta con attenzione, perché Nginx tende a restituire errori generici se il backend non è raggiungibile.

14. Un blocco server minimale può assomigliare a questo:

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}

Verifica sempre che il socket esista davvero:

ls -l /run/php/php8.3-fpm.sock
ss -xl | grep php8.3-fpm

Se il socket non c’è, FPM non è partito o sta ascoltando altrove. Se il socket c’è ma Nginx risponde con 502, controlla i permessi e il gruppo del socket, poi il log di errore di Nginx, di solito in /var/log/nginx/error.log.

Tuning operativo: opcache, limiti e log utili

Installare PHP è solo metà del lavoro. In produzione contano le impostazioni che riducono latenza e rumore operativo. La prima da considerare quasi sempre è OPcache, perché evita di ricompilare gli script a ogni richiesta. La seconda è la scelta di limiti realistici per upload, memoria e timeouts.

15. Controlla il file di configurazione caricato da CLI e FPM, poi applica un set base ragionevole in /etc/php/8.3/fpm/conf.d/ o nel file dedicato dell’applicazione:

opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.validate_timestamps=1

Se il deployment è frequente, validate_timestamps=1 è comodo ma introduce un controllo periodico. Se il rilascio è controllato e fai reload del pool dopo ogni deploy, puoi valutare una strategia più aggressiva, ma solo sapendo come gestire il refresh della cache. Non c’è una regola valida per tutti: la metrica da seguire è il tempo di risposta sotto traffico e la stabilità dopo i deploy.

16. Per i log, tieni presente questi punti di osservazione:

• /var/log/php8.3-fpm.log o il journal di systemd per il demone FPM
• /var/log/nginx/error.log o /var/log/apache2/error.log per l’integrazione web
• log applicativi, spesso in storage/logs, var/log o cartelle simili

Se un sito mostra pagina bianca, il primo passo non è “toccare PHP a caso”, ma leggere gli errori recenti e cercare fatal error, memory exhausted, classi mancanti o estensioni non caricate. In molti casi il problema è un modulo assente, non il motore PHP in sé.

Verifica finale: versione, moduli, FPM e risposta HTTP

La verifica finale deve coprire quattro livelli: binario, moduli, servizio e risposta web. Se ne manca uno, la diagnosi resta incompleta.

17. Esegui questi controlli in sequenza:

php -v
php -m | grep -E 'opcache|mbstring|intl|curl|xml|mysqli|pdo_mysql'
systemctl is-active php8.3-fpm
curl -I http://127.0.0.1/

Se il comando curl -I restituisce 200 o un redirect atteso, il percorso web base funziona. Se invece ottieni 502, 503 o timeout, il guasto è quasi certamente nel passaggio web server → FPM. Se la CLI funziona ma il sito no, il problema non è l’installazione del binario: è la configurazione del front-end o del pool.

18. Se vuoi un test rapido lato applicativo, crea un file temporaneo e rimuovilo dopo la prova:

printf '<?php phpinfo();' | sudo tee /var/www/html/info.php >/dev/null
curl -s http://127.0.0.1/info.php | head
sudo rm -f /var/www/html/info.php

Questo test è utile solo come verifica temporanea. Non lasciare phpinfo() esposto in produzione: mostra dettagli sensibili del sistema, del percorso delle estensioni e della configurazione PHP. Se ti serve un endpoint di health check permanente, usa uno script minimale che ritorni solo uno stato sintetico.

Rollback pratico e gestione del rischio

Ogni modifica che tocca repository, runtime o web server deve avere un rollback chiaro. Se hai aggiunto un repository esterno e qualcosa non torna, il rollback non è “reinstallare tutto”: basta disabilitare la sorgente, fare apt update e tornare ai pacchetti del ramo precedente, purché compatibili con l’applicazione.

19. Prima di cambiare i file, salva una copia del contesto:

sudo cp /etc/php/8.3/fpm/pool.d/www.conf /root/www.conf.bak.$(date +%F)
sudo cp /etc/apt/sources.list.d/php.list /root/php.list.bak.$(date +%F)

Se devi tornare indietro, rimetti i file come erano, ricarica i servizi e ripeti i test. La stabilità del rollback dipende dal fatto che tu abbia cambiato una variabile alla volta. Se hai aggiornato anche il web server, il database o il codice applicativo nello stesso momento, il rientro diventa meno lineare e va gestito a blocchi.

20. Assunzione operativa finale: su Debian 12 conviene installare PHP 8.x in modo modulare, con FPM separato, repository verificato e una sola configurazione web server per host, così da poter misurare l’effetto di ogni modifica senza confondere causa e sintomo.