HOWTO · PHP

Trouver le chemin du répertoire racine en PHP

Ce tutoriel présente comment trouver le chemin du répertoire racine du projet PHP

Sur cette page

Une application PHP peut avoir plusieurs chemins que l’on appelle sa « racine ». La racine du projet est le répertoire que l’application utilise comme base ; le répertoire du fichier courant est celui où se trouve un script PHP donné ; et la racine des documents Web est le répertoire que le serveur Web expose pour une requête. Ces chemins peuvent différer. Choisissez la valeur qui correspond aux fichiers que vous devez localiser, au lieu de supposer qu’une expression renvoie toujours la racine du projet.

Pour les exemples, imaginons un projet situé dans /var/www/html/project, avec index.php à sa racine et login.php dans master/. La racine des documents du serveur, donnée à titre illustratif, est /var/www/html. Ce sont des chemins d’exemple, et non des valeurs mesurées sur votre serveur.

Distinguer la racine du projet de la racine des documents Web

La racine du projet est une convention propre à l’application, et non un paramètre PHP. Elle peut contenir le code de l’application, sa configuration et d’autres fichiers. La racine des documents Web est configurée sur le serveur et détermine à partir de quel répertoire les fichiers publics sont servis. Dans cet exemple, le projet se trouve sous la racine des documents, mais un déploiement peut placer le projet ailleurs ou configurer un sous-répertoire public comme racine des documents.

Gardez cette distinction à l’esprit : __DIR__ et dirname() dérivent des chemins de l’emplacement d’un fichier PHP, tandis que $_SERVER['DOCUMENT_ROOT'] indique un paramètre du serveur pour la requête en cours. Aucune de ces valeurs ne détecte automatiquement une racine propre à l’application.

Obtenir le répertoire du fichier courant avec __DIR__

La constante magique __DIR__ est le chemin absolu du répertoire qui contient le fichier où elle apparaît. Dans master/login.php, elle correspond donc à /var/www/html/project/master, et non à /var/www/html/project. Sa valeur dépend de l’emplacement du script : inclure celui-ci depuis un autre répertoire de travail ne la modifie pas. Utilisez-la pour construire des chemins vers des fichiers situés à côté du script ou dans ses sous-répertoires ; ajoutez au besoin un chemin relatif en utilisant le séparateur de chemins de PHP.

Exécutez cet exemple autonome. Lors de l’exécution fournie, le fichier PHP a été enregistré sous /work ; les deux expressions ont donc renvoyé ce répertoire. Les libellés et le résultat affichés dans l’exemple restent en anglais.

<?php
echo "Current file directory: ", __DIR__, PHP_EOL;
echo "Directory from __FILE__: ", dirname(__FILE__), PHP_EOL;
?>
Current file directory: /work
Directory from __FILE__: /work

__FILE__ est le chemin complet du fichier courant, et dirname(__FILE__) renvoie le répertoire qui le contient. Cette fonction constitue donc un équivalent pratique dans du code PHP plus ancien, tandis que __DIR__ exprime l’intention plus directement.

Trouver un répertoire parent avec dirname()

Utilisez dirname() pour remonter d’un chemin de fichier connu à son répertoire parent. En partant de __FILE__ dans master/login.php, un appel renvoie le répertoire master ; un deuxième appel renvoie le répertoire du projet. Dans l’arborescence d’exemple, ces résultats sont respectivement /var/www/html/project/master et /var/www/html/project. Les appels imbriqués rendent chaque étape explicite et évitent de dépendre de l’argument facultatif levels, dont la disponibilité varie selon la version de PHP.

L’opération remonte les composants du chemin ; elle ne recherche pas un dossier par son nom et ne descend pas dans un sous-répertoire. Si l’organisation de votre projet change, le nombre de répertoires parents à remonter peut également changer. Gardez cette relation près du code ou, si plusieurs fichiers en ont besoin, définissez un chemin de base propre au projet dans la configuration.

Lire la racine des documents Web du serveur avec $_SERVER['DOCUMENT_ROOT']

Pendant une requête Web, $_SERVER['DOCUMENT_ROOT'] contient la racine des documents configurée sur le serveur. Dans la configuration donnée à titre illustratif, sa valeur est /var/www/html, tandis que la racine du projet est /var/www/html/project. Utilisez cette valeur lorsque vous avez précisément besoin de la racine Web publique du serveur, par exemple pour construire un chemin relatif à ce répertoire configuré. Ne l’utilisez pas comme synonyme de la racine du projet.

Cette variable du serveur dépend du contexte de la requête et de la configuration du serveur. Elle peut être absente ou inadaptée dans un script exécuté en ligne de commande, et sa valeur peut varier d’un déploiement à l’autre. Vérifiez qu’elle est disponible dans le code susceptible de s’exécuter hors d’une requête Web. Si le chemin recherché appartient au projet plutôt qu’au répertoire public du serveur, utilisez __DIR__ ou un chemin de base défini dans la configuration de l’application.

En résumé, utilisez __DIR__ pour obtenir le répertoire qui contient le fichier PHP courant, imbriquez les appels à dirname() pour atteindre un répertoire parent connu, comme celui du projet, et consultez $_SERVER['DOCUMENT_ROOT'] uniquement lorsque vous avez besoin de la racine des documents configurée sur le serveur Web. Considérez les chemins d’exemple comme des illustrations et vérifiez la configuration propre à votre déploiement dans l’environnement où le script s’exécute.