ftp_pasv()

Die PHP-Funktion ftp_pasv()

Die Funktion ftp_pasv() aktiviert oder deaktiviert den passiven Modus für eine offene FTP-Verbindung. Der passive Modus bestimmt, welche Seite den Datenkanal öffnet – und die richtige Einstellung ist die häufigste Lösung, wenn FTP-Downloads und Verzeichnisauflistungen hängen oder eine Zeitüberschreitung auftreten. Dieses Kapitel erklärt, was der passive Modus ist, wann er benötigt wird und wie ftp_pasv() korrekt in einem echten Übertragungsskript aufgerufen wird.

Aktiver vs. passiver Modus

FTP verwendet zwei separate Kanäle: einen Befehlskanal (für Befehle wie LIST, RETR usw.) und einen Datenkanal (über den die eigentlichen Datei-Bytes oder Verzeichnislistungen übertragen werden). Die beiden Modi unterscheiden sich nur darin, wer den Datenkanal öffnet:

• Aktiver Modus (Protokoll-Standard): Der Server öffnet die Datenverbindung zurück zum Client. Befindet sich der Client hinter einer Firewall oder einem NAT-Router, wird diese eingehende Verbindung in der Regel blockiert, sodass die Übertragung stoppt.
• Passiver Modus: Der Client öffnet beide Kanäle zum Server. Da der Client ausschließlich ausgehende Verbindungen herstellt, funktioniert dies mit nahezu jeder Firewall- oder NAT-Konfiguration.

Daher ist der passive Modus für die meisten modernen Skripte die sichere Standardwahl: Clients befinden sich fast immer hinter NAT, während Server unter einer öffentlichen Adresse erreichbar sind.

Syntax

ftp_pasv(FTP\Connection $ftp, bool $passive): bool

• $ftp — die von ftp_connect() zurückgegebene FTP-Verbindung. Ab PHP 8.1 handelt es sich um ein FTP\Connection-Objekt; in PHP 8.0 und früher war es eine Ressource. Vorhandener Code funktioniert in beiden Fällen weiterhin.
• $passive — true, um den passiven Modus zu aktivieren; false, um zurück in den aktiven Modus zu wechseln.

Die Funktion gibt bei Erfolg true und bei einem Fehler false zurück.

Die Reihenfolge ist entscheidend: Rufen Sie ftp_pasv() nach ftp_login() und vor jeder Übertragung wie ftp_get(), ftp_put() oder ftp_nlist() auf. Ein Aufruf vor dem Login schlägt fehl, da der passive Modus innerhalb einer authentifizierten Sitzung ausgehandelt wird.

Eine vollständige Übertragung im passiven Modus

Das folgende Beispiel stellt eine Verbindung her, meldet sich an, wechselt in den passiven Modus, lädt eine Datei herunter und schließt die Verbindung. Jeder Schritt prüft seinen Rückgabewert, damit Fehler gemeldet werden anstatt stillschweigend ignoriert zu werden.

<?php

// 1. Connect to the FTP server (30-second timeout)
$ftp = ftp_connect('ftp.example.com', 21, 30);
if (!$ftp) {
    die("Could not connect to the FTP server.\n");
}

// 2. Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    ftp_close($ftp);
    die("FTP login failed.\n");
}

// 3. Switch to passive mode — must come after login, before any transfer
if (!ftp_pasv($ftp, true)) {
    ftp_close($ftp);
    die("Could not switch to passive mode.\n");
}

// 4. Download a file now that the data channel will be client-initiated
if (ftp_get($ftp, 'local-copy.txt', 'remote/report.txt', FTP_BINARY)) {
    echo "File downloaded successfully.\n";
} else {
    echo "File download failed.\n";
}

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

Ohne die Zeile ftp_pasv($ftp, true) würde Schritt 4 hinter einem NAT-Router häufig hängen, weil der Server die eingehende Datenverbindung nicht öffnen könnte.

Fehlerbehandlung

ftp_pasv() gibt false zurück, wenn der Server die Modusänderung ablehnt oder die Verbindung nicht mehr gültig ist. Prüfen Sie den Rückgabewert stets, bevor Sie eine Übertragung starten, und verwenden Sie ftp_close(), um die Verbindung auf jedem Ausführungspfad freizugeben:

<?php

if (!ftp_pasv($ftp, true)) {
    echo "Failed to enable passive mode on the remote server.\n";
    ftp_close($ftp);
    return; // stop before attempting a transfer that would stall
}

Wann stattdessen aktiver Modus verwendet werden sollte

Der passive Modus eignet sich für die meisten Clients, aber einige Situationen erfordern den aktiven Modus (ftp_pasv($ftp, false)):

• Der passive Portbereich des Servers ist durch eine Firewall gesperrt, sodass passive Datenverbindungen abgelehnt werden, während aktive erfolgreich sind.
• Sie stellen eine Verbindung von einem Host mit öffentlicher IP-Adresse ohne eingehende Einschränkungen her und kommunizieren mit einem Server, der nur aktive Übertragungen erlaubt.

Wenn eine Übertragung hängt, ist das Umschalten des Modus das Erste, was man versuchen sollte – viele Meldungen „FTP funktioniert nicht" sind schlicht auf den falschen Modus für das Netzwerk zurückzuführen.

Fazit

ftp_pasv() legt fest, ob der Client oder der Server den FTP-Datenkanal öffnet. Aktivieren Sie es (true) für Clients hinter Firewalls oder NAT – was meistens der Fall ist – und rufen Sie es direkt nach ftp_login() und vor jeder Übertragung auf. Das Prüfen des Rückgabewerts und das Schließen der Verbindung mit ftp_close() sorgen dafür, dass Ihre FTP-Skripte in verschiedenen Netzwerkumgebungen zuverlässig funktionieren.

Übungen