ftp_nlist()

La funzione PHP ftp_nlist()

ftp_nlist() restituisce un array semplice dei nomi dei file e delle sottodirectory presenti in una directory su un server FTP. È l'equivalente FTP del comando nls/ls — si ottengono solo i nomi, senza informazioni su dimensione, permessi o data.

Questa pagina illustra la sintassi e i parametri, un esempio funzionante completo, l'aspetto del valore restituito, come gestire i fallimenti, le insidie più comuni (modalità passiva, nomi senza prefisso di percorso) e quando preferire ftp_rawlist().

Sintassi

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

Valore restituito: un array di nomi in caso di successo, oppure false in caso di fallimento.

I nomi restituiti non includono il prefisso della directory — l'elenco di /public_html/ restituisce index.php, non /public_html/index.php. Se la directory è vuota, si ottiene un array vuoto [], che non è la stessa cosa di false.

Un Esempio Completo

Prima di poter elencare qualsiasi cosa, è necessaria una connessione aperta e autenticata. Il flusso tipico è ftp_connect() → ftp_login() → ftp_pasv() → ftp_nlist() → ftp_close():

Utilizzo di ftp_nlist()

<?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.');
}

// Enable passive mode (often required for directory listings)
ftp_pasv($conn, true);

// Get an array of filenames in the specified directory
$files = ftp_nlist($conn, '/public_html/');

// Output the array of filenames
print_r($files);

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

Ogni passaggio è protetto: si interrompe l'esecuzione se la connessione o il login falliscono. Abilitare la modalità passiva con ftp_pasv() è importante — molti server (e la maggior parte dei firewall) la richiedono prima che un elenco di directory abbia successo, quindi una chiamata ftp_pasv() mancante è la ragione più comune per cui ftp_nlist() restituisce silenziosamente false.

Per una directory contenente due file, print_r() produrrebbe un output simile a:

Array
(
    [0] => index.php
    [1] => style.css
)

ftp_nlist() vs ftp_rawlist()

Usa la funzione più adatta alle tue esigenze:

• ftp_nlist() restituisce solo un array di nomi — perfetto per "questo file esiste?" o per iterare sui download.
• ftp_rawlist() restituisce l'output LIST grezzo e non analizzato (una stringa per riga, come ls -l), che include dimensioni, permessi e date — utile quando hai bisogno di quei metadati e sei disposto a interpretarli.

Se hai bisogno solo dei nomi, preferisci ftp_nlist(): il suo output è coerente tra i server, mentre il formato di ftp_rawlist() varia in base al tipo di server FTP.

Gestione degli Errori

È importante gestire correttamente gli errori quando si usa la funzione ftp_nlist(). Se la funzione restituisce false, significa che l'elenco non è riuscito. Nota che una directory vuota restituisce un array vuoto [], non false. Ecco un esempio di come gestire gli errori:

Gestione degli errori in ftp_nlist()

<?php

// $conn is assumed to be established from the previous example
$file_list = ftp_nlist($conn, '/public_html/');

if ($file_list === false) {
    echo "Failed to list directory on remote server.\n";
}

ftp_close($conn);

Confronta sempre con === (uguaglianza stretta). Usare un if (!$file_list) non rigoroso tratterebbe una directory legittimamente vuota ([]) come un errore, poiché un array vuoto è falsy in PHP.

Insidie Comuni

• Dimenticare la modalità passiva. Chiama ftp_pasv($conn, true) dopo il login se gli elenchi restituiscono false.
• Array vuoto vs false. [] significa "la directory esiste ma è vuota"; false significa che l'elenco è fallito. Distinguili con ===.
• I nomi non hanno percorso. Aggiungi tu stesso la directory quando hai bisogno di un percorso completo: $dir . '/' . $name.
• File nascosti. Alcuni server omettono i file con punto (.htaccess) da ftp_nlist(). Passa -a tramite l'argomento directory (es. '-a /public_html/') sui server che lo supportano.

Conclusione

ftp_nlist() è il modo più semplice per ottenere i nomi dei file in una directory remota. Abbinalo a ftp_pasv() per maggiore affidabilità, controlla il valore restituito con === e ricorri a ftp_rawlist() quando hai bisogno anche dei metadati dei file. Per il flusso FTP completo, consulta la panoramica PHP FTP.

Esercitazione