dirname()

PHP-Funktion dirname()

Die Funktion dirname() gibt den übergeordneten Verzeichnisanteil eines Pfades zurück. Bei einem vollständigen Pfad zu einer Datei oder einem Verzeichnis entfernt sie die letzte Komponente und liefert das übergeordnete Verzeichnis. Diese Seite behandelt die Syntax, den Parameter $levels, Sonderfälle und den Unterschied zwischen dirname() und verwandten Pfadfunktionen.

Es handelt sich um eine reine String-Operation: dirname() analysiert den Text des übergebenen Pfades. Sie greift nicht auf das Dateisystem zu, sodass der Pfad nicht auf eine tatsächlich existierende Datei zeigen muss.

Syntax

dirname(string $path, int $levels = 1): string

• $path — der zu verarbeitende Pfad (erforderlich).
• $levels — wie viele Verzeichnisebenen nach oben gegangen werden soll. Standardmäßig 1. Verfügbar seit PHP 7.0; muss 1 oder größer sein.

Die Funktion gibt das übergeordnete Verzeichnis von $path als string zurück.

Parameter

Beispiele

Verzeichnis einer Datei ermitteln

Hier wird das Verzeichnis ermittelt, das example.txt enthält:

Ausgabe:

/home/user1

Übergeordnetes Verzeichnis eines Ordners ermitteln

Ein abschließender Schrägstrich wird als Ende eines Verzeichnisnamens behandelt, sodass dirname() trotzdem das übergeordnete Verzeichnis zurückgibt:

Ausgabe:

/home/user1

Mit $levels mehrere Ebenen hochgehen

Ein zweites Argument ermöglicht es, in einem einzigen Aufruf weiter nach oben im Verzeichnisbaum zu navigieren:

<?php

echo dirname("/usr/local/lib", 2);

Ausgabe:

/usr

Dies entspricht dirname(dirname("/usr/local/lib")), ist aber übersichtlicher, wenn mehrere Ebenen auf einmal übersprungen werden sollen.

Wichtige Sonderfälle

dirname() liefert in einigen Fällen Ergebnisse, die beim ersten Mal überraschen können:

<?php

echo dirname("example.txt"), "\n";   // "."  — no directory part, so current dir
echo dirname("/"), "\n";             // "/"  — root has no parent
echo dirname(""), "\n";              // "."

• Ein Pfad ohne Verzeichniskomponente gibt . (das aktuelle Verzeichnis) zurück, keinen leeren string.
• Der Stammpfad gibt sich selbst zurück.
• Unter Windows werden sowohl / als auch \ als Verzeichnistrennzeichen akzeptiert.

dirname() im Vergleich zu verwandten Funktionen

• basename() — das Gegenstück zu dirname(): gibt die letzte Komponente (den Datei- oder Ordnernamen) statt des übergeordneten Verzeichnisses zurück.
• pathinfo() — gibt ein array mit dirname, basename, extension und filename auf einmal zurück, was praktisch ist, wenn mehrere Informationen gleichzeitig benötigt werden.
• realpath() — löst einen Pfad gegen das echte Dateisystem auf (folgt Symlinks und ..), im Gegensatz zu dirname(), das rein textbasiert arbeitet.

Ein gängiges Muster ist das Erstellen von Pfaden relativ zur aktuellen Datei:

<?php

// Load config that sits one directory above this script.
require dirname(__DIR__) . "/config.php";

Fazit

dirname() extrahiert das übergeordnete Verzeichnis aus einem Pfad als einfache String-Operation. Zu beachten ist: Die Funktion prüft niemals das Dateisystem, ein Pfad ohne Verzeichnis gibt . zurück, und das Argument $levels ermöglicht es, in einem einzigen Aufruf mehrere Verzeichnisebenen hochzugehen. Für den komplementären Dateinamenteil eines Pfades eignet sich basename(); für alle Informationen auf einmal steht pathinfo() zur Verfügung.

Übungen