ftp_nb_fput()

Die PHP-Funktion ftp_nb_fput() verstehen

Die Funktion ftp_nb_fput() ist eine eingebaute PHP-Funktion, die eine Datei im nicht-blockierenden Modus auf einen FTP-Server hochlädt. „Nicht-blockierend" bedeutet, dass die Funktion die Kontrolle an Ihr Skript zurückgibt, bevor die Übertragung abgeschlossen ist, sodass Sie während des laufenden Uploads anderen Code ausführen können (z. B. einen Fortschrittsbalken aktualisieren oder eine andere Aufgabe verarbeiten). Dieser Artikel erläutert die Parameter, Rückgabewerte und ein vollständiges Arbeitsmuster für die Verwendung in Ihren PHP-Projekten.

Das blockierende Gegenstück ist ftp_fput(), das einfach wartet, bis die gesamte Datei hochgeladen wurde. Verwenden Sie ftp_nb_fput() nur, wenn Sie während der Übertragung andere Arbeiten erledigen müssen.

Was ist ftp_nb_fput()?

Die Funktion ftp_nb_fput() lädt eine Datei im nicht-blockierenden Modus auf einen FTP-Server hoch. Sie akzeptiert vier Pflichtparameter und einen optionalen Parameter:

1. ftp_stream: Die Verbindungskennung, die von ftp_connect() zurückgegeben wird.
2. remote_file: Der Pfad zur Remote-Datei auf dem FTP-Server.
3. handle: Ein geöffneter Dateizeiger auf die lokale Datei.
4. mode: Der Übertragungsmodus, entweder FTP_ASCII oder FTP_BINARY.
5. startpos (optional): Die Position in der Remote-Datei, ab der der Upload beginnen soll. Standardwert ist 0.

Die Funktion gibt eine der folgenden Konstanten zurück: FTP_SUCCESS (Upload abgeschlossen), FTP_MOREDATA (es müssen noch mehr Daten gelesen werden) oder FTP_FAILED (ein Fehler ist aufgetreten).

Syntax von ftp_nb_fput()

Die Syntax der Funktion ftp_nb_fput() lautet wie folgt:

int ftp_nb_fput ( resource $ftp_stream , string $remote_file , resource $handle , int $mode [, int $startpos = 0 ] )

Die Funktion nimmt vier Pflichtparameter (ftp_stream, remote_file, handle und mode) sowie einen optionalen Parameter (startpos) entgegen. Der Parameter ftp_stream ist die Verbindungskennung, die von ftp_connect() zurückgegeben wird. Der Parameter remote_file ist der Pfad zur Remote-Datei auf dem FTP-Server. Der Parameter handle ist ein geöffneter Dateizeiger im lokalen Dateisystem. Der Parameter mode gibt den Übertragungsmodus an, entweder FTP_ASCII oder FTP_BINARY. Der Parameter startpos gibt die Position in der Remote-Datei an, ab der der Upload beginnen soll. Standardmäßig ist startpos auf 0 gesetzt, was bedeutet, dass der Upload am Anfang der Datei beginnt.

Verwendung von ftp_nb_fput()

Um die Funktion ftp_nb_fput() zu verwenden, müssen Sie zunächst eine Verbindung zum FTP-Server mit der Funktion ftp_connect() 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');

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

// Enable passive mode to prevent transfer issues
ftp_pasv($conn, true);

// Open a file for reading
$handle = fopen('local_file.txt', 'r');

// Initiate an asynchronous FTP operation
$res = ftp_nb_fput($conn, 'remote_file.txt', $handle, FTP_BINARY);

// Continue the asynchronous FTP operation
while ($res == FTP_MOREDATA) {
    $res = ftp_nb_continue($conn);
}

// Check for errors
if ($res != FTP_FAILED && $res != FTP_SUCCESS) {
    echo "FTP upload failed.\n";
}

// Close the file
fclose($handle);

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

In diesem Beispiel stellen wir eine Verbindung zum FTP-Server her, melden uns mit unseren Zugangsdaten an und aktivieren den passiven Modus mit ftp_pasv(), um häufige Übertragungsprobleme hinter Firewalls zu verhindern. Wir öffnen die lokale Datei zum Lesen und rufen dann ftp_nb_fput() auf, um den Upload zu starten. Das entscheidende Detail ist die while-Schleife: Solange ftp_nb_fput() (oder die nachfolgenden Aufrufe) FTP_MOREDATA zurückgibt, halten wir die Übertragung mit ftp_nb_continue() am Laufen. In einer echten Anwendung ist jede Iteration dieser Schleife der Punkt, an dem Sie andere Arbeiten erledigen könnten, da die Übertragung nicht-blockierend ist.

Fehlerbehandlung in ftp_nb_fput()

Es ist wichtig, Fehler bei der Verwendung der Funktion ftp_nb_fput() ordnungsgemäß zu behandeln. Die Funktion gibt spezifische Konstanten statt eines boolean-Werts zurück, daher müssen Sie auf FTP_FAILED prüfen, um Fehler zu erkennen. Hier ist ein Beispiel für die Fehlerbehandlung:

<?php

// Assume $conn is already established and logged in
$handle = fopen('local_file.txt', 'r');
$res = ftp_nb_fput($conn, 'remote_file.txt', $handle, FTP_BINARY);

if ($res == FTP_FAILED) {
    echo "Failed to initiate upload.\n";
}

while ($res == FTP_MOREDATA) {
    $res = ftp_nb_continue($conn);
}

if ($res == FTP_FAILED) {
    echo "Failed to complete upload.\n";
}

fclose($handle);
ftp_close($conn);

Indem Sie Fehler angemessen behandeln und die Rückgabekonstanten sowohl von ftp_nb_fput() als auch von ftp_nb_continue() überprüfen, können Sie den Erfolg Ihrer FTP-Operationen sicherstellen.

ftp_nb_fput() im Vergleich zu verwandten Funktionen

PHP bietet mehrere FTP-Upload-Funktionen. Die richtige Wahl hängt davon ab, ob Sie einen offenen Datei-Handle oder nur einen Pfad haben und ob Sie nicht-blockierendes Verhalten benötigen:

• ftp_fput() — lädt von einem offenen Datei-Handle hoch, blockierend bis zum Abschluss.
• ftp_put() — lädt von einem lokalen Dateipfad hoch, blockierend bis zum Abschluss.
• ftp_nb_put() — nicht-blockierender Upload von einem lokalen Dateipfad (gleiche Schleifenstruktur wie diese Funktion).
• ftp_nb_fput() — nicht-blockierender Upload von einem offenen Datei-Handle (diese Funktion).

Alle nicht-blockierenden Varianten verwenden dasselbe Muster mit FTP_MOREDATA / ftp_nb_continue().

Fazit

Die Funktion ftp_nb_fput() lädt eine Datei im nicht-blockierenden Modus auf einen FTP-Server hoch und ermöglicht es Ihrem Skript, während der laufenden Übertragung weiter andere Operationen auszuführen. Das wesentliche Muster ist: Upload starten, dann mit ftp_nb_continue() in einer Schleife iterieren, solange der Rückgabewert FTP_MOREDATA ist, und bei jedem Schritt auf FTP_FAILED prüfen. Richtig eingesetzt verbessert es die Reaktionsfähigkeit von Dateiübertragungscode in Ihren PHP-Projekten.

Übungen