ftp_rawlist()

Comprendere la funzione PHP ftp_rawlist()

La funzione ftp_rawlist() restituisce un elenco dettagliato di una directory su un server FTP. Ogni elemento dell'array restituito corrisponde a una riga dell'output grezzo LIST del server — lo stesso testo che vedresti in un client FTP a riga di comando, inclusi permessi del file, proprietario, dimensione e data di modifica.

Questa pagina illustra cosa restituisce ftp_rawlist(), la sua sintassi, un esempio funzionante completo, come analizzare le righe grezze in dati utilizzabili, gli elenchi ricorsivi e la gestione degli errori. Se hai bisogno solo dei nomi dei file in una directory, usa ftp_nlist() — è più semplice e molto più facile da analizzare.

Cos'è ftp_rawlist()?

ftp_rawlist() accetta due parametri obbligatori e uno opzionale:

ftp_stream — l'oggetto connessione (PHP 8.1+) o la risorsa restituita da ftp_connect() (o ftp_ssl_connect()).
directory — la directory da elencare.
recursive (opzionale) — impostare a true per elencare le sottodirectory in modo ricorsivo.

In caso di successo restituisce un array di stringhe, dove ogni string è una riga grezza dell'output; in caso di errore (o per una directory vuota che non può essere letta) restituisce false.

L'aspetto fondamentale da capire è che questo output non è standardizzato. È qualsiasi cosa il comando LIST del server produca, quindi il suo formato dipende dal sistema operativo e dalla configurazione del server. Un server in stile Unix restituisce tipicamente righe simili all'output di ls -l:

drwxr-xr-x   2 owner group        4096 Jun 21 10:00 images
-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html

I server in stile Windows/DOS restituiscono un formato completamente diverso. Per questo motivo, ftp_rawlist() fornisce tutti i dettagli al costo di dover analizzare manualmente del testo in formato libero. Confrontalo con:

ftp_nlist() — restituisce un semplice array con solo i nomi dei file.
ftp_mlsd() — restituisce un elenco strutturato e leggibile dalla macchina (preferibile quando il server supporta il comando MLSD).

Sintassi di ftp_rawlist()

La sintassi della funzione ftp_rawlist() è la seguente:

Sintassi di ftp_rawlist()

array ftp_rawlist ( FTP\Connection|resource $ftp_stream , string $directory [, bool $recursive = false ] )

La funzione ftp_rawlist() accetta due parametri obbligatori, ftp_stream e directory. Il parametro ftp_stream è l'identificatore di connessione restituito dalla funzione ftp_connect(), e il parametro directory è la directory da elencare. La funzione ha anche un parametro opzionale, recursive, che consente di specificare se elencare le sottodirectory.

Utilizzo di ftp_rawlist()

Per utilizzare la funzione ftp_rawlist(), devi prima stabilire una connessione al server FTP usando la funzione ftp_connect(). Ecco un esempio:

Utilizzo di ftp_rawlist()

<?php

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

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

// Get a detailed listing of the directory
$listing = ftp_rawlist($conn, '/public_html');

// Output the listing to the console
if ($listing) {
    foreach ($listing as $item) {
        echo $item . "\n";
    }
}

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

Qui ci connettiamo con ftp_connect(), ci autentichiamo con ftp_login(), recuperiamo l'elenco con ftp_rawlist(), stampiamo ogni riga grezza e infine rilasciamo la connessione con ftp_close().

Suggerimento — modalità passiva: Molte reti e firewall bloccano il canale dati in modalità attiva che ftp_rawlist() usa per recuperare l'elenco, causando un blocco o la restituzione di false. Se accade, abilita la modalità passiva con ftp_pasv($conn, true) dopo aver effettuato il login.

Nota di sicurezza: Il protocollo FTP standard trasmette credenziali e dati in chiaro. Per ambienti di produzione, considera l'uso di ftp_ssl_connect() per FTP esplicito su TLS, oppure passa a SFTP (tramite l'estensione ssh2) per trasferimenti crittografati.

Analisi dell'elenco grezzo

Poiché ogni riga è testo non strutturato, di solito è necessario estrarne i singoli campi. Per un server in stile Unix puoi dividere ogni riga sugli spazi bianchi: i permessi sono il primo token, la dimensione è il quinto e il nome del file è tutto ciò che segue l'ottavo token (il nome può contenere spazi).

Analisi di un elenco grezzo in stile Unix

<?php

// One line of typical ftp_rawlist() output:
$line = '-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html';

// Split on runs of whitespace, limited so the name stays intact.
$parts = preg_split('/\s+/', $line, 9);

$type        = $parts[0][0] === 'd' ? 'directory' : 'file';
$permissions = $parts[0];
$size        = (int) $parts[4];
$name        = $parts[8];

echo "Name:        $name\n";
echo "Type:        $type\n";
echo "Size:        $size bytes\n";
echo "Permissions: $permissions\n";
?>

Questo stampa:

Name:        index.html
Type:        file
Size:        10240 bytes
Permissions: -rw-r--r--

Se il tuo server lo supporta, preferisci ftp_mlsd(), che restituisce questi dati già strutturati, così puoi evitare l'analisi fragile delle stringhe.

Elenco delle sottodirectory in modo ricorsivo

Passando true come terzo argomento si istruisce il server a discendere nelle sottodirectory. L'output include quindi righe vuote e intestazioni di directory (un percorso seguito da due punti) che separano il contenuto di ciascuna sottodirectory — sii pronto a saltarle durante l'iterazione:

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html', true);

foreach ($listing as $line) {
    if ($line === '' || str_ends_with($line, ':')) {
        // Skip blank separators and "/path/to/dir:" headers
        continue;
    }
    echo $line . "\n";
}
?>

Tieni presente che non tutti i server FTP rispettano il flag ricorsivo, e una struttura ad albero profonda può essere lenta, quindi testa sul server di destinazione.

Gestione degli errori in ftp_rawlist()

È importante gestire correttamente gli errori quando si utilizza la funzione ftp_rawlist(). Se la funzione restituisce false, significa che l'operazione non è riuscita. Ecco un esempio di come gestire gli errori:

Gestione degli errori in ftp_rawlist()

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html');

if (!$listing) {
    echo "Failed to get directory listing from FTP server.\n";
}

ftp_close($conn);
?>

Gestendo gli errori in modo appropriato e verificando il valore restituito dalla funzione, puoi garantire il successo delle tue operazioni FTP utilizzando la funzione ftp_rawlist().

Conclusione

ftp_rawlist() è la funzione da usare quando hai bisogno di tutti i metadati dei file — permessi, proprietario, dimensione e data — da una directory FTP, non solo i nomi. Il compromesso è che il suo output è il testo LIST grezzo e dipendente dal sistema operativo del server, quindi pianifica di analizzarlo (oppure usa il strutturato ftp_mlsd() dove disponibile). Verifica sempre il valore restituito, abilita la modalità passiva quando sei dietro un firewall e preferisci una connessione crittografata per la produzione.

Funzioni correlate

ftp_nlist() — elenca solo i nomi dei file
ftp_mlsd() — elenco strutturato e leggibile dalla macchina
ftp_connect() / ftp_login() — apri e autentica una sessione
ftp_get() — scarica un file una volta trovato
ftp_close() — chiudi la connessione

Practice

Pratica

Qual è la funzione di ftp_rawlist in PHP?

Produce un elenco di file in una directory specificata.Fornisce informazioni su un file su un server.Restituisce un elenco dettagliato dei file nella directory specificata su un server FTP.Recupera il contenuto di un file da un server.