ftp_get_option()

Was ist ftp_get_option()?

Die Funktion ftp_get_option() ist eine in PHP integrierte Funktion, die eine einzelne Laufzeitoption einer offenen FTP-Verbindung abruft. Eine Laufzeitoption ist eine konfigurierbare Einstellung, die das Verhalten des FTP-Clients steuert — zum Beispiel, wie lange er auf einen Timeout wartet oder ob er unterbrochene Übertragungen automatisch fortsetzt. Diese Einstellungen liest man mit ftp_get_option() und ändert sie mit dem Gegenstück ftp_set_option().

Man greift typischerweise auf ftp_get_option() zurück, wenn man die aktuelle Konfiguration einer Verbindung prüfen möchte, bevor man entscheidet, was als Nächstes zu tun ist — zum Beispiel, um den aktiven Timeout zu protokollieren oder sicherzustellen, dass die automatische Fortsetzung aktiviert ist, bevor man einen großen Download startet.

Die Funktion nimmt zwei Parameter entgegen:

1. ftp — die von ftp_connect() zurückgegebene Verbindungskennung (ein FTP\Connection-Objekt in PHP 8.1+ oder eine Ressource in älteren Versionen).
2. option — die Konstante, die die abzurufende Option benennt (zum Beispiel FTP_TIMEOUT_SEC).

Die Funktion gibt je nach abgefragter Option einen gemischten Wert zurück — einen Integer für FTP_TIMEOUT_SEC oder einen boolean für die Flag-Optionen. Ist der Optionsname unbekannt, gibt PHP eine Warnung aus und die Funktion gibt false zurück.

Syntax von ftp_get_option()

Die Syntax der Funktion ftp_get_option() lautet wie folgt:

Syntax von ftp_get_option()

mixed ftp_get_option ( FTP\Connection|resource $ftp_stream , int $option )

Beide Parameter sind erforderlich. Der Parameter $ftp_stream ist die von ftp_connect() (oder ftp_ssl_connect()) zurückgegebene Verbindungskennung, und $option ist eine der vordefinierten FTP_*-Konstanten, die unten beschrieben werden.

Verfügbare Optionen in ftp_get_option()

ftp_get_option() versteht die folgenden Optionskonstanten. Der Rückgabetyp unterscheidet sich je nach Option, was beim Überprüfen des Ergebnisses wichtig ist:

Hinweis: FTP_USEPASVADDRESS ist nur im passiven Modus sinnvoll. FTP_LISTEN, das in älteren Dokumentationen auftauchen kann, ist keine gültige Option für ftp_get_option() — eine Abfrage erzeugt eine Warnung und gibt false zurück.

Verwendung von ftp_get_option()

Um die Funktion ftp_get_option() zu verwenden, muss zunächst eine Verbindung zum FTP-Server mithilfe der Funktion ftp_connect() hergestellt werden. Hier ist ein Beispiel:

Verwendung von ftp_get_option()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');

// Login with your FTP credentials
ftp_login($conn, 'username', 'password');

// Retrieve the current timeout (in seconds)
$timeout = ftp_get_option($conn, FTP_TIMEOUT_SEC);
echo "Current timeout: {$timeout} seconds\n"; // Default: 90 seconds

// Check whether passive-address rewriting is enabled
$usePasv = ftp_get_option($conn, FTP_USEPASVADDRESS);
echo "Use PASV address: " . ($usePasv ? "yes" : "no") . "\n";

// Close the FTP connection
ftp_close($conn);

In diesem Beispiel verbinden wir uns mit ftp_connect(), authentifizieren uns mit ftp_login() und lesen dann zwei Optionen aus. Der Standard-FTP_TIMEOUT_SEC einer neuen Verbindung beträgt 90, sodass die erste Zeile Current timeout: 90 seconds ausgibt. Abschließend geben wir die Verbindung mit ftp_close() frei.

Fehlerbehandlung in ftp_get_option()

Da FTP_AUTOSEEK und FTP_USEPASVADDRESS rechtmäßig den boolean-Wert false zurückgeben können, sollte das Ergebnis niemals mit einem losen == geprüft werden — ein deaktiviertes Flag würde wie ein Fehler aussehen. Verwende den strikten Identitätsoperator ===, um einen echten Fehler von einem gültigen false-Wert zu unterscheiden:

Fehlerbehandlung in ftp_get_option()

<?php

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

$timeout = ftp_get_option($conn, FTP_TIMEOUT_SEC);

if ($timeout === false) {
    // The option name was invalid, or the connection is not usable
    echo "Failed to retrieve the option.\n";
} elseif ($timeout > 0) {
    echo "Timeout is set to {$timeout} seconds.\n";
} else {
    echo "No timeout is set.\n";
}

ftp_close($conn);

Hier unterscheidet die strikte Prüfung === false einen tatsächlichen Abruffehler von einer Option, deren echter Wert zufällig 0 oder false ist. Bei boolean-Optionen wie FTP_USEPASVADDRESS speichere das Ergebnis zunächst in einer Variablen und vergleiche es dann mit ===, bevor du es als ein- oder ausgeschaltet behandelst.

Verwandte Funktionen

• ftp_set_option() — ändert eine Laufzeitoption (das Schreib-Gegenstück dieser Funktion).
• ftp_connect() — öffnet die Verbindung, auf die diese Optionen angewendet werden.
• ftp_pasv() — schaltet den passiven Modus um, der mit FTP_USEPASVADDRESS interagiert.
• PHP FTP-Übersicht — alle FTP-Funktionen auf einen Blick.

Fazit

Die Funktion ftp_get_option() ermöglicht es, die Laufzeitkonfiguration einer offenen FTP-Verbindung auszulesen — am nützlichsten für den Netzwerk-Timeout sowie die Flags für automatische Fortsetzung und passive Adresse. Da einige Optionen einen boolean zurückgeben, sollte das Ergebnis immer mit === geprüft werden, um ein gültiges false nicht mit einem Fehler zu verwechseln.

Übungen