Aggiornare PHP senza rompere il sito: test di compatibilità e rollback

Come aggiornare PHP senza compromettere il sito Web: una guida pratica per verificare codice e dipendenze, confrontare versioni PHP con Docker, eseguire test automatici e ripristinare la configurazione precedente in caso di problemi.

La necessità di aggiornare PHP lato server è sempre più frequente, spesso per via di vulnerabilità come PHP2Shell e altre problematiche che il team ha già annunciato di aver corretto. L’aggiornamento di PHP può insomma migliorare sicurezza e prestazioni, ma un’applicazione che funziona perfettamente con una versione del linguaggio potrebbe smettere di rispondere dopo il passaggio a quella successiva. Funzioni eliminate, librerie incompatibili, estensioni mancanti e modifiche nella gestione degli errori possono provocare malfunzionamenti difficili da individuare.

La soluzione non consiste semplicemente nell’installare la nuova versione e verificare se il sito si apre: è bene analizzare preventivamente il codice, controllare le dipendenze e riprodurre l’ambiente applicativo, mantenendo la possibilità di tornare rapidamente alla configurazione precedente.

Vediamo una procedura concreta utilizzando PHPCompatibility, Composer, PHPUnit e Docker, con esempi applicabili ad applicazioni PHP personalizzate, CMS e progetti basati su framework.

Prima dell’aggiornamento: identificare l’ambiente PHP effettivo

Il primo controllo riguarda la versione di PHP utilizzata dal progetto. Da terminale, impartiamo i comandi che mostrano rispettivamente la versione PHP, i file di configurazione caricati e le estensioni disponibili:

php -v
php --ini
php -m

La versione PHP rilevata da terminale potrebbe essere diversa da quella utilizzata dal server Web: un sito può utilizzare PHP-FPM 8.3 mentre il comando php esegue PHP 8.5. Occorre quindi verificare anche la configurazione di Apache, NGINX o del pannello hosting.

Prima di procedere, va creato un backup dei file applicativi, del database, della configurazione PHP e del file composer.lock: quest’ultimo conserva le versioni esatte delle dipendenze installate.

Per una panoramica sulle diverse modalità di esecuzione rimandiamo alla nostra guida alla configurazione di PHP su Windows e Linux.

PHPCompatibility: individuare funzioni e costrutti non più supportati

PHPCompatibility è un insieme di regole per PHP_CodeSniffer che analizza il codice sorgente alla ricerca di costrutti incompatibili con determinate versioni del linguaggio.

PHPCompatibility si installa tramite Composer, il gestore delle librerie e delle dipendenze PHP. Se Composer non è ancora disponibile sul sistema utilizzato per i test, possiamo installarlo seguendo le istruzioni ufficiali. Per verificare che sia correttamente installato, apriamo il terminale ed eseguiamo quanto segue:

composer --version

Spostiamoci quindi nella directory principale del progetto PHP, dove si trova il file composer.json, se già presente, ed eseguiamo:

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev phpcompatibility/php-compatibility

Il primo comando autorizza il plugin necessario per registrare le regole di controllo; il secondo installa PHPCompatibility e le relative dipendenze, rendendo disponibile lo strumento di analisi del codice.

Analizzare la compatibilità del codice con una specifica versione di PHP

Per verificare, ad esempio, il codice contenuto nella directory src rispetto a PHP 8.5:

vendor/bin/phpcs -p src --standard=PHPCompatibility --runtime-set testVersion 8.5

Lo strumento può segnalare funzioni eliminate, funzionalità deprecate o sintassi non compatibile, indicando file e righe interessati. Per salvare il risultato in un resoconto finale:

vendor/bin/phpcs src --standard=PHPCompatibility --runtime-set testVersion 8.5 --report-full=compatibilita.txt

La copertura dipende dalla versione di PHPCompatibility installata e dalle regole disponibili. Un risultato privo di errori non certifica la compatibilità dell’intera applicazione, soprattutto quando il codice richiama librerie esterne o genera dinamicamente istruzioni PHP.

Non bisogna installare Composer sul server Web di produzione: è preferibile eseguire queste verifiche su una copia del progetto, in un ambiente di sviluppo o staging, senza modificare direttamente il sito pubblico.

Composer: verificare librerie e versioni PHP richieste

Un’applicazione moderna utilizza spesso decine di dipendenze gestite tramite Composer: ciascun pacchetto può dichiarare quali versioni PHP supporta. Per individuare i componenti che impediscono l’adozione di PHP 8.5 possiamo eseguire:

composer prohibits php 8.5

Il comando identifica i vincoli che impediscono la compatibilità dichiarata con la versione richiesta. Per verificare invece se l’ambiente PHP corrente soddisfa i requisiti dei pacchetti installati si può usare il comando seguente:

composer check-platform-reqs

Il controllo considera anche le estensioni PHP richieste, a patto ovviamente di svolgere il controllo all’interno dell’ambiente che vogliamo verificare.

La documentazione ufficiale di Composer descrive il funzionamento di questi controlli.

Docker: confrontare due versioni PHP senza modificare il server

Con Docker possiamo eseguire lo stesso codice avvalendoci di versioni PHP differenti, mantenendo separati gli ambienti di prova. Creiamo nella directory del progetto un file compose.yaml:

services:
  php83:
    image: php:8.3-cli
    working_dir: /app
    volumes:
      - ./:/app

  php85:
    image: php:8.5-cli
    working_dir: /app
    volumes:
      - ./:/app

Avendo Docker Compose disponibile, verifichiamo le due versioni:

docker compose run --rm php83 php -v
docker compose run --rm php85 php -v

Possiamo controllare la sintassi di un file applicativo con il nuovo runtime:

docker compose run --rm php85 php -l src/index.php

Verificare il funzionamento dell’applicazione con PHPUnit

Il comando php -l utilizzato in precedenza controlla che un file PHP non contenga errori di sintassi, ma non esegue il programma. Un risultato positivo non garantisce quindi che l’applicazione continui a funzionare correttamente dopo l’aggiornamento.

Per effettuare una verifica più approfondita possiamo utilizzare PHPUnit, uno strumento che permette di eseguire automaticamente una serie di test sul codice PHP. Possiamo così controllare che determinate funzioni restituiscano i risultati attesi e che il comportamento dell’applicazione non cambi passando da una versione PHP all’altra.

Se il progetto dispone già di test PHPUnit e lo strumento è installato tramite Composer nella directory vendor, possiamo eseguire gli stessi test nei due container Docker:

docker compose run --rm php83 php vendor/bin/phpunit
docker compose run --rm php85 php vendor/bin/phpunit

Il primo comando esegue i test con PHP 8.3, mentre il secondo li ripete con PHP 8.5. Se un test funziona con la vecchia versione e fallisce con quella nuova, abbiamo individuato un possibile problema di compatibilità da approfondire prima dell’aggiornamento del sito.

Se PHPUnit non è ancora presente nel progetto, possiamo installarlo nell’ambiente di sviluppo tramite Composer, scegliendo una versione compatibile con entrambe le versioni PHP da confrontare:

composer require --dev phpunit/phpunit

L’installazione, da sola, non crea però i test: bisogna predisporre i file contenenti le verifiche da eseguire. È possibile far riferimento alla documentazione ufficiale di PHPUnit per creare i primi test e configurarli nel progetto.

Attenzione alle differenze tra Docker e il server di produzione

Il confronto tra le due versioni PHP è attendibile soltanto se i container dispongono delle estensioni e delle configurazioni richieste dall’applicazione. Le immagini Docker php:8.3-cli e php:8.5-cli utilizzate nell’esempio contengono PHP per la riga di comando, ma non riproducono automaticamente l’ambiente del server Web.

Un’applicazione che utilizza MySQL, ad esempio, potrebbe richiedere l’estensione pdo_mysql; altre potrebbero dipendere da intl per la gestione delle lingue o da gd per l’elaborazione delle immagini. Se queste estensioni mancano, i test possono fallire per ragioni che non dipendono dall’aggiornamento di PHP.

Per progetti reali conviene quindi predisporre immagini Docker personalizzate che riproducano, per quanto possibile, estensioni, impostazioni e servizi utilizzati in produzione.

Un’ultima precauzione riguarda i file: nel nostro esempio, entrambi i container accedono alla stessa directory del progetto attraverso il collegamento ./:/app. Di conseguenza, eventuali modifiche apportate dai test ai file applicativi, alla cache o ai dati salvati su disco possono influenzare le esecuzioni successive.

Test di regressione: verificare ciò che conta

Superare un controllo sintattico non significa che il sito funzioni correttamente: è indispensabile accertare anche il comportamento dell’applicazione.

Con PHPUnit possiamo automatizzare i test delle funzioni principali. Consideriamo ad esempio una funzione che calcola un prezzo scontato:

function sconta(float $prezzo, float $percentuale): float
{
    return round($prezzo * (1 - $percentuale / 100), 2);
}

Un test potrebbe verificare che il calcolo restituisca il risultato previsto:

use PHPUnit\Framework\TestCase;

final class PrezzoTest extends TestCase
{
    public function testSconto(): void
    {
        $this->assertSame(80.0, sconta(100.0, 20.0));
    }
}

Come effettuare un test in pratica

L’esempio presuppone che la funzione sconta() sia già disponibile quando PHPUnit esegue il test. Per ottenere questo risultato possiamo utilizzare un file di bootstrap, ovvero uno script PHP caricato automaticamente prima dei test, che include i file necessari o inizializza il sistema di caricamento delle classi di Composer.

Ad esempio, se la funzione si trova nel file src/funzioni.php, possiamo creare un file tests/bootstrap.php contenente:

require __DIR__ . '/../src/funzioni.php';

Possiamo quindi avviare PHPUnit indicando esplicitamente il bootstrap:

vendor/bin/phpunit --bootstrap tests/bootstrap.php tests/

Nelle applicazioni reali non basta verificare una singola funzione: è cruciale controllare anche autenticazione, gestione delle sessioni, interrogazioni SQL, caricamento dei file, invio delle email e comunicazioni con API esterne. Per esempio, possiamo verificare che un utente riesca ancora ad autenticarsi, che una query restituisca i dati attesi e che il caricamento di un documento non produca errori dopo il cambio di versione PHP. Queste verifiche andrebbero eseguite in un ambiente di prova, utilizzando database dedicati e simulando, quando possibile, le comunicazioni con servizi esterni.

Durante il collaudo attiviamo una registrazione dettagliata degli errori, senza mostrarli ai visitatori (le direttive vanno inserite nel file di configurazione php.ini dell’ambiente PHP utilizzato per i test):

display_errors = Off
log_errors = On
error_reporting = E_ALL

La comparsa di nuovi avvisi Deprecated, eccezioni o errori nei log può rivelare problemi che una semplice visita alla homepage non evidenzierebbe.

Come aggiornare PHP in produzione senza perdere la possibilità di rollback

Il passaggio definitivo dovrebbe avvenire soltanto dopo aver completato i test usando un ambiente di staging sufficientemente simile alla produzione.

La procedura più sicura consiste nel preparare la nuova versione PHP separatamente, verificare le estensioni necessarie e distribuire un rilascio applicativo identificabile, conservando quello precedente.

Con PHP-FPM possiamo predisporre pool differenti e modificare il collegamento utilizzato dal server Web soltanto quando il nuovo ambiente è pronto. Con Docker possiamo mantenere l’immagine precedente e ripristinarla qualora emergano problemi.

Il rollback non deve limitarsi a ripristinare il vecchio eseguibile PHP: se durante la migrazione abbiamo aggiornato Composer, modificato il database o introdotto nuove configurazioni, potrebbe essere necessario ripristinare anche questi componenti.

Per ridurre il rischio, è ragionevole evitare aggiornamenti simultanei di PHP, framework, plugin e struttura del database: le modifiche ai dati dovrebbero essere compatibili con entrambe le versioni applicative oppure accompagnate da procedure di ripristino collaudate.

La regola fondamentale: aggiornare PHP è un processo, non un comando

PHPCompatibility individua potenziali incompatibilità nel codice, Composer controlla i requisiti delle dipendenze, Docker permette di confrontare ambienti differenti e PHPUnit verifica che le funzionalità continuino a produrre i risultati previsti.

Nessuno strumento, da solo, garantisce una migrazione sicura. La combinazione di analisi statica, test di regressione, ambienti isolati e rollback verificato permette però di individuare molti problemi prima che coinvolgano gli utenti del sito.

Ti consigliamo anche

Link copiato negli appunti