ftp_get()

Was ist ftp_get()?

ftp_get() ist eine in PHP integrierte Funktion, die eine Datei von einem FTP-Server herunterlädt und auf Ihrem Rechner in eine lokale Datei schreibt. Sie ist das lesende Gegenstück zu ftp_put(), das hochlädt. Verwenden Sie sie immer dann, wenn Sie eine Datei (ein Backup, ein Log, einen Bericht) von einem Remote-Server über FTP abrufen möchten.

Diese Seite erklärt, was ftp_get() tut, welche Parameter und Rückgabewerte es hat, einen vollständigen Ablauf (verbinden → einloggen → herunterladen → schließen), wie Fehler behandelt werden und welche typischen Fallstricke es gibt (Übertragungsmodus, passiver Modus und das Fortsetzen unterbrochener Downloads).

Parameter

ftp_get() nimmt fünf Parameter entgegen — drei erforderliche und zwei optionale:

Rückgabewert

Die Funktion gibt einen boolean zurück: true bei Erfolg, false bei Fehler. Prüfen Sie ihn immer — ein fehlgeschlagener Download löst standardmäßig keine Ausnahme aus.

FTP_BINARY vs FTP_ASCII

FTP_BINARY überträgt die Datei Byte für Byte und ist für nahezu alles korrekt: Bilder, PDFs, Archive, ausführbare Dateien und sogar die meisten Textdateien. FTP_ASCII führt eine automatische Zeilenende-Konvertierung zwischen den Konventionen von Server und Client durch — verwenden Sie es daher nur für reine Textdateien, wenn Sie diese Konvertierung tatsächlich wünschen. Die Verwendung von FTP_ASCII auf einer Binärdatei beschädigt diese, wählen Sie daher im Zweifel FTP_BINARY.

Syntax von ftp_get()

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

Hinweis: Ab PHP 8.1+ wurde der Typ resource für FTP-Verbindungen durch ein Ftp\Connection-Objekt ersetzt, und der Parameter mode wurde optional (Standard: FTP_BINARY). Die obige veraltete resource-Signatur wird für die Abwärtskompatibilität beibehalten — Ihr Code muss nicht geändert werden.

Verwendung von ftp_get()

Um ftp_get() zu verwenden, stellen Sie zunächst mit ftp_connect() eine Verbindung her und authentifizieren sich mit ftp_login(). Hier ist der vollständige Ablauf:

Herunterladen einer Datei mit ftp_get()

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

// 2. Log in with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    ftp_close($conn);
    die("Login failed.\n");
}

// 3. Switch to passive mode (required behind most firewalls/NAT)
ftp_pasv($conn, true);

// 4. Download the remote file into a local path
if (ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY)) {
    echo "File retrieved successfully.\n";
} else {
    echo "Failed to retrieve the file.\n";
}

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

Die Schritte sind immer gleich: verbinden, einloggen, optional den passiven Modus aktivieren, herunterladen, dann schließen. Der passive Modus (ftp_pasv()) wird hier aktiviert, weil die meisten Clients hinter einer Firewall oder NAT sitzen und Übertragungen im aktiven Modus sonst hängen bleiben oder fehlschlagen würden. Beachten Sie, dass Sie ftp_pasv() nach dem Einloggen aufrufen müssen.

Fehlerbehandlung in ftp_get()

ftp_get() gibt bei einem Fehler false zurück, anstatt eine Ausnahme auszulösen. Prüfen Sie daher den Rückgabewert explizit. Häufige Ursachen sind eine fehlende Remote-Datei, unzureichende Berechtigungen oder ein lokaler Pfad, der nicht beschreibbar ist. PHP gibt auch eine Warnung aus, die Sie zur Protokollierung erfassen können:

Erfassen des Grundes für einen fehlgeschlagenen Download

<?php
// $conn is an open, logged-in FTP connection
$ok = @ftp_get($conn, '/local/directory/local_file.txt', 'remote_file.txt', FTP_BINARY);

if ($ok === false) {
    $error = error_get_last();
    echo "Failed to retrieve the file: " . ($error['message'] ?? 'unknown error') . "\n";
} else {
    echo "File retrieved successfully.\n";
}

Das @ unterdrückt die PHP-Rohmeldung, sodass Sie Ihre eigene Nachricht formatieren können, während error_get_last() Ihnen dennoch das zugrunde liegende Detail für ein Log liefert.

Unterbrochenen Download fortsetzen

Der optionale Parameter resumepos ermöglicht es Ihnen, einen abgebrochenen Download fortzusetzen, anstatt von vorne zu beginnen. Übergeben Sie die aktuelle Größe der teilweise heruntergeladenen lokalen Datei als Byte-Offset:

Fortsetzen mit resumepos

<?php
// $conn is an open, logged-in FTP connection
$local = '/local/directory/big_archive.zip';

// Continue from however many bytes we already have locally
$offset = file_exists($local) ? filesize($local) : 0;

if (ftp_get($conn, $local, 'big_archive.zip', FTP_BINARY, $offset)) {
    echo "Download complete.\n";
} else {
    echo "Resume failed.\n";
}

Das Fortsetzen funktioniert zuverlässig nur mit FTP_BINARY und auf Servern, die den REST-Befehl unterstützen. Für große Übertragungen können Sie auch die nicht-blockierende Variante ftp_nb_get() verwenden, die im Hintergrund herunterlädt, damit Ihr Skript andere Aufgaben erledigen kann.

Verwandte Funktionen

• ftp_put() — eine lokale Datei auf den Server hochladen (das Gegenstück zu ftp_get()).
• ftp_fget() — in ein bereits geöffnetes Datei-Handle statt in einen Pfad herunterladen.
• ftp_size() — die Größe einer Remote-Datei vor dem Herunterladen ermitteln.
• ftp_connect() und ftp_login() — die Verbindung öffnen und authentifizieren.
• ftp_close() — die Verbindung schließen, wenn Sie fertig sind.

Zusammenfassung

ftp_get() lädt eine Remote-Datei über FTP herunter und speichert sie lokal, wobei es bei Erfolg true und bei Fehler false zurückgibt. Stellen Sie zuerst eine Verbindung her und melden Sie sich an, bevorzugen Sie FTP_BINARY, es sei denn, Sie benötigen ausdrücklich eine ASCII-Zeilenende-Konvertierung, aktivieren Sie den passiven Modus hinter einer Firewall und prüfen Sie stets den Rückgabewert, damit Fehler nicht unbemerkt bleiben.

Übungen