dirname()

Fonction PHP dirname()

La fonction dirname() retourne la portion du répertoire parent d'un chemin. À partir d'un chemin complet vers un fichier ou un répertoire, elle supprime le composant final et vous retourne le répertoire qui le contient. Cette page couvre la syntaxe, le paramètre $levels, les cas particuliers, et comment dirname() se distingue des fonctions de chemin associées.

Il s'agit d'une opération purement sur les chaînes : dirname() analyse le texte du chemin que vous lui passez. Elle ne touche pas le système de fichiers, donc le chemin n'a pas besoin de pointer vers un fichier qui existe réellement.

Syntaxe

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

• $path — le chemin sur lequel opérer (obligatoire).
• $levels — le nombre de niveaux de répertoires à remonter. Par défaut 1. Disponible depuis PHP 7.0 ; doit être 1 ou supérieur.

Elle retourne le répertoire parent de $path sous forme de string.

Paramètres

Exemples

Obtenir le répertoire d'un fichier

Ceci récupère le répertoire qui contient example.txt :

Résultat :

/home/user1

Obtenir le parent d'un répertoire

Un slash final est traité comme la fin d'un nom de répertoire, donc dirname() retourne quand même le parent :

Résultat :

/home/user1

Remonter plusieurs niveaux avec $levels

Passez un deuxième argument pour remonter plus loin dans l'arborescence en un seul appel :

<?php

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

Résultat :

/usr

Ceci est équivalent à dirname(dirname("/usr/local/lib")), mais se lit plus clairement lorsque vous devez remonter plusieurs niveaux.

Cas particuliers à connaître

dirname() produit quelques résultats qui surprennent les gens la première fois :

<?php

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

• Un chemin sans composant de répertoire retourne . (le répertoire courant), et non une chaîne vide.
• Le chemin racine se retourne lui-même.
• Sous Windows, / et \ sont acceptés comme séparateurs de répertoire.

dirname() vs. fonctions associées

• basename() — l'opposé de dirname() : elle retourne le dernier composant (le nom du fichier ou du dossier) au lieu du répertoire parent.
• pathinfo() — retourne un array avec dirname, basename, extension et filename d'un seul coup, ce qui est pratique quand vous avez besoin de plus d'une information.
• realpath() — résout un chemin par rapport au système de fichiers réel (en suivant les liens symboliques et ..), contrairement à dirname() qui n'opère que sur le texte.

Un motif courant consiste à construire des chemins relatifs au fichier courant :

<?php

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

Conclusion

dirname() extrait le répertoire parent d'un chemin en tant qu'opération purement textuelle. N'oubliez pas qu'elle ne consulte jamais le système de fichiers, qu'un chemin sans répertoire retourne ., et que l'argument $levels vous permet de remonter plusieurs répertoires en un seul appel. Pour la partie complémentaire — le nom du fichier — utilisez basename() ; pour tout récupérer en une fois, utilisez pathinfo().

Pratique