ftp_nb_get()

Die PHP-Funktion ftp_nb_get() verstehen

Die Funktion ftp_nb_get() lädt eine Datei von einem FTP-Server im nicht-blockierenden Modus herunter. Im Gegensatz zu ihrem blockierenden Pendant ftp_get(), das Ihr Skript anhält, bis die gesamte Datei übertragen wurde, gibt ftp_nb_get() die Kontrolle fast sofort an Ihr Programm zurück, sodass Sie andere Aufgaben erledigen können, während der Download im Hintergrund läuft.

Diese Seite erklärt, wann Sie die nicht-blockierende Variante verwenden sollten, geht alle Parameter und Rückgabewerte durch und zeigt ein vollständiges Arbeitsmuster mit ftp_nb_continue().

Wann sollte der nicht-blockierende Modus verwendet werden?

Das „nb" im Namen steht für non-blocking (nicht-blockierend). Greifen Sie auf ftp_nb_get() statt auf ftp_get() zurück, wenn:

• Sie Fortschritt anzeigen oder eine Benutzeroberfläche reaktionsfähig halten möchten, während eine große Datei heruntergeladen wird.
• Sie während der Übertragung andere Aufgaben ausführen müssen (Protokollierung, Heartbeats senden, bereits heruntergeladene Daten verarbeiten).
• Sie Ihre eigene Timeout- oder Abbruchlogik in der Abfrageschleife durchsetzen möchten.

Für ein einfaches „Datei herunterladen und warten" ist das normale ftp_get() einfacher und die bessere Wahl. Der Kompromiss besteht darin, dass der nicht-blockierende Modus erfordert, dass Sie die Übertragung selbst in einer Schleife mit ftp_nb_continue() steuern.

Was ist ftp_nb_get()?

Die Funktion ftp_nb_get() initiiert einen asynchronen Dateidownload. Sie benötigt vier Parameter:

1. ftp_stream: Der Verbindungsbezeichner, der von ftp_connect() zurückgegeben wird.
2. local_file: Der lokale Dateipfad, unter dem die heruntergeladene Datei gespeichert wird.
3. remote_file: Der Pfad zur Remote-Datei auf dem FTP-Server.
4. mode: Der Übertragungsmodus, entweder FTP_ASCII oder FTP_BINARY.

Außerdem wird ein optionaler fünfter Parameter resumepos akzeptiert, der die Position in der Remote-Datei angibt, von der aus der Download gestartet werden soll (Standard: 0).

Die Funktion gibt eine von drei Konstanten zurück:

Da die Funktion zurückkehren kann, bevor der Download abgeschlossen ist, wird sie fast immer mit ftp_nb_continue() in einer Schleife kombiniert, die läuft, solange das Ergebnis FTP_MOREDATA ist.

Syntax von ftp_nb_get()

Die Syntax der Funktion ftp_nb_get() lautet wie folgt:

Syntax von ftp_nb_get()

int ftp_nb_get ( resource $ftp_stream , string $local_file , string $remote_file , int $mode [, int $resumepos = 0 ] )

Die Funktion ftp_nb_get() nimmt vier erforderliche Parameter (ftp_stream, local_file, remote_file und mode) und einen optionalen Parameter (resumepos) entgegen. Der Parameter ftp_stream ist der Verbindungsbezeichner, der von ftp_connect() zurückgegeben wird. Der Parameter local_file ist der Pfad zur lokalen Datei, unter der die heruntergeladene Datei gespeichert wird. Der Parameter remote_file ist der Pfad zur Remote-Datei auf dem FTP-Server. Der Parameter mode gibt den Übertragungsmodus an, entweder FTP_ASCII oder FTP_BINARY. Der Parameter resumepos gibt die Position in der Remote-Datei an, von der aus der Download gestartet werden soll. Standardmäßig ist resumepos auf 0 gesetzt, was bedeutet, dass der Download vom Anfang der Datei beginnt.

Verwendung von ftp_nb_get()

Um die Funktion ftp_nb_get() zu verwenden, müssen Sie zunächst eine Verbindung zum FTP-Server mit ftp_connect() herstellen. Hier ist ein Beispiel:

Verwendung von ftp_nb_get()

<?php

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

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

// Initiate an asynchronous FTP operation
$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($result === FTP_FAILED) {
    echo "Failed to download file from remote server.\n";
} else {
    // Continue the asynchronous FTP operation
    while ($result === FTP_MOREDATA) {
        // Do something else while waiting for the FTP operation to complete
        $result = ftp_nb_continue($conn);
    }
}

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

In diesem Beispiel stellen wir eine Verbindung zum FTP-Server mit ftp_connect() her. Dann melden wir uns mit unseren FTP-Anmeldedaten über ftp_login() an. Wir initiieren eine asynchrone FTP-Operation mit ftp_nb_get(). Wir setzen die Operation mit ftp_nb_continue() in einer Schleife fort, die auf FTP_MOREDATA prüft, und schließen schließlich die FTP-Verbindung.

Einen unterbrochenen Download fortsetzen

Der optionale fünfte Parameter resumepos ermöglicht es Ihnen, eine teilweise heruntergeladene Datei fortzusetzen, anstatt von vorne zu beginnen. Übergeben Sie den Byte-Offset, von dem aus fortgesetzt werden soll — typischerweise die Größe der Datei, die Sie bereits auf der Festplatte haben:

Einen Download mit resumepos fortsetzen

<?php

$local = 'big-archive.zip';

// If a partial file already exists, resume from where it left off.
$resumePos = file_exists($local) ? filesize($local) : 0;

$result = ftp_nb_get($conn, $local, 'big-archive.zip', FTP_BINARY, $resumePos);

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

Dies ist besonders nützlich für große Dateien über unzuverlässige Verbindungen, bei denen Sie bereits heruntergeladene Daten nicht erneut laden möchten.

Fehlerbehandlung in ftp_nb_get()

Überprüfen Sie immer den Rückgabewert. ftp_nb_get() gibt FTP_FAILED zurück, wenn es die Übertragung nicht starten (oder fortsetzen) kann, und ftp_nb_continue() kann ebenfalls FTP_FAILED während der Übertragung zurückgeben. Behandeln Sie beides:

Fehlerbehandlung in ftp_nb_get()

<?php

$conn = ftp_connect('ftp.example.com');

if ($conn === false || !ftp_login($conn, 'username', 'password')) {
    exit("Could not connect or log in to the FTP server.\n");
}

$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

// Drive the transfer to completion, watching for failure at every step.
while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "File downloaded successfully.\n";
} else {
    echo "Failed to download file from remote server.\n";
}

ftp_close($conn);

Indem Sie die Verbindung, den Login und den Endzustand der Übertragung separat überprüfen, können Sie genau feststellen, wo ein FTP-Vorgang fehlgeschlagen ist.

Verwandte Funktionen

• ftp_get() — die blockierende Version, die eine Datei herunterlädt und auf den Abschluss wartet.
• ftp_nb_continue() — setzt eine nicht-blockierende Übertragung fort, die von ftp_nb_get() gestartet wurde.
• ftp_nb_fget() — wie ftp_nb_get(), schreibt aber in einen geöffneten Datei-Pointer statt in einen Pfad.
• ftp_connect() und ftp_login() — stellen die FTP-Sitzung her und authentifizieren sie.
• ftp_close() — schließt die Verbindung, wenn Sie fertig sind.

Fazit

Die Funktion ftp_nb_get() lädt Dateien von einem FTP-Server im nicht-blockierenden Modus herunter und ermöglicht es Ihrem Skript, reaktionsfähig zu bleiben, während eine Übertragung läuft. Kombinieren Sie sie mit ftp_nb_continue() in einer Schleife, überprüfen Sie den Rückgabewert gegen FTP_FINISHED und FTP_FAILED, und verwenden Sie resumepos, um unterbrochene Downloads fortzusetzen.

Übungen