ftp_raw()

Die PHP-Funktion ftp_raw() verstehen

Die Funktion ftp_raw() ist eine eingebaute PHP-Funktion, die einen beliebigen Befehl direkt an einen FTP-Server sendet und die rohe, nicht geparste Antwort des Servers zurückgibt. Anders als die übergeordneten FTP-Hilfsfunktionen interpretiert ftp_raw() das Ergebnis nicht für Sie — sie liefert genau das zurück, was der Server gesendet hat, Zeile für Zeile. Diese Seite erklärt, was die Funktion tut, wann Sie sie tatsächlich benötigen und wie Sie sie sicher einsetzen.

Was ist ftp_raw()?

FTP ist ein textbasiertes Protokoll: Clients senden kurze Befehle wie SYST, PWD oder FEAT, und der Server antwortet mit nummerierten Statuszeilen (zum Beispiel 215 UNIX Type: L8). Die meisten PHP-FTP-Funktionen — wie ftp_nlist(), ftp_get() und ftp_systype() — kapseln einen dieser Befehle und parsen die Antwort zu einem praktischen Wert. ftp_raw() überspringt das Parsen und legt das Protokoll direkt offen.

Sie nimmt zwei Parameter entgegen:

1. ftp_stream — der Verbindungsbezeichner, der von ftp_connect() zurückgegeben wird.
2. command — der zu sendende FTP-Befehlsstring (zum Beispiel 'SYST' oder 'PWD').

Bei Erfolg gibt sie ein array von Strings zurück, ein Element pro Antwortzeile, das die Serverantwort enthält. Bei einem Fehler (zum Beispiel eine ungültige Verbindung) gibt sie false zurück.

Wann sollten Sie sie verwenden?

Für alltägliche Aufgaben — Auflisten, Hochladen, Herunterladen — bevorzugen Sie die dedizierten Funktionen; sie kümmern sich um Datenverbindungen und das Parsen. Greifen Sie auf ftp_raw() nur zurück, wenn:

• Sie einen Befehl benötigen, für den PHP keinen Wrapper hat (zum Beispiel FEAT zum Entdecken von Server-Features oder eine benutzerdefinierte SITE-Direktive).
• Sie debuggen und die genaue Statuszeile sehen möchten, die der Server zurückgibt.
• Sie Protokollverhalten implementieren, das die übergeordnete API nicht bereitstellt.

Beachten Sie, dass ftp_raw() ausschließlich für Steuerkanal-Befehle gedacht ist. Es können keine Dateidaten übertragen werden — Befehle wie RETR oder LIST benötigen eine separate Datenverbindung, weshalb Sie für diese stattdessen ftp_get() oder ftp_nlist() verwenden.

Häufige Raw-Befehle

Syntax von ftp_raw()

Die Signatur der Funktion ftp_raw() lautet wie folgt:

ftp_raw(FTP\Connection $ftp, string $command): array

Der Parameter $ftp ist die Verbindung, die von ftp_connect() zurückgegeben wird, und $command ist der zu sendende Befehlsstring. Beide sind erforderlich.

Verwendung von ftp_raw()

Um die Funktion ftp_raw() zu verwenden, müssen Sie zunächst mit ftp_connect() eine Verbindung zum FTP-Server herstellen und sich mit ftp_login() authentifizieren. Hier ist ein vollständiges Beispiel:

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die("Could not connect to FTP server.\n");
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die("Login failed.\n");
}

// Ask the server what operating system it runs
$response = ftp_raw($conn, 'SYST');

// Output the server's raw response, one line per element
echo "Server response: " . implode("\n", $response) . "\n";
// e.g. Server response: 215 UNIX Type: L8

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

Hier verbinden wir uns mit ftp_connect() und überprüfen, ob die Verbindung erfolgreich war, authentifizieren uns mit ftp_login(), senden den Befehl SYST mit ftp_raw() und geben jede Antwortzeile aus. Die 215 ist der FTP-Antwortcode; der Text danach ist die Antwort des Servers. Abschließend geben wir die Verbindung mit ftp_close() frei.

Fehlerbehandlung in ftp_raw()

Prüfen Sie immer den Rückgabewert, bevor Sie ihn verwenden. ftp_raw() gibt false zurück, wenn der Befehl nicht gesendet werden kann (zum Beispiel weil die Verbindung nicht mehr gültig ist). Dieses Ergebnis direkt in implode() zu übergeben, würde einen Typfehler auslösen. Schützen Sie sich dagegen:

<?php

$response = ftp_raw($conn, 'SYST');

if ($response === false) {
    echo "Failed to send the raw command to the FTP server.\n";
} else {
    echo implode("\n", $response) . "\n";
}

ftp_close($conn);

Beachten Sie, dass ein nicht-falsches array nicht garantiert, dass der Befehl selbst erfolgreich war — es bedeutet nur, dass der Server geantwortet hat. Überprüfen Sie den Antwortcode (die führende Zahl in jeder Zeile, zum Beispiel 5xx bei Fehlern), wenn Sie wissen müssen, ob der Befehl akzeptiert wurde.

Fazit

Die Funktion ftp_raw() gibt Ihnen direkten Zugriff auf den FTP-Steuerkanal, was für Befehle, die PHP nicht kapselt (wie FEAT), und zum Debuggen unschätzbar ist. Für routinemäßiges Auflisten, Hochladen und Herunterladen greifen Sie stattdessen auf die dedizierten Funktionen zurück. Die vollständige Übersicht finden Sie in der PHP-FTP-Funktionsreferenz.

Übungen