ftp_nb_get — Funktion · PHP-Referenz

Signatur

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

Beschreibung

ftp_nb_get() überträgt eine Datei vom FTP-Server auf das lokale Dateisystem, ohne den PHP-Prozess zu blockieren. Im Gegensatz zu ftp_get() kehrt die Funktion sofort zurück und liefert einen Status-Code, der anzeigt, ob die Übertragung abgeschlossen ist oder weitergeführt werden muss. Dadurch kann die Anwendung während des Downloads weitere Aufgaben erledigen.

Der Rückgabewert ist eine der Konstanten FTP_FINISHED (Übertragung abgeschlossen), FTP_MOREDATA (Übertragung läuft noch) oder FTP_FAILED (Fehler). Solange FTP_MOREDATA zurückgegeben wird, muss ftp_nb_continue() in einer Schleife aufgerufen werden, um den Download fortzusetzen.

Der Parameter $mode bestimmt, ob die Datei binär (FTP_BINARY) oder im Textmodus (FTP_ASCII) übertragen wird. Mit dem optionalen $offset-Parameter lässt sich ein Wiederaufsetzen einer unterbrochenen Übertragung realisieren.

Diese Funktion eignet sich besonders, wenn mehrere FTP-Downloads parallel oder zusammen mit anderem I/O-Handling koordiniert werden müssen, ohne auf die Fertigstellung jedes einzelnen Downloads warten zu müssen.

Parameter

Name	Typ	Default	Beschreibung
$ftp Pflicht	FTP\Connection		Eine aktive FTP-Verbindung, die mit `ftp_connect()` oder `ftp_ssl_connect()` erstellt wurde.
$local_filename Pflicht	string		Der lokale Pfad, unter dem die heruntergeladene Datei gespeichert werden soll.
$remote_filename Pflicht	string		Der Pfad zur Datei auf dem FTP-Server, die heruntergeladen werden soll.
$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 beginnen soll. Nützlich zum Fortsetzen unterbrochener Downloads.

Rückgabewert

Typ

int

Beschreibung

Gibt FTP_FINISHED zurück, wenn die Übertragung erfolgreich abgeschlossen wurde, FTP_MOREDATA wenn die Übertragung noch läuft und ftp_nb_continue() weiter aufgerufen werden muss, oder FTP_FAILED bei einem Fehler.

Beispiele

Einfacher nicht-blockierender Download

<?php
$ftp = ftp_connect('ftp.beispiel.de');
ftp_login($ftp, 'benutzer', 'passwort');
ftp_pasv($ftp, true);

$ret = ftp_nb_get($ftp, '/tmp/lokale_datei.zip', '/remote/datei.zip', FTP_BINARY);

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

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

ftp_close($ftp);
?>

..... Download erfolgreich abgeschlossen.

Unterbrochenen Download fortsetzen (Resume)

<?php
$ftp = ftp_connect('ftp.beispiel.de');
ftp_login($ftp, 'benutzer', 'passwort');
ftp_pasv($ftp, true);

$lokaleDatei = '/tmp/grossedatei.bin';
$remoteDatei = '/remote/grossedatei.bin';

// Bereits heruntergeladene Bytes ermitteln
$offset = file_exists($lokaleDatei) ? filesize($lokaleDatei) : 0;
echo "Setze Download fort ab Byte: $offset\n";

$ret = ftp_nb_get($ftp, $lokaleDatei, $remoteDatei, FTP_BINARY, $offset);

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

if ($ret === FTP_FINISHED) {
    echo "Download abgeschlossen.";
} else {
    echo "Download fehlgeschlagen.";
}

ftp_close($ftp);
?>

Setze Download fort ab Byte: 204800 Download abgeschlossen.

// Wichtig · Fallstricke

Sicherheitshinweis: FTP überträgt Zugangsdaten und Dateiinhalte unverschlüsselt. Für sensible Daten sollte stattdessen ftp_ssl_connect() oder SFTP (über die SSH2-Erweiterung) verwendet werden.

Passivmodus: In den meisten Netzwerkumgebungen (insbesondere hinter NAT oder einer Firewall) sollte ftp_pasv($ftp, true) vor dem Download aufgerufen werden, da andernfalls Verbindungsprobleme auftreten können.

Gleichzeitige Operationen: Auf einer FTP-Verbindung kann immer nur eine nicht-blockierende Operation gleichzeitig aktiv sein. Ein neues ftp_nb_get() oder ftp_nb_put() darf erst aufgerufen werden, wenn die laufende Übertragung mit FTP_FINISHED oder FTP_FAILED beendet wurde.

Ab PHP 8.1 ist der Verbindungstyp FTP\Connection statt der früheren Ressource zu verwenden.

Siehe auch

ftp_nb_continue ftp_get ftp_nb_put ftp_nb_fget ftp_pasv ftp_connect ftp_ssl_connect