chdir()

La fonction PHP chdir() change le répertoire de travail courant de votre script pour le répertoire que vous lui passez en argument. Cette page explique ce qu'est le répertoire de travail, la signature exacte de chdir(), comment gérer la valeur de retour, ainsi que les cas d'usage courants et les pièges à éviter dans du code réel.

Qu'est-ce que le répertoire de travail ?

Le répertoire de travail courant (CWD) est l'emplacement de base que PHP utilise pour résoudre les chemins relatifs. Lorsque vous appelez quelque chose comme fopen('data.txt', 'r') ou include 'config.php', PHP concatène ce chemin relatif avec le CWD pour déterminer quel fichier vous visez.

Une idée reçue courante est que le CWD correspond toujours au dossier contenant le script en cours d'exécution. Ce n'est que le point de départ dans certaines configurations. Le CWD peut différer du répertoire du script — par exemple lorsqu'un script est lancé par cron, par un serveur web, ou depuis un répertoire de travail différent en ligne de commande. Lorsque le chemin importe, ne faites jamais d'hypothèse ; lisez-le avec getcwd().

Syntaxe

chdir(string $directory): bool

• $directory — le chemin vers lequel basculer. Il peut être absolu (/var/www/html) ou relatif par rapport au CWD courant (../logs).
• Valeur de retour — true en cas de succès, false en cas d'échec (par exemple, si le répertoire n'existe pas ou si le processus n'a pas les permissions nécessaires). chdir() émet un E_WARNING en cas d'échec, vous devriez donc vérifier la valeur de retour plutôt que de l'ignorer.

Utilisation de base

<?php
// Where are we now?
echo getcwd() . PHP_EOL;   // e.g. /var/www/html

// Move into a subdirectory
chdir('logs');
echo getcwd() . PHP_EOL;   // e.g. /var/www/html/logs

// Move back up one level
chdir('..');
echo getcwd() . PHP_EOL;   // e.g. /var/www/html

Comme chdir() accepte des chemins relatifs, chdir('logs') est résolu par rapport à l'emplacement courant, tandis que chdir('..') remonte d'un niveau dans l'arborescence.

Toujours vérifier la valeur de retour

Un chdir() échoué laisse le CWD inchangé, ce qui peut silencieusement corrompre tous les chemins relatifs qui suivent. Protégez l'appel :

<?php
$target = '/path/that/may/not/exist';

if (chdir($target)) {
    echo "Now working in: " . getcwd() . PHP_EOL;
} else {
    echo "Could not change to {$target}" . PHP_EOL;
}

Sauvegarder et restaurer le répertoire d'origine

Changer le CWD affecte le processus entier, pas seulement la fonction en cours. Si une fonction auxiliaire change de répertoire et oublie de revenir en arrière, le code suivant pourrait lire ou écrire les mauvais fichiers. Une pratique sûre consiste à capturer le répertoire d'origine et à le restaurer une fois le travail terminé :

<?php
$original = getcwd();      // remember where we started

chdir('/tmp');
// ... do work that relies on /tmp being the CWD ...

chdir($original);          // restore for the rest of the script
echo getcwd() . PHP_EOL;   // back to where we started

Combiner chdir() avec les inclusions

Une fois le CWD modifié, les chemins relatifs des include/require sont résolus depuis le nouvel emplacement :

<?php
chdir('/path/to/app/config');
include 'database.php';   // resolves to /path/to/app/config/database.php

Pour les inclusions en particulier, s'appuyer sur le CWD est fragile car les appelants peuvent le modifier. Préférez un chemin absolu construit à partir de l'emplacement propre du script grâce à la constante magique __DIR__ :

<?php
// Robust regardless of the current working directory
include __DIR__ . '/config/database.php';

Quand utiliser chdir() ?

• Scripts CLI et outils de build qui exécutent des commandes nécessitant un répertoire spécifique.
• Tâches planifiées (exécutées via cron) où le CWD de lancement est imprévisible, et que vous définissez explicitement en premier.
• Travail avec des chemins relatifs en masse — par exemple, parcourir des fichiers dans un dossier sans préfixer chaque chemin.

Pour la plupart des applications web, vous devriez préférer les chemins absolus (__DIR__, chemins de base configurés) plutôt que de modifier le CWD global, car la modification se propage à l'ensemble de la requête.

Fonctions associées

• getcwd() — lire le répertoire de travail courant.
• mkdir() — créer un répertoire avant d'y accéder.
• scandir() / opendir() — lister le contenu d'un répertoire.
• realpath() — transformer un chemin relatif en chemin absolu résolu avec les liens symboliques.
• dirname() — obtenir la partie répertoire d'une chaîne de chemin.

Pratique