chdir()

La funzione PHP chdir() cambia la directory di lavoro corrente dello script con quella che le si passa. Questa pagina spiega cos'è la directory di lavoro, la firma esatta di chdir(), come gestire il valore restituito e i casi comuni con le insidie che si incontrano nel codice reale.

Cos'è la directory di lavoro?

La directory di lavoro corrente (CWD) è la posizione base che PHP usa per risolvere i percorsi relativi. Quando si chiama qualcosa come fopen('data.txt', 'r') o include 'config.php', PHP unisce quel percorso relativo alla CWD per determinare quale file si intende.

Un malinteso comune è che la CWD sia sempre la cartella contenente lo script in esecuzione. Questo vale solo come punto di partenza in alcune configurazioni. La CWD può differire dalla directory dello script — ad esempio quando uno script viene avviato da cron, da un web server, o da un'altra directory di lavoro dalla riga di comando. Quando il percorso è importante, non fare supposizioni: leggilo con getcwd().

Sintassi

chdir(string $directory): bool

• $directory — il percorso verso cui spostarsi. Può essere assoluto (/var/www/html) o relativo alla CWD corrente (../logs).
• Valore restituito — true in caso di successo, false in caso di errore (ad esempio, se la directory non esiste o il processo non ha i permessi). chdir() emette un E_WARNING in caso di errore, quindi è opportuno verificare il valore restituito anziché ignorarlo.

Utilizzo di base

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

Poiché chdir() accetta percorsi relativi, chdir('logs') viene risolto rispetto alla posizione corrente, mentre chdir('..') risale di una directory.

Verificare sempre il valore restituito

Un chdir() fallito lascia la CWD invariata, il che può interrompere silenziosamente ogni percorso relativo successivo. Proteggi la chiamata:

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

Salvare e ripristinare la directory originale

Cambiare la CWD influisce sull'intero processo, non solo sulla funzione corrente. Se una funzione ausiliaria cambia directory e dimentica di tornare indietro, il codice successivo potrebbe leggere o scrivere file sbagliati. Un pattern sicuro consiste nel memorizzare la directory originale e ripristinarla al termine:

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

Combinare chdir() con gli include

Una volta cambiata la CWD, i percorsi relativi in include/require vengono risolti dalla nuova posizione:

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

Per gli include in particolare, affidarsi alla CWD è fragile perché i chiamanti possono modificarla. È preferibile usare un percorso assoluto costruito dalla posizione dello script stesso con la costante magica __DIR__:

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

Quando usare chdir()?

• Script CLI e strumenti di build che eseguono comandi che si aspettano una directory specifica.
• Batch job (avviati tramite cron) in cui la CWD di avvio è imprevedibile, quindi la si imposta esplicitamente prima.
• Lavorare con percorsi relativi in blocco — ad esempio iterando file in una cartella senza prefissare ogni percorso.

Per la maggior parte delle applicazioni web è preferibile usare percorsi assoluti (__DIR__, percorsi base configurati) anziché cambiare la CWD globale, poiché la modifica si propaga all'intera richiesta.

Funzioni correlate

• getcwd() — legge la directory di lavoro corrente.
• mkdir() — crea una directory prima di entrarci.
• scandir() / opendir() — elenca il contenuto di una directory.
• realpath() — espande un percorso relativo nella sua forma assoluta con i symlink risolti.
• dirname() — ottiene la parte directory di una stringa di percorso.

Pratica