Signatur
Beschreibung
ftp_nlist() ruft eine einfache Dateiliste vom FTP-Server ab. Im Gegensatz zu ftp_rawlist() liefert sie nur die Dateinamen (bzw. Pfade) und keine weiteren Metadaten wie Größe oder Berechtigungen. Die Funktion ist daher ideal, wenn man lediglich wissen möchte, welche Dateien oder Verzeichnisse in einem bestimmten Pfad vorhanden sind.
Der Parameter $directory kann neben einem einfachen Verzeichnisnamen auch Platzhalter (Wildcards) enthalten, z. B. /pub/*.txt, sofern der FTP-Server diese unterstützt. Bei einem leeren Verzeichnis gibt die Funktion ein leeres Array zurück; bei einem Fehler (z. B. ungültiger Pfad oder Verbindungsproblem) wird false zurückgegeben.
Intern sendet die Funktion den FTP-Befehl NLST an den Server. Die zurückgegebenen Pfade sind häufig relativ zum Verbindungs-Startpunkt oder zum angegebenen Verzeichnis – dies kann je nach FTP-Server variieren. Es empfiehlt sich daher, absolute Pfade zu verwenden.
Für Szenarien, in denen auch Metadaten wie Dateigröße oder Änderungsdatum benötigt werden, sollte stattdessen ftp_rawlist() oder ftp_mlsd() (ab PHP 7.2) eingesetzt werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $ftp Pflicht | FTP\Connection | Eine gültige FTP-Verbindungsinstanz, wie sie von ftp_connect() oder ftp_ssl_connect() zurückgegeben wird. |
|
| $directory Pflicht | string | Das Verzeichnis auf dem FTP-Server, dessen Inhalt aufgelistet werden soll. Kann ein absoluter Pfad (/pub/data), ein relativer Pfad oder ein Muster mit Wildcards (/pub/*.csv) sein. |
Rückgabewert
false zurück, wenn ein Fehler auftritt (z. B. ungültiger Pfad, fehlende Berechtigung oder Verbindungsproblem).Beispiele
Alle Dateien im FTP-Verzeichnis auflisten
<?php
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
die('Verbindung fehlgeschlagen.');
}
if (!ftp_login($ftp, 'benutzername', 'passwort')) {
die('Anmeldung fehlgeschlagen.');
}
// Passiven Modus aktivieren (oft bei NAT/Firewall nötig)
ftp_pasv($ftp, true);
$dateien = ftp_nlist($ftp, '/pub/daten');
if ($dateien === false) {
echo 'Fehler beim Abrufen der Dateiliste.';
} else {
echo 'Gefundene Dateien:' . PHP_EOL;
foreach ($dateien as $datei) {
echo ' ' . $datei . PHP_EOL;
}
}
ftp_close($ftp);
Nur CSV-Dateien mit Wildcard filtern
<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'benutzername', 'passwort');
ftp_pasv($ftp, true);
// Nur .csv-Dateien im Verzeichnis abrufen
$csvDateien = ftp_nlist($ftp, '/pub/exporte/*.csv');
if (empty($csvDateien)) {
echo 'Keine CSV-Dateien gefunden.';
} else {
echo 'CSV-Dateien:' . PHP_EOL;
foreach ($csvDateien as $csv) {
echo ' ' . basename($csv) . PHP_EOL;
}
}
ftp_close($ftp);
// Wichtig · Fallstricke
Passiver Modus: In vielen Netzwerkumgebungen mit NAT oder Firewalls schlägt die Datenübertragung im aktiven FTP-Modus fehl. Es empfiehlt sich daher, vor dem Aufruf von ftp_nlist() den passiven Modus mit ftp_pasv($ftp, true) zu aktivieren.
Serverabhängigkeit: Die zurückgegebenen Pfade können je nach FTP-Server-Software unterschiedlich formatiert sein – manche liefern vollständige absolute Pfade, andere nur relative Dateinamen. Verlasse dich daher nicht blind auf das Format und nutze ggf. basename() zur Extraktion des reinen Dateinamens.
Wildcard-Unterstützung: Nicht alle FTP-Server unterstützen Wildcard-Muster im NLST-Befehl. Bei fehlender Unterstützung gibt die Funktion möglicherweise false oder ein leeres Array zurück, obwohl Dateien vorhanden sind.
PHP 8.1: Ab PHP 8.1 ist der Typ der FTP-Verbindung FTP\Connection statt der zuvor verwendeten Ressource.