ftp_put()

Die PHP-Funktion ftp_put()

ftp_put() ist eine eingebaute PHP-Funktion, die eine lokale Datei auf einen entfernten FTP-Server hochlädt. Sie ist das Upload-Gegenstück zu ftp_get(), das eine Remote-Datei auf Ihren Rechner herunterlädt. Diese Seite behandelt die Signatur, die wichtigen Übertragungsmodi, einen vollständigen Arbeitsablauf, die Fehlerbehandlung und häufige Fallstricke in der Produktion.

ftp_put() wird verwendet, nachdem eine Verbindung mit ftp_connect() geöffnet und die Authentifizierung mit ftp_login() durchgeführt wurde.

Syntax

ftp_put(
    FTP\Connection $ftp,
    string $remote_filename,
    string $local_filename,
    int $mode = FTP_BINARY
): bool

Gibt bei Erfolg true und bei Fehler false zurück.

Versionshinweis: Vor PHP 8.1 war das erste Argument eine resource, die von ftp_connect() zurückgegeben wurde. Ab PHP 8.1 ist es ein FTP\Connection-Objekt. Ihr Code ändert sich nicht — Sie übergeben weiterhin das, was ftp_connect() zurückgibt — aber is_resource()-Prüfungen funktionieren damit nicht mehr.

Binär- vs. ASCII-Modus

Die Wahl des falschen Modus ist die häufigste Ursache für „Der Upload hat funktioniert, aber die Datei ist beschädigt":

• FTP_BINARY überträgt die Bytes exakt so, wie sie sind. Verwenden Sie ihn standardmäßig für alles — Bilder, Archive, PDFs, ausführbare Dateien und in der Praxis sogar Textdateien.
• FTP_ASCII schreibt Zeilenenden (\n ↔ \r\n) um, damit sie zur Zielplattform passen. Nur sinnvoll für reinen Text, und er zerstört jede Binärdatei lautlos. Im Zweifelsfall bleiben Sie bei FTP_BINARY.

Ein vollständiger Upload

Prüfen Sie immer die Rückgabewerte jedes FTP-Aufrufs, anstatt anzunehmen, dass ein Schritt erfolgreich war:

<?php

// 1. Open a connection (false on failure)
$ftp = ftp_connect('ftp.example.com');
if ($ftp === false) {
    exit("Could not connect to FTP server.\n");
}

// 2. Authenticate
if (!ftp_login($ftp, 'username', 'password')) {
    ftp_close($ftp);
    exit("FTP login failed.\n");
}

// 3. Behind a firewall/NAT? Passive mode is almost always required.
ftp_pasv($ftp, true);

// 4. Upload: local file -> remote path, binary mode
$ok = ftp_put($ftp, '/public_html/index.html', './build/index.html', FTP_BINARY);

echo $ok
    ? "Upload succeeded.\n"
    : "Upload failed.\n";

// 5. Always close
ftp_close($ftp);

Beachten Sie die Reihenfolge der Argumente: Remote-Ziel zuerst, lokale Quelle zweite — umgekehrt zu dem, was viele erwarten. Wenn diese vertauscht werden, versucht PHP, eine nicht vorhandene lokale Datei zu lesen, und der Aufruf schlägt fehl.

Fehlerbehandlung

ftp_put() gibt false zurück und erzeugt eine PHP-Warnung bei einem Fehler. Wandeln Sie das in ein klares, verwertbares Ergebnis um, anstatt eine unbeabsichtigte Warnung in Ihre Ausgabe durchsickern zu lassen:

<?php

$remote = '/public_html/index.html';
$local  = './build/index.html';

// Catch the "no such local file" case before touching the network.
if (!is_readable($local)) {
    exit("Local file '$local' is missing or unreadable.\n");
}

if (!ftp_put($ftp, $remote, $local, FTP_BINARY)) {
    // Common causes: wrong remote directory, no write permission,
    // disk quota exceeded, or passive mode not enabled.
    echo "Failed to upload '$local' to '$remote'.\n";
} else {
    echo "Uploaded '$local' to '$remote'.\n";
}

ftp_close($ftp);

Häufige Fehlerursachen

• Falsche Argumentreihenfolge — Remote-Pfad und lokaler Pfad sind vertauscht.
• Passivmodus nicht gesetzt — Die meisten Server hinter NAT benötigen ftp_pasv($ftp, true) nach dem Login.
• Fehlendes Remote-Verzeichnis — ftp_put() erstellt keine Ordner; verwenden Sie zuerst ftp_mkdir().
• Keine Schreibberechtigung oder Kontingent überschritten auf der Serverseite.
• Falscher Übertragungsmodus beschädigt eine Binärdatei (verwenden Sie FTP_BINARY).

Upload aus einem offenen Stream

Wenn Ihre Daten bereits ein offenes Datei-Handle sind (oder von einem Stream-Wrapper statt einem Pfad auf der Festplatte stammen), verwenden Sie stattdessen ftp_fput() — es nimmt eine Stream-Ressource anstelle eines lokalen Dateinamens.

Fazit

ftp_put() lädt eine lokale Datei auf einen entfernten FTP-Server hoch. Merken Sie sich die drei Dinge, die die meisten Probleme verursachen: übergeben Sie den Remote-Pfad zuerst, behalten Sie FTP_BINARY bei, es sei denn, Sie haben einen bestimmten Grund für ASCII, und prüfen Sie jeden Rückgabewert. Für nicht-blockierende Übertragungen, die Ihr Skript nicht blockieren, siehe ftp_nb_put().

Übungen