ftp_set_option()

Die Funktion ftp_set_option() konfiguriert das Laufzeitverhalten einer bereits geöffneten FTP-Verbindung in PHP. Sie ermöglicht es, das Verhalten des FTP-Clients anzupassen — Verbindungs-Timeouts, Passive-Mode-Adressierung und ob Downloads beim Fortsetzen automatisch gesucht werden — ohne die Verbindung zu trennen und neu aufzubauen.

Diese Seite erklärt, was jede Option bewirkt, wann Sie sie verwenden sollten und wie die Optionen sicher gesetzt werden. Es wird davon ausgegangen, dass Sie bereits eine Verbindung über ftp_connect() (oder ftp_ssl_connect()) geöffnet und sich mit ftp_login() angemeldet haben.

Syntax

ftp_set_option(FTP\Connection $ftp, int $option, mixed $value): bool

Die Funktion gibt true bei Erfolg zurück oder false, wenn die Option nicht gesetzt werden konnte (z. B. wenn $value den falschen Typ für die gewählte $option hat).

Hinweis: In PHP 8.1+ ist das erste Argument ein FTP\Connection-Objekt. In PHP 8.0 und früher ist es eine resource, die von ftp_connect() zurückgegeben wird. Funktionsname und Verhalten sind ansonsten identisch.

Grundlegende Verwendung

Öffnen Sie eine Verbindung, melden Sie sich an und setzen Sie dann die Option. Das Setzen von Optionen erfolgt üblicherweise direkt nach dem Login, bevor Sie mit der Übertragung von Dateien beginnen, damit jede Übertragung das neue Verhalten verwendet.

<?php

// Open a connection to the FTP server
$ftp = ftp_connect('ftp.example.com');

if (!$ftp) {
    die('Could not connect to FTP server.');
}

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

// Abort any network operation that stalls for more than 30 seconds
ftp_set_option($ftp, FTP_TIMEOUT_SEC, 30);

// ... transfers happen here ...

ftp_close($ftp);

Hier verbinden wir uns mit ftp_connect(), authentifizieren uns mit ftp_login(), senken das Netzwerk-Timeout mit ftp_set_option() auf 30 Sekunden und schließen schließlich die Verbindung mit ftp_close().

Verfügbare Optionen

ftp_set_option() akzeptiert die folgenden Optionskonstanten:

FTP_TIMEOUT_SEC und FTP_USEPASVADDRESS sind die beiden, die Sie im echten Code am häufigsten anpassen: Ersteres bei Timeout-Fehlern bei Übertragungen, Letzteres wenn der Passive-Modus hinter einer Firewall fehlschlägt.

Den aktuellen Wert einer dieser Optionen können Sie mit ftp_get_option() auslesen.

Auto-Seek deaktivieren

Ein häufiger Grund für den Aufruf von ftp_set_option() ist das Deaktivieren von FTP_AUTOSEEK. Standardmäßig sucht das Fortsetzen eines Downloads mit einem Offset ungleich null die lokale Datei. Wenn jeder Download ab Byte null überschreiben soll, deaktivieren Sie es:

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');

// Force full transfers instead of resuming from an offset
ftp_set_option($ftp, FTP_AUTOSEEK, false);

ftp_close($ftp);

Fehlerbehandlung

ftp_set_option() gibt false zurück (und gibt eine Warnung aus), wenn der Wert nicht zur Option passt — zum Beispiel wenn ein string übergeben wird, wo ein int erwartet wird. Prüfen Sie den Rückgabewert, damit eine stillschweigend ignorierte Option Sie nicht später überrascht:

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');

if (!ftp_set_option($ftp, FTP_TIMEOUT_SEC, 30)) {
    echo "Failed to set the FTP timeout option.\n";
}

ftp_close($ftp);

Arbeiten Sie stets mit einer aktiven Verbindung: Das Übergeben einer geschlossenen oder ungültigen Verbindung erzeugt eine Warnung statt eines sauberen false, also setzen Sie Ihre Optionen, bevor Sie ftp_close() aufrufen.

Fazit

ftp_set_option() passt das Verhalten einer offenen FTP-Verbindung an — am nützlichsten bei Netzwerk-Timeouts und der Behandlung von Passive-Mode-Adressen hinter NAT. Setzen Sie Optionen unmittelbar nach ftp_login(), prüfen Sie den Rückgabewert und verwenden Sie ftp_get_option(), um zu bestätigen, was aktuell in Kraft ist. Einen vollständigen FTP-Workflow finden Sie in der PHP FTP-Übersicht.

Übung