PHP e CLI: creare un comando per leggere argomenti e opzioni da terminale

Introduzione

Quando si parla di PHP e CLI, molti pensano subito a script lanciati da terminale per automatizzare attività semplici. In realtà, uno degli usi più utili e professionali della CLI in PHP è la creazione di comandi personalizzati che accettano argomenti e opzioni da riga di comando.

Questo approccio è molto pratico perché permette di costruire piccoli strumenti riutilizzabili: ad esempio un comando che genera report, valida dati, esegue importazioni, lancia controlli su file o prepara configurazioni di progetto. In questo tutorial vedremo come leggere i parametri passati da terminale, interpretarli in modo pulito e usare il tutto in uno script PHP ben strutturato.

L’obiettivo è imparare un sotto-argomento utile e concreto: gestire argomenti e opzioni nella CLI con PHP. È un tema diverso da quelli già elencati e rappresenta una base molto solida per costruire strumenti da riga di comando più evoluti.

Codice completo

Nel seguente esempio realizziamo uno script chiamato report.php che riceve un nome utente, un livello di dettaglio e un’opzione per salvare l’output su file.

<?php
declare(strict_types=1);

/**
 * Script CLI per generare un piccolo report testuale.
 * Uso:
 * php report.php Mario --level=full --output=report.txt
 */

// Verifica che lo script sia eseguito da CLI
if (PHP_SAPI !== ´cli´) {
    fwrite(STDERR, "Questo script va eseguito da riga di comando.n");
    exit(1);
}

// Estrae gli argomenti passati da terminale
$args = $argv;
array_shift($args); // rimuove il nome dello script

// Funzione semplice per leggere opzioni nel formato --chiave=valore
function parseOptions(array $args): array
{
    $options = [];
    $positionals = [];

    foreach ($args as $arg) {
        if (str_starts_with($arg, ´--´)) {
            $parts = explode(´=´, substr($arg, 2), 2);
            $key = $parts[0];
            $value = $parts[1] ?? true;
            $options[$key] = $value;
        } else {
            $positionals[] = $arg;
        }
    }

    return [
        ´options´ => $options,
        ´positionals´ => $positionals,
    ];
}

$data = parseOptions($args);
$options = $data[´options´];
$positionals = $data[´positionals´];

// Argomento obbligatorio: nome utente
$username = $positionals[0] ?? null;
if ($username === null) {
    fwrite(STDERR, "Uso: php report.php <nome> [--level=basic|full] [--output=file]n");
    exit(1);
}

// Opzioni con valori di default
$level = $options[´level´] ?? ´basic´;
$outputFile = $options[´output´] ?? null;

// Validazione del livello
$allowedLevels = [´basic´, ´full´];
if (!in_array($level, $allowedLevels, true)) {
    fwrite(STDERR, "Valore non valido per --level. Usa: basic oppure fulln");
    exit(1);
}

// Costruzione del report
$report = [];
$report[] = "Report CLI";
$report[] = "Utente: " . $username;
$report[] = "Livello: " . $level;
$report[] = "Data: " . date(´Y-m-d H:i:s´);
$report[] = "";

if ($level === ´basic´) {
    $report[] = "Sezione base:";
    $report[] = "- Controllo completato";
    $report[] = "- Nessuna anomalia rilevata";
} else {
    $report[] = "Sezione completa:";
    $report[] = "- Controllo completato";
    $report[] = "- Nessuna anomalia rilevata";
    $report[] = "- Dettaglio 1: verifica input OK";
    $report[] = "- Dettaglio 2: validazione parametri OK";
    $report[] = "- Dettaglio 3: output generato correttamente";
}

$output = implode(PHP_EOL, $report) . PHP_EOL;

// Stampa a schermo
echo $output;

// Salvataggio su file, se richiesto
if ($outputFile !== null) {
    $written = file_put_contents($outputFile, $output);

    if ($written === false) {
        fwrite(STDERR, "Errore durante il salvataggio del file.n");
        exit(1);
    }

    echo "Report salvato in: {$outputFile}" . PHP_EOL;
}

Spiegazione

Vediamo il funzionamento del codice passo per passo. La prima cosa importante è il controllo:

if (PHP_SAPI !== ´cli´) { ... }

Questa verifica assicura che lo script venga eseguito da terminale e non tramite browser. È una buona pratica perché evita comportamenti inattesi e rende più chiaro l’uso previsto del file.

Subito dopo utilizziamo la variabile globale $argv, che contiene tutti gli argomenti passati allo script. Il primo elemento è sempre il nome del file PHP, quindi lo rimuoviamo con:

array_shift($args);

In questo modo restano solo i parametri realmente utili. La funzione parseOptions() divide gli input in due gruppi:

positional arguments: argomenti senza prefisso, come Mario;
options: parametri nel formato --chiave=valore, come --level=full.

Questa separazione è molto utile perché consente di gestire in modo ordinato sia i dati obbligatori sia le configurazioni opzionali.

Nel nostro esempio, il nome utente è un argomento obbligatorio:

$username = $positionals[0] ?? null;

Se manca, lo script mostra un messaggio di uso corretto e termina con un codice di uscita diverso da zero. Questo è importante nei programmi CLI perché il codice di uscita comunica al sistema operativo se l’esecuzione è andata bene o male.

Le opzioni invece hanno valori predefiniti. Per esempio --level vale basic se non viene specificato. Poi validiamo il contenuto con un elenco di valori consentiti:

$allowedLevels = [´basic´, ´full´];

Questa validazione evita errori logici e rende lo script più robusto. Se l’utente inserisce un valore non previsto, il comando si interrompe con un messaggio chiaro.

Infine costruiamo il report come array di righe e lo uniamo con implode(). Questo approccio è comodo perché rende il codice leggibile e facile da estendere. Se in futuro volessimo aggiungere nuove sezioni, basterebbe inserire altre righe nell’array.

Se l’utente passa anche --output=report.txt, il contenuto viene salvato in un file tramite file_put_contents(). In questo modo lo stesso comando può essere usato sia per visualizzare sia per esportare il risultato.

Best practice

Quando sviluppi script PHP per la CLI, alcune buone pratiche fanno davvero la differenza:

Controlla sempre il contesto di esecuzione: verifica che lo script sia lanciato da CLI.
Valida gli input: non fidarti mai dei parametri passati da terminale.
Definisci un uso chiaro: stampa sempre un messaggio con la sintassi corretta se mancano dati obbligatori.
Usa valori di default sensati: rendono gli script più semplici da usare.
Separa parsing e logica: prima leggi gli argomenti, poi esegui il lavoro vero e proprio.
Gestisci gli errori con STDERR: per i messaggi di errore usa fwrite(STDERR, ...) invece di echo.
Restituisci exit code coerenti: 0 per successo, valori diversi da zero per errori.

Un altro consiglio utile è mantenere gli script piccoli e focalizzati. Se il comando cresce troppo, conviene separare il parsing degli argomenti dalla logica applicativa in funzioni o classi dedicate. Questo rende il codice più testabile e più facile da mantenere.

Inoltre, quando i parametri diventano numerosi, può essere utile adottare una libreria dedicata alla gestione della CLI. Tuttavia, per molti casi reali, la soluzione manuale mostrata in questo tutorial è perfetta per capire bene i meccanismi di base.

Riepilogo

In questo tutorial abbiamo visto come usare PHP e CLI per costruire un comando che legge argomenti e opzioni da terminale. Abbiamo creato uno script capace di:

verificare che l’esecuzione avvenga da riga di comando;
leggere argomenti posizionali con $argv;
gestire opzioni nel formato --chiave=valore;
validare i valori ricevuti;
stampare un output a schermo e, se necessario, salvarlo su file.

Questo è un ottimo punto di partenza per sviluppare utility CLI più complesse: importatori, generatori di file, task di manutenzione, strumenti per reportistica e piccoli comandi di supporto ai progetti PHP.

Approfondisci con risorse ufficiali

Per continuare lo studio, ti consiglio di consultare la documentazione ufficiale PHP sui seguenti argomenti:

PHP CLI e modalità di esecuzione da terminale
$argv e $argc per leggere gli argomenti della riga di comando
PHP_SAPI per distinguere CLI e web server
fwrite(), STDOUT e STDERR
file_put_contents() per la scrittura su file
date() per generare timestamp nei report

Approfondire questi strumenti ti aiuterà a scrivere script CLI più affidabili, puliti e pronti per essere usati in ambienti reali di sviluppo e automazione.

Add as preferred source on Google