ftp_nlist()

Die PHP-Funktion ftp_nlist()

ftp_nlist() gibt ein flaches Array der Namen der Dateien und Unterverzeichnisse in einem Verzeichnis auf einem FTP-Server zurück. Sie entspricht dem FTP-Äquivalent des nls/ls-Befehls — man erhält nur die Namen, ohne Größen-, Berechtigungs- oder Datumsinformationen.

Diese Seite behandelt die Syntax und Parameter, ein vollständiges Beispiel, wie der Rückgabewert aussieht, die Fehlerbehandlung, typische Fallstricke (Passivmodus, Namen ohne Pfadpräfix) und wann stattdessen ftp_rawlist() verwendet werden sollte.

Syntax

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

Rückgabewert: bei Erfolg ein Array von Namen, bei Fehler false.

Die zurückgegebenen Namen enthalten kein Verzeichnispräfix — das Auflisten von /public_html/ liefert index.php, nicht /public_html/index.php. Wenn das Verzeichnis leer ist, wird ein leeres array [] zurückgegeben, was nicht dasselbe ist wie false.

Ein vollständiges Beispiel

Bevor man etwas auflisten kann, braucht man eine offene, authentifizierte Verbindung. Der typische Ablauf ist ftp_connect() → ftp_login() → ftp_pasv() → ftp_nlist() → ftp_close():

Verwendung von 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);

Jeder Schritt ist abgesichert: Wir brechen ab, wenn die Verbindung oder der Login fehlschlägt. Das Aktivieren des Passivmodus mit ftp_pasv() ist wichtig — viele Server (und die meisten Firewalls) erfordern dies, bevor eine Verzeichnisauflistung gelingt. Daher ist ein fehlender ftp_pasv()-Aufruf der häufigste Grund, warum ftp_nlist() stillschweigend false zurückgibt.

Für ein Verzeichnis mit zwei Dateien würde print_r() etwa Folgendes ausgeben:

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

ftp_nlist() vs ftp_rawlist()

Verwende die Funktion, die deinen Anforderungen entspricht:

• ftp_nlist() gibt nur ein array von Namen zurück — ideal für „Existiert diese Datei?" oder das Iterieren über Downloads.
• ftp_rawlist() gibt die rohe, ungeparste LIST-Ausgabe zurück (ein string pro Zeile, wie bei ls -l), die Größen, Berechtigungen und Daten enthält — nützlich, wenn man diese Metadaten benötigt und bereit ist, sie zu parsen.

Wenn nur Namen benötigt werden, ist ftp_nlist() zu bevorzugen: Die Ausgabe ist über verschiedene Server hinweg konsistent, während das Format von ftp_rawlist() je nach FTP-Server-Typ variiert.

Fehlerbehandlung

Es ist wichtig, Fehler bei der Verwendung der Funktion ftp_nlist() korrekt zu behandeln. Wenn die Funktion false zurückgibt, bedeutet dies, dass die Auflistung fehlgeschlagen ist. Beachte, dass ein leeres Verzeichnis ein leeres array [] zurückgibt, nicht false. Hier ist ein Beispiel für die Fehlerbehandlung:

Fehlerbehandlung 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);

Vergleiche immer mit === (strikte Gleichheit). Bei Verwendung von if (!$file_list) würde ein legitim leeres Verzeichnis ([]) als Fehler behandelt werden, da ein leeres array in PHP als falsy gilt.

Häufige Fallstricke

• Vergessener Passivmodus. Rufe ftp_pasv($conn, true) nach dem Login auf, wenn Auflistungen false zurückgeben.
• Leeres array vs false. [] bedeutet „Verzeichnis existiert, ist aber leer"; false bedeutet, dass die Auflistung fehlgeschlagen ist. Unterscheide beide mit ===.
• Namen ohne Pfad. Hänge das Verzeichnis selbst voran, wenn ein vollständiger Pfad benötigt wird: $dir . '/' . $name.
• Versteckte Dateien. Einige Server lassen Dot-Dateien (.htaccess) bei ftp_nlist() weg. Übergebe -a über das Verzeichnisargument (z. B. '-a /public_html/') auf Servern, die dies unterstützen.

Fazit

ftp_nlist() ist die einfachste Möglichkeit, die Namen von Dateien in einem entfernten Verzeichnis abzurufen. Kombiniere sie mit ftp_pasv() für Zuverlässigkeit, überprüfe den Rückgabewert mit === und greife auf ftp_rawlist() zurück, wenn du auch Datei-Metadaten benötigst. Für den vollständigen FTP-Workflow, siehe die Übersicht PHP FTP.

Übungen