ftp_set_option — Funktion · PHP-Referenz

Signatur

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

Beschreibung

ftp_set_option() erlaubt es, verschiedene Verhaltensparameter einer aktiven FTP-Verbindung zur Laufzeit zu konfigurieren. Die Funktion wird nach dem Verbindungsaufbau mit ftp_connect() bzw. ftp_ssl_connect() aufgerufen, um das Verhalten der Verbindung gezielt anzupassen.

Zu den wichtigsten konfigurierbaren Optionen gehören der Verbindungs-Timeout (FTP_TIMEOUT_SEC), der automatische Wechsel in den passiven Modus bei NAT-Szenarien (FTP_AUTOSEEK) sowie das automatische Setzen der Dateiposition beim Fortsetzen von Übertragungen. Die Optionen werden über vordefinierte Konstanten ausgewählt.

Der passive Modus kann alternativ direkt mit ftp_pasv() gesetzt werden, jedoch ist ftp_set_option() die bevorzugte Methode für Timeout-Anpassungen. Besonders bei langsamen Verbindungen oder großen Dateiübertragungen ist ein angepasster Timeout essentiell, um vorzeitige Verbindungsabbrüche zu vermeiden.

FTP_TIMEOUT_SEC – Zeitlimit in Sekunden für FTP-Netzwerkoperationen (Standard: 90).
FTP_AUTOSEEK – Aktiviert/deaktiviert automatisches Seeked bei Dateiübertragungen mit Offset (true/false).
FTP_USEPASVADDRESS – Steuert, ob die vom Server im PASV-Befehl zurückgegebene IP-Adresse verwendet wird (true/false).

Parameter

Name	Typ	Beschreibung
$ftp Pflicht	FTP\Connection	Eine aktive FTP-Verbindungsressource, wie sie von `ftp_connect()` oder `ftp_ssl_connect()` zurückgegeben wird.
$option Pflicht	int	Die zu setzende Option. Gültige Werte sind die Konstanten `FTP_TIMEOUT_SEC`, `FTP_AUTOSEEK` und `FTP_USEPASVADDRESS`.
$value Pflicht	mixed	Der neue Wert der Option. Für `FTP_TIMEOUT_SEC` ein positiver `int`-Wert in Sekunden; für `FTP_AUTOSEEK` und `FTP_USEPASVADDRESS` ein `bool`-Wert.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Option erfolgreich gesetzt wurde, andernfalls false – etwa wenn eine unbekannte Option oder ein ungültiger Wert übergeben wurde.

Beispiele

Timeout erhöhen für große Dateiübertragungen

<?php
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
    die('Verbindung fehlgeschlagen.');
}

if (ftp_login($ftp, 'benutzer', 'passwort')) {
    // Timeout auf 300 Sekunden erhöhen
    if (ftp_set_option($ftp, FTP_TIMEOUT_SEC, 300)) {
        echo 'Timeout erfolgreich auf 300 Sekunden gesetzt.' . PHP_EOL;
    } else {
        echo 'Fehler beim Setzen des Timeouts.' . PHP_EOL;
    }

    // Große Datei übertragen
    ftp_get($ftp, '/tmp/grossedatei.zip', '/remote/grossedatei.zip', FTP_BINARY);
}

ftp_close($ftp);

Timeout erfolgreich auf 300 Sekunden gesetzt.

FTP_USEPASVADDRESS deaktivieren für NAT-Umgebungen

<?php
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
    die('Verbindung fehlgeschlagen.');
}

if (ftp_login($ftp, 'benutzer', 'passwort')) {
    // Passiven Modus aktivieren
    ftp_pasv($ftp, true);

    // Server-IP aus PASV-Antwort ignorieren (nützlich hinter NAT/Firewall)
    if (ftp_set_option($ftp, FTP_USEPASVADDRESS, false)) {
        echo 'USEPASVADDRESS deaktiviert – Client-seitige IP wird verwendet.' . PHP_EOL;
    }

    $dateien = ftp_nlist($ftp, '/');
    if ($dateien !== false) {
        foreach ($dateien as $datei) {
            echo $datei . PHP_EOL;
        }
    }
}

ftp_close($ftp);

USEPASVADDRESS deaktiviert – Client-seitige IP wird verwendet.

// Wichtig · Fallstricke

PHP 8.1+: Der Typ des ersten Parameters wurde von resource auf FTP\Connection geändert. Code, der noch auf resource-Typisierung prüft, muss angepasst werden.

Wird ein ungültiger Wert für FTP_TIMEOUT_SEC übergeben (z. B. 0 oder ein negativer Wert), gibt die Funktion false zurück und der Timeout bleibt unverändert. Gültig sind nur positive Ganzzahlen.

Das Deaktivieren von FTP_USEPASVADDRESS ist besonders in Cloud- oder Docker-Umgebungen sinnvoll, in denen der FTP-Server eine interne IP-Adresse im PASV-Befehl zurückliefert, die vom Client nicht erreichbar ist.

Siehe auch

ftp_get_option ftp_connect ftp_ssl_connect ftp_pasv ftp_login