mkdir()

Cos'è la funzione mkdir()?

La funzione mkdir() è una funzione PHP integrata che crea una nuova directory nel file system. Si utilizza ogni volta che lo script deve creare una cartella durante l'esecuzione — ad esempio, per archiviare file caricati, generare directory di cache per utente, o predisporre una cartella di esportazione prima di scrivervi report.

Questa pagina tratta la firma della funzione, ciascun parametro (incluso il spesso frainteso argomento per i permessi), come creare directory annidate in una sola chiamata, il valore restituito e la gestione degli errori, e i trabocchetti più comuni in cui ci si imbatte.

Ecco la sintassi di base della funzione mkdir():

La sintassi PHP di mkdir()

mkdir(string $directory, int $permissions = 0777, bool $recursive = false, ?resource $context = null): bool

Parametri

Nota sui permessi e l'umask

Il valore $permissions passato non viene applicato letteralmente. Il sistema operativo sottrae la umask del processo da esso. Ad esempio, con la comune umask 022, chiamare mkdir($dir, 0777) produce una directory con modalità 0755, non 0777. Per questo motivo, passare sempre la modalità desiderata e non supporre che 0777 significhi "scrivibile da tutti" — di solito non è così.

Per sicurezza, preferire 0755 (il proprietario può leggere/scrivere/eseguire, tutti gli altri possono leggere/eseguire) rispetto al valore predefinito 0777. Se occorre una modalità esatta indipendentemente dall'umask, chiamare chmod() dopo aver creato la directory.

Come si usa la funzione mkdir()?

L'utilizzo della funzione mkdir() è semplice. Ecco i passaggi da seguire:

1. Specificare il percorso della directory da creare.
2. Chiamare la funzione mkdir(), passando il percorso della directory come primo parametro, una modalità di permessi opzionale come secondo parametro e un flag booleano come terzo parametro per creare le directory padre se necessario.

Ecco un esempio di codice che mostra come utilizzare la funzione mkdir():

Come si usa la funzione mkdir()?

<?php

$dir = '/path/to/new/directory';
// 0755 is recommended for security (owner: rwx, others: rx)
$permissions = 0755;
if (!is_dir($dir)) {
    if (mkdir($dir, $permissions, true)) {
        echo "Directory created successfully!";
    } else {
        echo "Failed to create directory.";
    }
} else {
    echo "Directory already exists!";
}

In questo esempio, si usa is_dir() per verificare se la destinazione esiste già. Si specifica una modalità di permessi più sicura (0755) e si passa true come terzo argomento per abilitare la creazione ricorsiva. La funzione mkdir() restituisce un valore booleano, quindi si racchiude la chiamata in un'istruzione if per gestire in modo appropriato il successo o il fallimento. Se la directory non esiste, si tenta di crearla e si stampa un messaggio di successo o fallimento. Se esiste già, si stampa un messaggio di già esistente.

Creazione di directory annidate

Senza il flag ricorsivo, mkdir() può creare solo l'ultimo segmento di un percorso — ogni elemento padre deve già esistere. Passare true come terzo argomento indica a PHP di creare l'intera catena in una volta sola:

<?php

// Fails if "cache" or "cache/images" don't already exist:
// mkdir('cache/images/thumbs');           // Warning + returns false

// Works — creates cache, cache/images and cache/images/thumbs as needed:
if (mkdir('cache/images/thumbs', 0755, true)) {
    echo 'Nested directories created.';
}

Valore restituito e gestione degli errori

mkdir() restituisce true in caso di successo e false in caso di fallimento. In caso di fallimento, genera anche un E_WARNING — ad esempio quando la directory padre è mancante, il percorso esiste già, oppure il processo non dispone dei permessi di scrittura.

Esistono due modi corretti per gestire quell'avvertimento:

<?php

// 1. Guard with is_dir() so you never try to recreate an existing folder.
$dir = 'uploads';
if (!is_dir($dir) && !mkdir($dir, 0755, true) && !is_dir($dir)) {
    // The second is_dir() guards against a race where another
    // process created the directory between our two checks.
    throw new RuntimeException("Directory \"$dir\" could not be created");
}

// 2. Suppress the warning with @ only if you immediately check the result.
if (!@mkdir($dir, 0755) && !is_dir($dir)) {
    echo 'Could not create directory.';
}

Evitare di usare @ da solo senza verificare il valore restituito — ingoiare silenziosamente l'avvertimento rende i fallimenti invisibili.

Trabocchetti comuni

• La directory esiste già. mkdir() restituisce false e genera un avvertimento. Verificare sempre con is_dir() prima, oppure affidarsi all'idioma di creazione ricorsiva descritto sopra.
• I permessi vengono filtrati dall'umask. Come spiegato sopra, la modalità passata viene mascherata. Usare chmod() per una modalità esatta.
• I percorsi relativi dipendono dalla directory di lavoro. Un percorso relativo viene risolto rispetto alla directory corrente dello script, che può differire dalla posizione del file. Usare un percorso assoluto (ad es. __DIR__ . '/uploads') in caso di dubbio.
• Windows ignora completamente l'argomento dei permessi — è un'operazione nulla lì.

Funzioni correlate

• rmdir() — rimuove una directory vuota (il corrispettivo di mkdir()).
• scandir() — elenca il contenuto di una directory.
• chmod() — modifica i permessi di una directory dopo la creazione.
• fopen() — apre o crea un file una volta che la directory esiste.

Conclusione

La funzione mkdir() è uno strumento utile in PHP per creare nuove directory su un file system. Le cose fondamentali da ricordare sono: passare una modalità di permessi esplicita e sicura (come 0755) invece di affidarsi al valore predefinito 0777, usare il flag ricorsivo quando le directory padre potrebbero essere mancanti, e verificare sempre il valore booleano restituito affinché i fallimenti non passino inosservati. Con queste abitudini, mkdir() diventa un elemento affidabile per qualsiasi script che lavora con il file system.

Esercitazione