chdir()

A função PHP chdir() altera o diretório de trabalho atual do seu script para o diretório que você passa a ela. Esta página explica o que é o diretório de trabalho, a assinatura exata de chdir(), como tratar o valor retornado e os casos comuns e armadilhas que você encontrará em código real.

O que é o diretório de trabalho?

O diretório de trabalho atual (CWD) é a localização base que o PHP usa para resolver caminhos relativos. Quando você chama algo como fopen('data.txt', 'r') ou include 'config.php', o PHP combina esse caminho relativo com o CWD para determinar qual arquivo você deseja acessar.

Um equívoco comum é pensar que o CWD é sempre a pasta que contém o script em execução. Isso é apenas o ponto de partida em algumas configurações. O CWD pode ser diferente do diretório do script — por exemplo, quando um script é iniciado pelo cron, por um servidor web, ou a partir de outro diretório de trabalho na linha de comando. Quando o caminho importa, nunca presuma; leia-o com getcwd().

Sintaxe

chdir(string $directory): bool

• $directory — o caminho para o qual alternar. Pode ser absoluto (/var/www/html) ou relativo ao CWD atual (../logs).
• Valor de retorno — true em caso de sucesso, false em caso de falha (por exemplo, se o diretório não existir ou o processo não tiver permissão). chdir() emite um E_WARNING em caso de falha, portanto você deve verificar o valor de retorno em vez de ignorá-lo.

Uso básico

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

Como chdir() aceita caminhos relativos, chdir('logs') é resolvido em relação ao local atual, enquanto chdir('..') sobe um nível de diretório.

Sempre verifique o valor de retorno

Um chdir() com falha deixa o CWD inalterado, o que pode silenciosamente quebrar todos os caminhos relativos que vierem depois. Proteja a chamada:

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

Salvar e restaurar o diretório original

Alterar o CWD afeta o processo inteiro, não apenas a função atual. Se uma função auxiliar muda de diretório e se esquece de voltar, o código posterior pode ler ou gravar os arquivos errados. Um padrão seguro é capturar o diretório original e restaurá-lo quando terminar:

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

Combinando chdir() com includes

Uma vez que o CWD é alterado, os caminhos relativos de include/require são resolvidos a partir do novo local:

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

Para includes especificamente, depender do CWD é frágil porque quem chama pode alterá-lo. Prefira um caminho absoluto construído a partir do próprio local do script com a constante mágica __DIR__:

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

Quando devo usar chdir()?

• Scripts CLI e ferramentas de build que executam comandos que esperam um diretório específico.
• Jobs em lote (executados via cron) onde o CWD de inicialização é imprevisível, então você o define explicitamente primeiro.
• Trabalhar com caminhos relativos em massa — por exemplo, iterar arquivos em uma pasta sem prefixar cada caminho.

Para a maioria das aplicações web, você deve preferir caminhos absolutos (__DIR__, caminhos base configurados) em vez de alterar o CWD global, pois a mudança vaza por toda a requisição.

Funções relacionadas

• getcwd() — lê o diretório de trabalho atual.
• mkdir() — cria um diretório antes de entrar nele.
• scandir() / opendir() — lista o conteúdo de um diretório.
• realpath() — expande um caminho relativo para sua forma absoluta com symlinks resolvidos.
• dirname() — obtém a parte de diretório de uma string de caminho.

Prática