getcwd()

La funzione PHP getcwd()

getcwd() è una funzione PHP integrata che restituisce la directory di lavoro corrente — la directory rispetto alla quale PHP risolve i percorsi relativi dei file. Non accetta argomenti e restituisce il percorso assoluto come string, oppure false in caso di errore.

Questa pagina tratta la sintassi, il reale significato del valore restituito, i casi in cui restituisce false e come getcwd() differisce dalla costante magica __DIR__ e dalla funzione chdir().

Sintassi

getcwd(): string|false

• Parametri: nessuno.
• Valore restituito: il percorso assoluto della directory di lavoro corrente in caso di successo, oppure false in caso di errore (ad esempio, quando una directory padre del percorso corrente ha il bit di permesso read o search non impostato).

La directory di lavoro è uno stato a livello di processo. Inizia come la directory da cui è stato avviato PHP, non la directory in cui risiede lo script in esecuzione. Su un server web è solitamente la document root o la directory di avvio del server; sulla CLI è qualsiasi directory da cui si è eseguito lo script.

Esempio di base

<?php
echo getcwd();

Output (il percorso esatto dipende da dove viene eseguito lo script):

/home/user/public_html

Gestione degli errori

Poiché getcwd() può restituire false, tratta il risultato come string|false anziché assumere che sia sempre una string. Questo è importante quando si costruiscono percorsi a partire da esso — concatenare false produce silenziosamente un prefisso vuoto.

<?php
$dir = getcwd();

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

Costruzione di percorsi di file

Un utilizzo comune è risolvere un percorso relativo rispetto alla posizione in cui viene eseguito lo script, per poi eseguirvi operazioni sui file. Verifica sempre che il file sia stato effettivamente aperto prima di scriverci:

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

Usare la costante DIRECTORY_SEPARATOR invece di un / hardcoded mantiene il percorso corretto su tutti i sistemi operativi. Vedi fopen() per le modalità file disponibili.

getcwd() vs. DIR

Questa è la fonte più comune di bug. getcwd() restituisce la directory di lavoro a runtime, che può cambiare. __DIR__ viene risolta in fase di compilazione e punta sempre alla directory del file sorgente corrente — non cambia mai, nemmeno dopo una chiamata a chdir().

• Usa __DIR__ per includere file o caricare risorse che si trovano accanto al tuo script (require __DIR__ . '/config.php';). Questo è quasi sempre ciò che si vuole per percorsi relativi al progetto.
• Usa getcwd() quando ti interessa davvero da dove è stato avviato il processo, ad esempio in uno strumento CLI che opera sulla cartella corrente dell'utente.

La directory di lavoro può essere cambiata con chdir():

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

Funzioni correlate

• chdir() — cambia la directory di lavoro corrente.
• realpath() — espande un percorso relativo in un percorso assoluto canonico.
• dirname() — ottieni la parte della directory padre di un percorso.
• scandir() — elenca le voci all'interno di una directory.

Conclusione

getcwd() restituisce il percorso assoluto della directory di lavoro corrente del processo, oppure false se non può essere letta. Controlla la presenza di false prima di usare il risultato, preferisci DIRECTORY_SEPARATOR quando unisci percorsi, e ricorri a __DIR__ quando hai bisogno di un percorso relativo al file script anziché alla directory a runtime.

Esercizio