getcwd()

La función PHP getcwd()

getcwd() es una función integrada de PHP que devuelve el directorio de trabajo actual — el directorio contra el cual PHP resuelve las rutas de archivos relativas. No acepta argumentos y devuelve la ruta absoluta como string, o false en caso de fallo.

Esta página cubre la sintaxis, qué significa realmente el valor de retorno, los casos en que devuelve false, y cómo getcwd() difiere de la constante mágica __DIR__ y de la función chdir().

Sintaxis

getcwd(): string|false

• Parámetros: ninguno.
• Valor de retorno: la ruta absoluta del directorio de trabajo actual en caso de éxito, o false en caso de fallo (por ejemplo, cuando un directorio padre de la ruta actual tiene desactivado el bit de permiso de lectura o búsqueda).

El directorio de trabajo es un estado de todo el proceso. Comienza como el directorio desde el que se lanzó PHP, no el directorio donde reside el script en ejecución. En un servidor web suele ser la raíz del documento o el directorio de inicio del servidor; en la CLI es el directorio desde el que ejecutaste el script.

Ejemplo básico

<?php
echo getcwd();

Salida (la ruta exacta depende de dónde se ejecute el script):

/home/user/public_html

Manejo de fallos

Dado que getcwd() puede devolver false, trata el resultado como string|false en lugar de asumir que es un string. Esto importa cuando construyes rutas a partir de él — concatenar false produce silenciosamente un prefijo vacío.

<?php
$dir = getcwd();

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

Construcción de rutas de archivos

Un uso común es resolver una ruta relativa al lugar desde donde se ejecuta el script y luego realizar operaciones de archivo allí. Siempre verifica que el archivo se haya abierto correctamente antes de escribir en él:

<?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 la constante DIRECTORY_SEPARATOR en lugar de un / codificado de forma fija mantiene la ruta correcta en todos los sistemas operativos. Consulta fopen() para conocer los modos de archivo disponibles.

getcwd() vs. DIR

Esta es la fuente de errores más común. getcwd() devuelve el directorio de trabajo en tiempo de ejecución, que puede cambiar. __DIR__ se resuelve en tiempo de compilación y siempre apunta al directorio del archivo fuente actual — nunca cambia, incluso después de una llamada a chdir().

• Usa __DIR__ para incluir archivos o cargar recursos que se encuentren junto a tu script (require __DIR__ . '/config.php';). Esto es casi siempre lo que necesitas para rutas relativas al proyecto.
• Usa getcwd() cuando realmente te importe desde dónde se inició el proceso, como una herramienta CLI que opera en la carpeta actual del usuario.

El directorio de trabajo puede cambiarse con chdir():

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

Funciones relacionadas

• chdir() — cambiar el directorio de trabajo actual.
• realpath() — expandir una ruta relativa a una ruta absoluta canónica.
• dirname() — obtener la parte del directorio padre de una ruta.
• scandir() — listar las entradas dentro de un directorio.

Conclusión

getcwd() devuelve la ruta absoluta del directorio de trabajo actual del proceso, o false si no puede leerse. Comprueba si hay false antes de usar el resultado, prefiere DIRECTORY_SEPARATOR al unir rutas y recurre a __DIR__ cuando necesites una ruta relativa al archivo del script en lugar del directorio en tiempo de ejecución.

Práctica