getcwd()

A Função PHP getcwd()

getcwd() é uma função integrada do PHP que retorna o diretório de trabalho atual — o diretório em relação ao qual o PHP resolve caminhos de arquivo relativos. Não recebe argumentos e retorna o caminho absoluto como string, ou false em caso de falha.

Esta página aborda a sintaxe, o que o valor de retorno realmente significa, os casos em que retorna false e como getcwd() difere da constante mágica __DIR__ e da função chdir().

Sintaxe

getcwd(): string|false

• Parâmetros: nenhum.
• Valor de retorno: o caminho absoluto do diretório de trabalho atual em caso de sucesso, ou false em caso de falha (por exemplo, quando um diretório pai do caminho atual tem o bit de permissão de leitura ou busca desativado).

O diretório de trabalho é um estado de todo o processo. Começa como o diretório a partir do qual o PHP foi iniciado, não o diretório onde o script em execução reside. Em um servidor web, geralmente é a raiz do documento ou o diretório de inicialização do servidor; na CLI, é o diretório a partir do qual você executou o script.

Exemplo Básico

<?php
echo getcwd();

Saída (o caminho exato depende de onde o script é executado):

/home/user/public_html

Tratando Falhas

Como getcwd() pode retornar false, trate o resultado como string|false em vez de assumir que é uma string. Isso é importante quando você constrói caminhos a partir dele — concatenar false produz silenciosamente um prefixo vazio.

<?php
$dir = getcwd();

if ($dir === false) {
    echo "Unable to determine the current working directory.";
} else {
    echo "Working in: $dir";
}

Construindo Caminhos de Arquivo

Um uso comum é resolver um caminho relativo ao local onde o script está sendo executado e depois realizar operações de arquivo lá. Sempre verifique se o arquivo foi realmente aberto antes de escrever nele:

<?php
$current_dir = getcwd();
$file_path = $current_dir . DIRECTORY_SEPARATOR . 'test.txt';

$file_handle = fopen($file_path, 'w');

if ($file_handle === false) {
    echo "Could not open file for writing.";
} else {
    fwrite($file_handle, 'This is a test file.');
    fclose($file_handle);
    echo "File written to: $file_path";
}

Usar a constante DIRECTORY_SEPARATOR em vez de uma / codificada mantém o caminho correto em todos os sistemas operacionais. Consulte fopen() para os modos de arquivo disponíveis.

getcwd() vs. DIR

Esta é a fonte mais comum de bugs. getcwd() retorna o diretório de trabalho em tempo de execução, que pode mudar. __DIR__ é resolvido em tempo de compilação e sempre aponta para o diretório do arquivo fonte atual — nunca muda, mesmo após uma chamada a chdir().

• Use __DIR__ para incluir arquivos ou carregar recursos que estejam ao lado do seu script (require __DIR__ . '/config.php';). Isso é quase sempre o que você quer para caminhos relativos ao projeto.
• Use getcwd() quando você genuinamente se importa com onde o processo foi iniciado, como uma ferramenta de CLI que opera na pasta atual do usuário.

O diretório de trabalho pode ser alterado com chdir():

<?php
echo getcwd(), PHP_EOL;   // e.g. /home/user/project
chdir('..');
echo getcwd(), PHP_EOL;   // parent directory, e.g. /home/user

Funções Relacionadas

• chdir() — altera o diretório de trabalho atual.
• realpath() — expande um caminho relativo para um caminho absoluto canônico.
• dirname() — obtém a parte do diretório pai de um caminho.
• scandir() — lista as entradas dentro de um diretório.

Conclusão

getcwd() retorna o caminho absoluto do diretório de trabalho atual do processo, ou false se não puder ser lido. Verifique se há false antes de usar o resultado, prefira DIRECTORY_SEPARATOR ao unir caminhos e recorra a __DIR__ quando precisar de um caminho relativo ao arquivo de script em vez do diretório de execução.

Prática