Composer in PHP: verificare la compatibilità con la piattaforma di esecuzione

Introduzione

Un progetto PHP non dipende soltanto dai pacchetti installati tramite Composer. Ogni applicazione richiede anche una determinata versione di PHP e, spesso, alcune estensioni come ext-json, ext-mbstring o ext-pdo. Se l’ambiente di sviluppo, il server di test e quello di produzione non sono compatibili, l’installazione delle dipendenze può fallire oppure l’applicazione può comportarsi in modo imprevisto.

Composer permette di descrivere questi requisiti direttamente nel file composer.json. In questo modo le incompatibilità vengono individuate prima del deploy, invece di comparire soltanto quando il codice è già online.

Questo tutorial mostra come:

dichiarare la versione minima di PHP richiesta;
richiedere specifiche estensioni PHP;
simulare una piattaforma diversa durante lo sviluppo;
diagnosticare rapidamente i problemi con i comandi di Composer.

Codice completo

Creiamo un file composer.json per una semplice applicazione web che utilizza un client HTTP e richiede alcune funzionalità dell’interprete PHP.

{
    "name": "esempio/catalogo-prodotti",
    "description": "Applicazione PHP per la gestione di un catalogo",
    "type": "project",
    "require": {
        "php": "^8.2",
        "ext-json": "*",
        "ext-mbstring": "*",
        "ext-pdo": "*",
        "guzzlehttp/guzzle": "^7.8"
    },
    "config": {
        "platform": {
            "php": "8.2.0"
        },
        "sort-packages": true
    },
    "autoload": {
        "psr-4": {
            "App": "src/"
        }
    }
}

Per controllare se la piattaforma corrente soddisfa i requisiti dichiarati, eseguiamo:

composer check-platform-reqs

Per visualizzare tutti i requisiti dei pacchetti installati possiamo invece usare:

composer show --platform

Se vogliamo sapere perché un determinato pacchetto non può essere installato, il comando why-not è particolarmente utile:

composer why-not php 8.1

Possiamo anche verificare il file di configurazione senza modificare le dipendenze:

composer validate

Spiegazione

Requisiti della versione PHP

La voce php dentro require stabilisce quale versione dell’interprete è compatibile con il progetto. Nell’esempio, la notazione ^8.2 indica PHP 8.2 o una versione successiva compatibile secondo le regole semantiche di Composer, quindi versioni inferiori a PHP 9.

Dichiarare questo requisito è importante perché un pacchetto può utilizzare funzioni introdotte in una versione recente di PHP. Senza una dichiarazione esplicita, un progetto potrebbe essere installato su un server troppo vecchio e fallire durante l’esecuzione.

Estensioni PHP

Le estensioni vengono indicate con il prefisso ext-. Per esempio:

ext-json per lavorare con JSON;
ext-mbstring per gestire correttamente stringhe multibyte;
ext-pdo per l’accesso ai database tramite PDO.

Il valore * significa che è sufficiente che l’estensione sia disponibile, senza imporre una versione specifica. Se un’estensione è indispensabile per il funzionamento dell’applicazione, dichiararla consente di ottenere un errore chiaro già durante composer install.

La configurazione platform

La sezione config.platform permette di simulare una determinata piattaforma durante la risoluzione delle dipendenze. Nell’esempio Composer risolve i pacchetti come se il progetto fosse eseguito con PHP 8.2.0.

Questa impostazione è utile quando lo sviluppatore utilizza PHP 8.3, ma il server di produzione utilizza PHP 8.2. Senza questa simulazione, Composer potrebbe installare una versione di una libreria compatibile con PHP 8.3 ma non con il server reale.

È importante ricordare che config.platform non cambia davvero la versione di PHP installata. Se il codice viene eseguito con PHP 8.1, continuerà a essere eseguito con PHP 8.1. La configurazione serve soltanto a rendere più prudente la risoluzione delle dipendenze.

Controllo prima del deploy

Una procedura semplice può includere questi comandi:

composer validate --strict
composer install --no-dev --prefer-dist
composer check-platform-reqs

Il primo comando verifica la correttezza del file composer.json. L’opzione --strict trasforma anche gli avvisi in errori. Il secondo installa le dipendenze necessarie alla produzione, mentre l’ultimo controlla che PHP e le sue estensioni siano realmente disponibili.

Best practice

Dichiara sempre la versione minima di PHP: evita valori troppo generici come >=7.4 se il progetto usa caratteristiche moderne.
Indica le estensioni obbligatorie: il progetto deve documentare tutte le funzionalità richieste dall’ambiente.
Allinea platform all’ambiente reale: se il server utilizza PHP 8.2, considera di configurare Composer con PHP 8.2 anche durante lo sviluppo.
Non usare platform per nascondere problemi: simulare una versione non installata non rende l’ambiente realmente compatibile.
Inserisci i controlli nella pipeline: esegui composer validate e composer check-platform-reqs prima del deploy.
Usa immagini o macchine coerenti: Docker, ambienti virtualizzati o configurazioni documentate riducono le differenze tra sviluppatori e server.

Riepilogo

Composer non gestisce soltanto i pacchetti: può anche descrivere i requisiti dell’ambiente necessario per eseguire un progetto PHP. Dichiarare la versione di PHP e le estensioni richieste permette di individuare presto le incompatibilità.

La configurazione platform è utile per risolvere le dipendenze considerando l’ambiente di produzione, mentre check-platform-reqs, validate e why-not aiutano a diagnosticare i problemi in modo sistematico.

Approfondisci con risorse ufficiali

Add as preferred source on Google