chdir()

Функция PHP chdir() изменяет текущую рабочую директорию скрипта на переданную вами директорию. На этой странице объясняется, что такое рабочая директория, точная сигнатура chdir(), как обрабатывать возвращаемое значение, а также типичные случаи использования и подводные камни, с которыми вы столкнётесь в реальном коде.

Что такое рабочая директория?

Текущая рабочая директория (CWD) — это базовое расположение, которое PHP использует для разрешения относительных путей. Когда вы вызываете что-то вроде fopen('data.txt', 'r') или include 'config.php', PHP объединяет этот относительный путь с CWD, чтобы определить, какой файл вы имеете в виду.

Распространённое заблуждение состоит в том, что CWD всегда является папкой, содержащей выполняемый скрипт. Это лишь отправная точка в некоторых конфигурациях. CWD может отличаться от директории скрипта — например, когда скрипт запускается через cron, веб-сервером или из другой рабочей директории в командной строке. Если путь важен, никогда не делайте предположений — прочитайте его с помощью getcwd().

Синтаксис

chdir(string $directory): bool

• $directory — путь для переключения. Может быть абсолютным (/var/www/html) или относительным к текущей CWD (../logs).
• Возвращаемое значение — true в случае успеха, false в случае ошибки (например, если директория не существует или у процесса нет прав доступа). При ошибке chdir() генерирует предупреждение E_WARNING, поэтому следует проверять возвращаемое значение, а не игнорировать его.

Базовое использование

<?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

Поскольку chdir() принимает относительные пути, chdir('logs') разрешается относительно текущего местоположения, а chdir('..') поднимается на один уровень вверх.

Всегда проверяйте возвращаемое значение

Неудачный вызов chdir() оставляет CWD неизменной, что может незаметно нарушить работу всех относительных путей, следующих после него. Защитите вызов:

<?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;
}

Сохранение и восстановление исходной директории

Изменение CWD влияет на весь процесс, а не только на текущую функцию. Если вспомогательная функция меняет директорию и забывает вернуться обратно, последующий код может читать или записывать не те файлы. Безопасный подход — сохранить исходную директорию и восстановить её после завершения работы:

<?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

Использование chdir() совместно с include

После изменения CWD относительные пути в include/require разрешаются из нового расположения:

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

Конкретно для include полагаться на CWD ненадёжно, поскольку вызывающий код может её изменить. Предпочтительнее использовать абсолютный путь, построенный на основе собственного расположения скрипта с помощью магической константы __DIR__:

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

Когда стоит использовать chdir()?

• CLI-скрипты и инструменты сборки, которые вызывают команды, ожидающие определённой директории.
• Пакетные задания (запускаемые через cron), где стартовая CWD непредсказуема, и вы задаёте её явно перед началом работы.
• Работа с относительными путями в пакетном режиме — например, перебор файлов в одной папке без указания полного пути к каждому.

Для большинства веб-приложений следует предпочитать абсолютные пути (__DIR__, настроенные базовые пути) вместо изменения глобальной CWD, поскольку изменение распространяется на весь запрос.

Связанные функции

• getcwd() — получить текущую рабочую директорию.
• mkdir() — создать директорию перед переходом в неё.
• scandir() / opendir() — получить список содержимого директории.
• realpath() — преобразовать относительный путь в абсолютный с разрешением символических ссылок.
• dirname() — получить часть строки пути, соответствующую директории.

Практика