ftp_delete()

Die PHP-Funktion ftp_delete()

ftp_delete() entfernt eine einzelne Datei von einem entfernten FTP-Server. Sie ist das FTP-Äquivalent von unlink() auf einem lokalen Dateisystem: Man übergibt ihr eine offene FTP-Verbindung und den Pfad der zu löschenden Datei, und sie gibt zurück, ob die Löschung erfolgreich war.

Diese Seite behandelt die Signatur der Funktion, den Rückgabewert, ein vollständiges Praxisbeispiel, die Fehlerbehandlung und häufige Fallstricke (Verzeichnisse löschen, relative vs. absolute Pfade und Berechtigungen).

Syntax

ftp_delete(FTP\Connection $ftp, string $filename): bool

Hinweis: Vor PHP 8.1 war das erste Argument eine resource, die von ftp_connect() zurückgegeben wurde. Ab PHP 8.1 handelt es sich um ein FTP\Connection-Objekt, aber der Code ändert sich nicht — man übergibt weiterhin einfach den Wert, den ftp_connect() zurückgibt.

Rückgabewert

ftp_delete() gibt zurück:

• true — die Datei wurde erfolgreich gelöscht.
• false — die Löschung ist fehlgeschlagen (Datei existiert nicht, keine Berechtigung, der Pfad ist ein Verzeichnis oder die Verbindung ist ungültig).

Da sowohl ein gültiger leerer Pfad als auch jeder Fehler als false erscheinen, sollte das Ergebnis stets explizit geprüft werden, anstatt den Erfolg vorauszusetzen.

Ein vollständiges Beispiel

Zuerst öffnet man eine Verbindung mit ftp_connect(), authentifiziert sich mit ftp_login(), löscht die Datei und schließt die Sitzung dann mit ftp_close():

<?php

// Open an FTP connection (default port 21, 90-second timeout)
$ftp = ftp_connect('ftp.example.com');

if ($ftp === false) {
    exit("Could not connect to the FTP server.\n");
}

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

// Switch to passive mode — required behind most firewalls/NAT
ftp_pasv($ftp, true);

// Attempt the delete
if (ftp_delete($ftp, '/uploads/old-report.txt')) {
    echo "File deleted successfully.\n";
} else {
    echo "Failed to delete the file.\n";
}

// Always close the connection
ftp_close($ftp);

Fehlerbehandlung

ftp_delete() gibt eine PHP-Warnung aus und gibt false zurück, wenn die Datei nicht entfernt werden kann. Die zuverlässige Prüfung ist der boolean Rückgabewert. Verwenden Sie ===, damit das Ergebnis nicht mit einem falschen Verbindungswert verwechselt wird:

<?php

if (ftp_delete($ftp, '/uploads/old-report.txt') === true) {
    echo "Deleted.\n";
} else {
    echo "Delete failed — check the path, permissions, and that it is a file, not a folder.\n";
}

Wenn die eingebaute Warnung unterdrückt und eine eigene Meldung ausgegeben werden soll, wird dem Aufruf @ vorangestellt:

<?php

if (@ftp_delete($ftp, $remotePath) === false) {
    error_log("ftp_delete failed for: $remotePath");
}

Häufige Fallstricke

• Verzeichnisse sind keine Dateien. ftp_delete() entfernt nur Dateien. Um ein Verzeichnis zu löschen, verwendet man ftp_rmdir() — und das Verzeichnis muss zuerst leer sein, also müssen dessen Inhalte gelöscht werden (sie können mit ftp_nlist() aufgelistet werden), bevor es entfernt wird.
• Relative Pfade hängen vom aktuellen Verzeichnis ab. Ein einfacher Name wie report.txt wird relativ zum aktuellen Arbeitsverzeichnis des Servers aufgelöst. Absolute Pfade (/uploads/report.txt) sind zu bevorzugen, oder das Verzeichnis wird explizit mit ftp_chdir() gesetzt.
• Umbenennen statt Löschen. Wenn eine Datei nur verschoben oder archiviert werden soll, verwendet man ftp_rename() anstatt sie zu löschen und erneut hochzuladen.
• Berechtigungen. Das Löschen schlägt stillschweigend fehl (gibt false zurück), wenn der FTP-Benutzer keine Schreib-/Löschrechte für das Zielverzeichnis hat.

Zusammenfassung

ftp_delete() löscht eine einzelne Datei auf einem entfernten FTP-Server und gibt einen boolean zurück, der den Erfolg anzeigt. Zuerst wird die Verbindung geöffnet und authentifiziert, dann für Kompatibilität in den passiven Modus gewechselt, der Rückgabewert explizit geprüft und auf ftp_rmdir() zurückgegriffen, wenn stattdessen ein Verzeichnis entfernt werden soll. Den vollständigen Satz der FTP-Operationen finden Sie in der PHP-FTP-Referenz.

Practice