ftp_nb_fput — Funktion · PHP-Referenz

Signatur

ftp_nb_fput(FTP\Connection $ftp, string $remote_filename, resource $stream, int $mode = FTP_BINARY, int $offset = 0): int

Beschreibung

ftp_nb_fput() überträgt den Inhalt eines bereits geöffneten PHP-Datei-Streams auf einen FTP-Server, ohne den laufenden PHP-Prozess dabei zu blockieren. Im Gegensatz zur blockierenden Variante ftp_fput() kehrt die Funktion sofort zurück und liefert entweder FTP_MOREDATA (Übertragung läuft noch), FTP_FINISHED (Übertragung abgeschlossen) oder FTP_FAILED (Fehler).

Solange FTP_MOREDATA zurückgegeben wird, muss die Übertragung durch wiederholten Aufruf von ftp_nb_continue() fortgesetzt werden. Diese nicht-blockierende Arbeitsweise erlaubt es, während des Uploads andere Aufgaben zu erledigen – beispielsweise Fortschrittsanzeigen zu aktualisieren oder mehrere Übertragungen zeitgleich zu koordinieren.

Der Parameter $mode bestimmt, ob die Übertragung im Binär- (FTP_BINARY) oder ASCII-Modus (FTP_ASCII) stattfindet. Mit $offset kann die Übertragung an einer bestimmten Stelle im Remote-File fortgesetzt werden, was für unterbrochene Uploads nützlich ist.

Die Funktion eignet sich besonders dann, wenn große Dateien übertragen werden sollen und das Skript währenddessen reaktionsfähig bleiben muss, etwa in einem Event-Loop oder bei der parallelen Verarbeitung mehrerer FTP-Verbindungen.

Parameter

Name	Typ	Default	Beschreibung
$ftp Pflicht	FTP\Connection		Eine aktive FTP-Verbindung, wie sie von `ftp_connect()` oder `ftp_ssl_connect()` zurückgegeben wird.
$remote_filename Pflicht	string		Der Zielpfad und Dateiname auf dem FTP-Server, unter dem die Datei gespeichert werden soll.
$stream Pflicht	resource		Ein geöffneter PHP-Datei-Stream (z. B. via `fopen()`), dessen Inhalt hochgeladen wird.
$mode	int	FTP_BINARY	Übertragungsmodus: `FTP_BINARY` für binäre Dateien (Standard) oder `FTP_ASCII` für Textdateien.
$offset	int	0	Position im Remote-File, ab der die Übertragung beginnt (für die Fortsetzung unterbrochener Uploads). Standard ist `0`.

Rückgabewert

Typ

int

Beschreibung

Gibt FTP_MOREDATA zurück, wenn die Übertragung noch läuft und ftp_nb_continue() erneut aufgerufen werden muss. FTP_FINISHED zeigt an, dass die Übertragung erfolgreich abgeschlossen wurde. FTP_FAILED wird bei einem Fehler zurückgegeben.

Beispiele

Nicht-blockierender Datei-Upload mit Fortschrittsanzeige

<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'benutzer', 'geheim');
ftp_pasv($ftp, true);

$localFile = '/tmp/grosseDatei.zip';
$stream = fopen($localFile, 'rb');

$ret = ftp_nb_fput($ftp, '/uploads/grosseDatei.zip', $stream, FTP_BINARY);

while ($ret === FTP_MOREDATA) {
    // Andere Aufgaben können hier erledigt werden
    echo '.';
    $ret = ftp_nb_continue($ftp);
}

if ($ret === FTP_FINISHED) {
    echo PHP_EOL . 'Upload erfolgreich abgeschlossen.';
} else {
    echo PHP_EOL . 'Upload fehlgeschlagen!';
}

fclose($stream);
ftp_close($ftp);

..... Upload erfolgreich abgeschlossen.

Unterbrochenen Upload fortsetzen (Offset)

<?php
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'benutzer', 'geheim');
ftp_pasv($ftp, true);

$localFile = '/tmp/grosseDatei.zip';

// Bereits übertragene Bytes auf dem Server ermitteln
$remoteSize = ftp_size($ftp, '/uploads/grosseDatei.zip');
$resumeOffset = ($remoteSize > 0) ? $remoteSize : 0;

$stream = fopen($localFile, 'rb');
if ($resumeOffset > 0) {
    fseek($stream, $resumeOffset);
}

$ret = ftp_nb_fput($ftp, '/uploads/grosseDatei.zip', $stream, FTP_BINARY, $resumeOffset);

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

if ($ret === FTP_FINISHED) {
    echo 'Fortgesetzter Upload erfolgreich abgeschlossen.';
} else {
    echo 'Upload fehlgeschlagen!';
}

fclose($stream);
ftp_close($ftp);

Fortgesetzter Upload erfolgreich abgeschlossen.

// Wichtig · Fallstricke

Wichtig: Während eine nicht-blockierende Übertragung läuft (Rückgabe FTP_MOREDATA), darf über dieselbe FTP-Verbindung keine weitere FTP-Funktion aufgerufen werden – ausgenommen ftp_nb_continue(). Andernfalls wird die laufende Übertragung abgebrochen.

Ab PHP 8.1 ist der erste Parameter vom Typ FTP\Connection (Objekt) anstatt einer resource. Älterer Code, der eine resource erwartet, muss entsprechend angepasst werden.

Bei der Verwendung von FTP_ASCII werden Zeilenenden automatisch konvertiert. Für alle binären Dateien (Bilder, Archive, ausführbare Dateien) sollte stets FTP_BINARY verwendet werden, um Datenverfälschungen zu vermeiden.

Siehe auch

ftp_nb_fget ftp_nb_put ftp_nb_continue ftp_fput ftp_put ftp_connect