ftp_nb_put — Funktion · PHP-Referenz

Signatur

ftp_nb_put(FTP\Connection $ftp, string $remote_filename, string $local_filename, int $mode = FTP_BINARY, int $offset = 0): int|false

Beschreibung

ftp_nb_put() funktioniert ähnlich wie ftp_put(), führt den Upload jedoch asynchron (nicht-blockierend) durch. Das bedeutet, dass die Funktion sofort zurückkehrt, ohne auf den Abschluss der Übertragung zu warten. Das PHP-Skript kann so zwischen den einzelnen Übertragungs-Chunks weitere Aufgaben erledigen.

Der Rückgabewert ist entweder FTP_MOREDATA (die Übertragung läuft noch), FTP_FINISHED (erfolgreich abgeschlossen) oder FTP_FAILED (Fehler aufgetreten). Um die Übertragung fortzuführen, muss ftp_nb_continue() in einer Schleife aufgerufen werden, bis FTP_MOREDATA nicht mehr zurückgegeben wird.

Der Parameter $mode legt das Übertragungsformat fest: FTP_BINARY für Binärdaten (z. B. Bilder, Archive) und FTP_ASCII für Textdateien, bei denen Zeilenenden angepasst werden. Mit dem optionalen Parameter $offset lässt sich ein unterbrochener Upload an einer bestimmten Byte-Position fortsetzen.

Diese Funktion eignet sich besonders, wenn während eines Uploads gleichzeitig andere Verarbeitungsschritte stattfinden sollen oder wenn der Fortschritt des Uploads überwacht und protokolliert werden muss.

Parameter

Name	Typ	Default	Beschreibung
$ftp Pflicht	FTP\Connection		Eine gültige FTP-Verbindungsinstanz, die zuvor mit `ftp_connect()` oder `ftp_ssl_connect()` erstellt wurde.
$remote_filename Pflicht	string		Der Pfad und Dateiname auf dem FTP-Server, unter dem die Datei gespeichert werden soll.
$local_filename Pflicht	string		Der lokale Pfad zur Datei, die hochgeladen werden soll.
$mode	int	FTP_BINARY	Übertragungsmodus: `FTP_BINARY` für Binärdateien oder `FTP_ASCII` für Textdateien.
$offset	int	0	Byte-Offset, ab dem der Upload beginnen soll. Nützlich zum Fortsetzen unterbrochener Übertragungen.

Rückgabewert

Typ

int|false

Beschreibung

Gibt FTP_MOREDATA zurück, wenn die Übertragung noch läuft, FTP_FINISHED bei erfolgreichem Abschluss oder FTP_FAILED bei einem Fehler. Im Falle eines schwerwiegenden Fehlers (z. B. ungültige Verbindung oder Datei nicht gefunden) wird false zurückgegeben.

Beispiele

Einfacher nicht-blockierender FTP-Upload

<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'benutzername', 'passwort');

$ret = ftp_nb_put($ftp, '/upload/datei.zip', '/lokaler/pfad/datei.zip', FTP_BINARY);

while ($ret === FTP_MOREDATA) {
    // Hier können andere Aufgaben erledigt werden
    echo ".";
    $ret = ftp_nb_continue($ftp);
}

if ($ret === FTP_FINISHED) {
    echo "\nUpload erfolgreich abgeschlossen.";
} else {
    echo "\nUpload fehlgeschlagen (FTP_FAILED).";
}

ftp_close($ftp);

.... Upload erfolgreich abgeschlossen.

Upload fortsetzen ab einem bestimmten Offset

<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'benutzername', 'passwort');

// Bereits übertragene Bytes ermitteln (z. B. aus einer Datenbank oder Datei)
$uebertrageneBytes = 1048576; // 1 MB bereits übertragen

$ret = ftp_nb_put(
    $ftp,
    '/upload/grossedatei.bin',
    '/lokaler/pfad/grossedatei.bin',
    FTP_BINARY,
    $uebertrageneBytes
);

while ($ret === FTP_MOREDATA) {
    $ret = ftp_nb_continue($ftp);
}

if ($ret === FTP_FINISHED) {
    echo "Upload erfolgreich fortgesetzt und abgeschlossen.";
} else {
    echo "Upload fehlgeschlagen.";
}

ftp_close($ftp);

Upload erfolgreich fortgesetzt und abgeschlossen.

// Wichtig · Fallstricke

Wichtig: Es darf immer nur eine nicht-blockierende Übertragung gleichzeitig pro FTP-Verbindung aktiv sein. Ein zweiter Aufruf von ftp_nb_put() oder ftp_nb_get() auf derselben Verbindung, während noch eine Übertragung läuft, führt zu einem Fehler.

Ab PHP 8.1.0 ist der Typ des ersten Parameters FTP\Connection statt der zuvor verwendeten Ressource (resource).

Der Modus FTP_ASCII konvertiert Zeilenenden und kann bei Binärdateien zu Dateikorruption führen. Für alle Nicht-Textdateien stets FTP_BINARY verwenden.

Zugangsdaten (Benutzername und Passwort) sollten niemals im Quellcode hartcodiert werden. Besser Umgebungsvariablen oder gesicherte Konfigurationsdateien verwenden.

Siehe auch

ftp_nb_continue ftp_put ftp_nb_get ftp_connect ftp_nb_fput