ftp_nb_put()

Die PHP-Funktion ftp_nb_put() verstehen

Die Funktion ftp_nb_put() ist eine eingebaute PHP-Funktion, die eine Datei im nicht-blockierenden Modus auf einen FTP-Server hochlädt. „Nicht-blockierend" bedeutet, dass der Aufruf sofort nach dem Start der Übertragung zurückkehrt, anstatt auf deren Abschluss zu warten – so kann Ihr Skript weiterarbeiten, während Bytes über die Leitung übertragen werden. Dieser Leitfaden behandelt Parameter, Syntax, Verwendung und Fehlerbehandlung, damit Sie die Funktion effektiv in Ihre PHP-Projekte integrieren können.

Das Gegenstück zu dieser Funktion ist ftp_put(), das im blockierenden Modus hochlädt (das Skript pausiert, bis der Upload abgeschlossen ist). Verwenden Sie ftp_nb_put(), wenn Sie eine große Datei hochladen und dabei den Fortschritt anzeigen, andere Aufgaben verarbeiten oder lange, eingefrorene Anfragen vermeiden möchten.

Was ist ftp_nb_put()?

Die Funktion ftp_nb_put() lädt eine Datei auf einen FTP-Server hoch, ohne die Skriptausführung anzuhalten. Sie akzeptiert folgende Parameter:

1. ftp_stream: Der Verbindungsbezeichner, der von ftp_connect() zurückgegeben wird (ein FTP\Connection-Objekt ab PHP 8.1+).
2. remote_file: Der Remote-Dateipfad, unter dem die Datei hochgeladen wird.
3. local_file: Der lokale Dateipfad, aus dem gelesen wird.
4. mode: Der Übertragungsmodus, entweder FTP_BINARY oder FTP_ASCII (vor PHP 7.3 erforderlich; ab 7.3 optional mit Standardwert FTP_BINARY).
5. startpos (optional): Der Byte-Offset in der Remote-Datei, ab dem geschrieben wird; Standard ist 0.

Im Gegensatz zu einem blockierenden Upload gibt ftp_nb_put() kein einfaches true/false zurück. Stattdessen gibt sie eine von drei Integer-Konstanten zurück:

Aufgrund dieser Rückgabewerte wird ftp_nb_put() fast immer zusammen mit ftp_nb_continue() in einer Schleife verwendet, wie unten gezeigt.

Syntax von ftp_nb_put()

Die Syntax der Funktion ftp_nb_put() lautet wie folgt:

Syntax von ftp_nb_put()

int ftp_nb_put ( FTP\Connection $ftp_stream , string $remote_file , string $local_file , int $mode [, int $startpos = 0 ] )

Die Funktion ftp_nb_put() nimmt drei erforderliche Parameter (ftp_stream, remote_file und local_file) und einen optionalen Parameter (startpos) entgegen. Der Parameter mode ist erforderlich und gibt den Übertragungsmodus an: FTP_BINARY wird für die meisten Dateien (Bilder, Archive, ausführbare Dateien) empfohlen, um Zeilenende-Verfälschungen zu verhindern, während FTP_ASCII für reine Textdateien verwendet wird (wobei FTP_BINARY generell sicherer für alle Dateitypen ist). 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 vom Anfang der Datei beginnt.

Verwendung von ftp_nb_put()

Um die Funktion ftp_nb_put() zu verwenden, stellen Sie zunächst eine Verbindung mit ftp_connect() her und authentifizieren sich mit ftp_login(). Anschließend starten Sie den Upload und treiben ihn in einer Schleife voran, bis er abgeschlossen ist:

Verwendung von ftp_nb_put()

<?php

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

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

// Initiate an asynchronous FTP operation
$result = ftp_nb_put($conn, 'remote_file.txt', 'local_file.txt', FTP_BINARY);
if ($result === FTP_FAILED) {
    die('Upload failed.');
}

// 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);
}

if ($result === FTP_FINISHED) {
    echo "Upload completed successfully.\n";
}

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

In diesem Beispiel verbinden wir uns mit dem FTP-Server, melden uns mit unseren Zugangsdaten an und starten den Upload mit ftp_nb_put(). Der erste Aufruf gibt FTP_MOREDATA zurück, sodass wir in eine Schleife eintreten und wiederholt ftp_nb_continue() aufrufen, um das nächste Datenstück zu senden – der Kommentar // Do something else ist der Ort, an dem Sie eine Fortschrittsanzeige aktualisieren oder andere Arbeiten erledigen würden. Wenn die Schleife endet, prüfen wir auf FTP_FINISHED, um den Erfolg zu bestätigen, und schließen dann die Verbindung mit ftp_close().

Hinweis: Rufen Sie ftp_nb_continue() immer auf, bis das Ergebnis nicht mehr FTP_MOREDATA ist. Wenn Sie zu früh aufhören, bleibt der Upload auf dem Server unvollständig.

Fehlerbehandlung bei ftp_nb_put()

Es ist wichtig, Fehler bei der Verwendung der Funktion ftp_nb_put() ordnungsgemäß zu behandeln. Wenn die Funktion FTP_FAILED zurückgibt, bedeutet dies, dass der Upload fehlgeschlagen ist. Hier ein Beispiel, wie Fehler behandelt werden:

Fehlerbehandlung bei ftp_nb_put()

<?php

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

if ($result === FTP_FAILED) {
    echo "Failed to upload file to remote server.\n";
}

while ($result === FTP_MOREDATA) {
    // Do something else while waiting for the FTP operation to complete
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "Upload completed.\n";
}

ftp_close($conn);

Indem Sie Fehler angemessen behandeln und den Rückgabewert der Funktion prüfen, können Sie den Erfolg Ihrer FTP-Operationen mit der Funktion ftp_nb_put() sicherstellen.

Verwandte Funktionen

• ftp_put() — eine Datei im blockierenden Modus hochladen (einfacher, pausiert jedoch das Skript).
• ftp_nb_continue() — eine nicht-blockierende Übertragung fortsetzen, die von ftp_nb_put() gestartet wurde.
• ftp_nb_fput() — nicht-blockierender Upload von einem bereits geöffneten Datei-Handle anstelle eines Pfades.
• ftp_nb_get() — das Download-Gegenstück zu ftp_nb_put().

Fazit

Die Funktion ftp_nb_put() lädt Dateien im nicht-blockierenden Modus auf einen FTP-Server hoch, sodass Ihr Skript während der im Hintergrund laufenden Übertragung mit anderen Aufgaben fortfahren kann. Der Schlüssel liegt darin, den Upload zu starten, in einer Schleife ftp_nb_continue() aufzurufen, solange der Status FTP_MOREDATA ist, und FTP_FINISHED zu bestätigen (mit Behandlung von FTP_FAILED), bevor die Verbindung geschlossen wird. Mit korrekter Verwendung und Fehlerbehandlung ist sie ein wertvolles Werkzeug für reaktionsfähige Dateiübertragungen in Ihren PHP-Projekten.

Hinweis: Die ftp_nb_*-Funktionen gelten im modernen PHP als veraltet. Für neue Projekte sollten Sie cURL oder eine asynchrone HTTP-Bibliothek wie Guzzle für bessere Performance, Sicherheit und breitere Protokollunterstützung in Betracht ziehen.

Übungen