dirname en PHP : récupérer le dossier parent d'un chemin

La fonction dirname() en PHP est un outil incontournable pour naviguer dans l’arborescence des répertoires et extraire rapidement le répertoire parent, le répertoire courant ou le chemin du répertoire à partir d’un chemin complet, chemin relatif, chemin absolu ou même d’un lien symbolique.

Introduite avec PHP 4 en 2000, elle fonctionne aussi bien sur Unix comme que sous Windows, que vous travailliez en ligne de commande, via un terminal shell ou dans des scripts web complexes impliquant des noms de fichiers spécifiques.

Table des matières

Signature et paramètres essentiels

La syntaxe officielle est simple :

dirname(string $chemin, int $niveaux = 1): string|false

$chemin : Spécifier un chemin complet absolu incluant le nom du fichier (/var/www/html/index.php), un chemin relatif (../config.php) vers un fichier nommé, un script ou un sous-dossier.
$niveaux (optionnel, 1 par défaut depuis PHP 7) : Indique combien de répertoires remonter – idéal pour atteindre un sous-répertoire parent, le dossier courant ou le répertoire racine d’un projet.

Cette fonction traite nativement les chemins absolus, gère tous les séparateurs de dossiers (/ pour Unix/Linux, \ sous Windows) et fonctionne parfaitement avec le répertoire de travail ou répertoire actif , sans jamais vérifier l’existence physique des dossiers.

Exemples pratiques et progressifs

Extraction d’un chemin complet absolu

echo dirname("/var/www/html/projets/index.php");  
// Résultat : "/var/www/html/projets" (répertoire parent)

Gestion de chemins relatifs ou dossier seul

echo dirname("config.ini");                    // "." (dossier courant/répertoire actif)
echo dirname("/var/www/html/");                // "/var/www" 
echo dirname("/");                             // "/" (répertoire racine)
echo dirname("C:\\www\\projet\\test.txt");     // "C:\\www\\projet" (sous Windows)

Remontée multi-niveaux dans les sous-répertoires

$cheminComplet = "/var/www/html/projets/site/sous-dossier/admin/index.php";
echo dirname($cheminComplet, 1);  // "/var/www/html/projets/site/sous-dossier/admin"
echo dirname($cheminComplet, 2);  // "/var/www/html/projets/site/sous-dossier"
echo dirname($cheminComplet, 3);  // "/var/www/html/projets/site"

Cas réels avec chemins relatifs et __FILE__

// Inclure un fichier frère depuis n'importe quel sous-répertoire
$cheminConfig = dirname(__FILE__) . '/config/database.php';
if (file_exists($cheminConfig)) {
    include $cheminConfig;
}

// Copier un fichier nommé vers sauvegarde avec chemin relatif
$fichierSource = dirname(__FILE__) . '/data/export.csv';
$fichierDestination = dirname(__FILE__) . '/../sauvegarde/' . basename($fichierSource);
copy($fichierSource, $fichierDestination);

Liens symboliques et répertoires de travail

// Fonctionne même avec les liens symboliques
$cheminSymlink = "/var/www/html -> /home/user/projets";
echo dirname(readlink($cheminSymlink));  // "/home/user"

Applications concrètes en développement web

Dans vos scripts PHP, dirname() excelle pour construire des chemins absolus ou chemins relatifs dynamiques :

Inclusions dynamiques multi-environnements :

$includesPath = dirname(__FILE__) . '/includes/';
$templatesPath = dirname(__FILE__, 2) . '/templates/';

Gestion d’uploads organisée :

$uploadDir = dirname($_SERVER['SCRIPT_FILENAME']) . '/uploads/' . date('Y/m/');

Logs structurés par répertoire de travail :

$logPath = dirname(__FILE__) . '/logs/app-' . date('Y-m-d') . '.log'; 
error_log("Erreur détectée", 3, $logPath);

Bonnes pratiques et pièges à éviter absolument

Piège 1 : Fichier isolé sans contexte de dossier

echo dirname("export.csv");                    // "." (dossier courant imprécis ❌)
echo dirname(__FILE__ . "/export.csv");        // Chemin fiable ✅

Piège 2 : Confusion séparateurs sous Windows

// Fonctionne partout sans effort
echo dirname("C:\\www\\projet\\sous-dossier\\admin.php");  // "C:\\www\\projet\\sous-dossier"

echo dirname("/var/www/projet/sous-dossier/admin.php");    // "/var/www/projet/sous-dossier"

Piège 3 : Boucle infinie vers la racine sécurisée

$dossier = $_SERVER['SCRIPT_FILENAME'];
$cheminsParcourus = [];
while ($dossier !== '/' && !in_array($dossier, $cheminsParcourus)) {
    echo "Répertoire parent : " . $dossier . "\n";
    $cheminsParcourus[] = $dossier;
    $dossier = dirname($dossier);
}

Pro tip : Préférez toujours __DIR__ (PHP 5.3+) pour le répertoire actif du script courant – plus moderne que dirname(__FILE__).

Performances et limites techniques

dirname() est ultra-rapide (opération native sur chaînes), parfaitement multi-plateforme et idéale pour les environnements shell, terminal ou scripts intensifs. Elle gère sans broncher les liens symboliques et les très longs chemins relatifs.

Limites à connaître :

Pas de validation d’existence (is_dir() requis après)
Ralentissement sur arborescences très profondes ($niveaux > 50)
Encodages spéciaux sous Windows (caractères accentués)

Alternatives selon vos besoins précis

Objectif principal	Fonction recommandée	Usage optimal
Répertoire actif courant	`__DIR__`	Scripts simples, moderne (PHP 5.3+)
Noms de fichiers seuls	`basename()`	Extraire nom sans chemin complet
Chemin complet analysé	`pathinfo()`	Répertoire + nom + extension
Chemins absolus vérifiés	`realpath()`	Résout `..`, vérifie existence
Lister répertoires	`scandir()`	Explorer contenu des sous-dossiers

retour à la liste des fonctions

Sources : php.net

dirname en PHP : récupérer le dossier parent d’un chemin