ftp_raw()

Comprendere la funzione PHP ftp_raw()

La funzione ftp_raw() è una funzione PHP integrata che invia un comando arbitrario direttamente a un server FTP e restituisce la risposta grezza e non analizzata del server. A differenza degli helper FTP di alto livello, ftp_raw() non interpreta il risultato per te — restituisce esattamente ciò che il server ha risposto, riga per riga. Questa pagina spiega cosa fa la funzione, quando hai effettivamente bisogno di usarla e come usarla in modo sicuro.

Cos'è ftp_raw()?

FTP è un protocollo basato su testo: i client inviano comandi brevi come SYST, PWD o FEAT, e il server risponde con righe di stato numerate (ad esempio 215 UNIX Type: L8). La maggior parte delle funzioni PHP per FTP — come ftp_nlist(), ftp_get() e ftp_systype() — incapsulano uno di questi comandi e analizzano la risposta in un valore conveniente. ftp_raw() salta l'analisi ed espone direttamente il protocollo.

Accetta due parametri:

1. ftp_stream — l'identificatore di connessione restituito da ftp_connect().
2. command — la stringa del comando FTP da inviare (ad esempio 'SYST' o 'PWD').

In caso di successo restituisce un array di stringhe, un elemento per ogni riga di risposta, contenente la risposta del server. In caso di errore (ad esempio una connessione non valida) restituisce false.

Quando dovresti usarla?

Per le operazioni quotidiane — elencare, caricare, scaricare — preferisci le funzioni dedicate; esse gestiscono le connessioni dati e l'analisi per te. Ricorri a ftp_raw() solo quando:

• Hai bisogno di un comando per cui PHP non ha un wrapper (ad esempio FEAT per scoprire le funzionalità del server, o una direttiva SITE personalizzata).
• Stai eseguendo il debug e vuoi vedere l'esatta riga di stato restituita dal server.
• Stai implementando un comportamento del protocollo che l'API di alto livello non espone.

Nota che ftp_raw() è destinata solo ai comandi del canale di controllo. Non può trasferire dati di file — comandi come RETR o LIST richiedono una connessione dati separata, motivo per cui si usano ftp_get() o ftp_nlist() per quelli.

Comandi grezzi comuni

Sintassi di ftp_raw()

La firma della funzione ftp_raw() è la seguente:

ftp_raw(FTP\Connection $ftp, string $command): array

Il parametro $ftp è la connessione restituita da ftp_connect(), e $command è la stringa del comando da inviare. Entrambi sono obbligatori.

Utilizzo di ftp_raw()

Per utilizzare la funzione ftp_raw(), è necessario prima stabilire una connessione al server FTP con ftp_connect() e autenticarsi con ftp_login(). Ecco un esempio completo:

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die("Could not connect to FTP server.\n");
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die("Login failed.\n");
}

// Ask the server what operating system it runs
$response = ftp_raw($conn, 'SYST');

// Output the server's raw response, one line per element
echo "Server response: " . implode("\n", $response) . "\n";
// e.g. Server response: 215 UNIX Type: L8

// Close the FTP connection
ftp_close($conn);

Qui ci connettiamo con ftp_connect() e verifichiamo che abbia avuto successo, ci autentichiamo con ftp_login(), inviamo il comando SYST con ftp_raw() e stampiamo ogni riga di risposta. Il 215 è il codice di risposta FTP; il testo successivo è la risposta del server. Infine rilasciamo la connessione con ftp_close().

Gestione degli errori in ftp_raw()

Controlla sempre il valore restituito prima di utilizzarlo. ftp_raw() restituisce false quando non riesce a inviare il comando (ad esempio perché la connessione non è più valida), quindi passare direttamente quel risultato a implode() causerebbe un errore di tipo. Proteggi il codice:

<?php

$response = ftp_raw($conn, 'SYST');

if ($response === false) {
    echo "Failed to send the raw command to the FTP server.\n";
} else {
    echo implode("\n", $response) . "\n";
}

ftp_close($conn);

Tieni presente che un array non-false non garantisce che il comando stesso abbia avuto successo — significa solo che il server ha risposto. Esamina il codice di risposta (il numero iniziale su ogni riga, come 5xx per gli errori) quando hai bisogno di sapere se il comando è stato accettato.

Conclusione

La funzione ftp_raw() ti dà accesso diretto al canale di controllo FTP, il che è prezioso per i comandi che PHP non incapsula (come FEAT) e per il debug. Per le operazioni ordinarie di elenco, caricamento e scaricamento, usa invece le funzioni dedicate. Consulta il riferimento completo alle funzioni PHP FTP per l'insieme completo.

Esercitazione