ftp_mlsd()

Che cos'è ftp_mlsd()?

ftp_mlsd() è una funzione PHP integrata (disponibile da PHP 7.2) che elenca il contenuto di una directory su un server FTP utilizzando il comando FTP MLSD. A differenza delle funzioni di listaggio più vecchie, restituisce un risultato strutturato e leggibile dalla macchina: invece di un blocco di testo grezzo da analizzare manualmente, si ottiene un array di voci in cui ogni file o directory ha attributi con nome come tipo, dimensione e data di modifica.

Questo è importante perché i listati di directory FTP sono notoriamente inconsistenti — ftp_rawlist() restituisce righe il cui formato dipende dal sistema operativo del server. Il comando MLSD è stato aggiunto al protocollo FTP (RFC 3659) proprio per standardizzare questo comportamento, e ftp_mlsd() lo espone direttamente.

Usa ftp_mlsd() quando hai bisogno di:

• Enumerare i file e conoscere la dimensione, il tipo o il timestamp di ciascuno.
• Distinguere in modo affidabile le directory dai file (l'attributo type lo fa per te).
• Evitare l'analisi fragile delle stringhe che ftp_rawlist() impone.

Se hai bisogno solo di un elenco piatto di nomi di file, ftp_nlist() è più semplice. Se devi supportare server precedenti alla versione 7.2 o server senza supporto a MLSD, ricorri a ftp_rawlist().

Sintassi di ftp_mlsd()

ftp_mlsd(FTP\Connection $ftp, string $directory): array|false

La funzione accetta due parametri obbligatori:

In caso di successo restituisce un array di voci, oppure false in caso di errore (ad esempio se il percorso non esiste o il server non supporta MLSD).

Cosa restituisce ftp_mlsd()

Ogni elemento dell'array restituito è un array associativo che descrive una voce. Le chiavi esatte dipendono da ciò che riporta il server, ma quelle comuni sono:

La struttura di una singola voce è la seguente:

[
    'name'   => 'report.pdf',
    'type'   => 'file',
    'size'   => '20480',
    'modify' => '20240115093000', // 2024-01-15 09:30:00
    'perms'  => 'adfr',
]

Utilizzo di ftp_mlsd()

Prima di elencare qualsiasi cosa, ti connetti con ftp_connect() e ti autentichi con ftp_login(). Il flusso completo è il seguente:

<?php

// 1. Open a connection
$ftp = ftp_connect('ftp.example.com');

// 2. Authenticate
ftp_login($ftp, 'username', 'password');

// 3. Switch to passive mode (recommended behind firewalls/NAT)
ftp_pasv($ftp, true);

// 4. Get a structured listing of the directory
$entries = ftp_mlsd($ftp, '/public_html');

// 5. Always close the connection when done
ftp_close($ftp);

Iterazione sul listato

Il vero valore di ftp_mlsd() risiede nei dati strutturati. Qui stampiamo ogni file con una dimensione leggibile e saltiamo le pseudo-voci . e ..:

<?php

$entries = ftp_mlsd($ftp, '.');

foreach ($entries as $entry) {
    // Skip the current-dir and parent-dir markers
    if (in_array($entry['type'], ['cdir', 'pdir'], true)) {
        continue;
    }

    if ($entry['type'] === 'dir') {
        echo "[DIR]  {$entry['name']}\n";
    } else {
        $kb = round($entry['size'] / 1024, 1);
        echo "[FILE] {$entry['name']} ({$kb} KB)\n";
    }
}

Il campo modify è un timestamp a 14 cifre. Puoi convertirlo in una data reale con DateTime:

<?php

$modified = DateTime::createFromFormat('YmdHis', $entry['modify']);
echo $modified->format('Y-m-d H:i:s');

Gestione degli errori in ftp_mlsd()

ftp_mlsd() restituisce false in caso di errore, quindi controlla sempre il risultato prima di iterare — chiamare foreach su false genererebbe un avviso e non elaborerebbe nulla.

<?php

$entries = ftp_mlsd($ftp, '/path/that/may/not/exist');

if ($entries === false) {
    echo "Failed to retrieve the directory listing.\n";
} else {
    foreach ($entries as $entry) {
        echo $entry['name'] . "\n";
    }
}

Motivi comuni per cui ftp_mlsd() fallisce:

• Il server non supporta il comando MLSD (server FTP più vecchi o minimali). Ricorri a ftp_rawlist().
• Il percorso della directory è errato oppure non hai i permessi per leggerla.
• Non hai ancora effettuato l'accesso, oppure la connessione è scaduta.

ftp_mlsd() vs. altre funzioni di listaggio

Conclusione

ftp_mlsd() è il modo moderno e affidabile per elencare una directory FTP in PHP: ti fornisce un array strutturato con tipo, dimensione e data di modifica di ogni voce, risparmiandoti l'analisi fragile del testo che richiedono le funzioni più vecchie. Abbinala a ftp_connect(), ftp_login() e ftp_close() per un flusso di lavoro FTP completo e robusto — e ricorda di verificare === false prima di iterare.

Esercitazione