Die PHP-Funktion ftp_cdup() verstehen

Wenn Sie Dateiübertragungen per FTP skripten, müssen Sie häufig im entfernten Verzeichnisbaum navigieren, bevor Sie Dateien hochladen, herunterladen oder auflisten. PHPs eingebaute FTP-Erweiterung bietet dafür eine Handvoll Navigationsfunktionen, und ftp_cdup() ist die Funktion, die eine Ebene nach oben wechselt – das FTP-Äquivalent von cd .. auf der Kommandozeile.

Dieses Kapitel erläutert, was ftp_cdup() tut, seine Syntax und Rückgabewert, ein vollständiges Arbeitsbeispiel sowie die Fallstricke, die Sie kennen sollten, bevor Sie die Funktion produktiv einsetzen.

Was ist ftp_cdup()?

ftp_cdup() wechselt das aktuelle Arbeitsverzeichnis auf dem entfernten FTP-Server in dessen übergeordnetes Verzeichnis. Die Funktion macht genau eine Sache: eine Ebene nach oben wechseln. Befinden Sie sich in /var/www/html/uploads, landen Sie nach einmaligem Aufruf von ftp_cdup() in /var/www/html.

Sie ist das Gegenstück zu ftp_chdir(), das in ein benanntes Verzeichnis wechselt. Verwenden Sie ftp_chdir(), um tiefer zu wechseln oder zu einem Pfad zu springen, und ftp_cdup(), um wieder in Richtung Root zurückzusteigen.

ftp_cdup() beeinflusst nur das aktuelle Verzeichnis, das Ihre FTP-Sitzung verfolgt. Es verschiebt, kopiert oder löscht nichts auf dem Server.

Syntax

ftp_cdup(FTP\Connection $ftp): bool

Rückgabewert: true bei Erfolg, false bei Fehler (zum Beispiel, wenn Sie sich bereits im Stammverzeichnis befinden oder die Verbindung nicht authentifiziert ist).

Ab PHP 8.1 gibt ftp_connect() ein FTP\Connection-Objekt anstelle einer Ressource zurück. Die Funktion verhält sich unverändert; nur der Typhinweis hat sich geändert.

Verwendung von ftp_cdup()

Bevor Sie ftp_cdup() aufrufen können, müssen Sie:

1. Eine Verbindung mit ftp_connect() öffnen.
2. Sich mit ftp_login() authentifizieren.
3. (In der Regel) den passiven Modus mit ftp_pasv() aktivieren, damit Übertragungen hinter NAT/Firewalls funktionieren.

Das folgende Beispiel meldet sich an, wechselt mit ftp_chdir() in ein Unterverzeichnis und nutzt dann ftp_cdup(), um wieder eine Ebene nach oben zu wechseln. Mit ftp_pwd() wird das Arbeitsverzeichnis vor und nach dem Wechsel ausgegeben, damit Sie den Effekt nachvollziehen können:

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

// Move into a sub-directory first.
ftp_chdir($ftp, 'uploads');
echo "Before: " . ftp_pwd($ftp) . PHP_EOL; // e.g. /uploads

// Step back up to the parent directory.
if (ftp_cdup($ftp)) {
    echo "After:  " . ftp_pwd($ftp) . PHP_EOL; // e.g. /
} else {
    echo "Failed to change to the parent directory" . PHP_EOL;
}

ftp_close($ftp);

Hier stellen wir eine Verbindung her, melden uns an und aktivieren den passiven Modus. Anschließend wechseln wir in das Verzeichnis uploads, bestätigen den Standort mit ftp_pwd() und rufen ftp_cdup() auf, um zum übergeordneten Verzeichnis zurückzukehren. Die if-Prüfung ermöglicht es, auf einen fehlgeschlagenen Wechsel zu reagieren, anstatt den Erfolg vorauszusetzen. Abschließend wird die Verbindung mit ftp_close() freigegeben.

Häufige Fallstricke

• Sie befinden sich bereits im Stammverzeichnis. Der Aufruf von ftp_cdup() vom obersten Verzeichnis aus gibt false zurück. Prüfen Sie immer den Rückgabewert, anstatt Erfolg vorauszusetzen.
• Verwechslung mit einer Dateioperation. ftp_cdup() ändert nur Ihre Position. Zum Löschen oder Umbenennen entfernter Elemente verwenden Sie ftp_delete() oder ftp_rename().
• Warnungen bei Fehlern. Ein fehlgeschlagener Aufruf gibt auch ein E-WARNING aus. Unterdrücken oder behandeln Sie es gemäß Ihrer Fehlerstrategie, verlassen Sie sich aber niemals auf die Unterdrückung anstatt auf das boolean-Ergebnis zu prüfen.
• Vergessener passiver Modus. Wenn Auflistungen oder Übertragungen nach der Navigation hängenbleiben, haben Sie wahrscheinlich ftp_pasv($ftp, true) vergessen.

Fazit

ftp_cdup() ist die einfachste Navigationshilfe in PHPs FTP-Toolkit: Sie wechselt das aktuelle Verzeichnis der Sitzung eine Ebene nach oben und gibt einen boolean-Wert zurück, der angibt, ob der Vorgang erfolgreich war. Kombinieren Sie sie mit ftp_chdir() zum Wechseln nach unten und ftp_pwd() zum Bestätigen Ihrer Position, und Sie haben alles, was Sie benötigen, um zuverlässig in einem entfernten Verzeichnisbaum zu navigieren.

Übung