dirname()

Funzione PHP dirname()

La funzione dirname() restituisce la porzione della directory padre di un percorso. Dato un percorso completo verso un file o una directory, rimuove il componente finale e restituisce la directory che lo contiene. Questa pagina tratta la sintassi, il parametro $levels, i casi limite e le differenze tra dirname() e le funzioni correlate per la gestione dei percorsi.

Si tratta di una pura operazione su string: dirname() analizza il testo del percorso passato. Non accede al filesystem, quindi il percorso non deve necessariamente puntare a un file esistente.

Sintassi

dirname(string $path, int $levels = 1): string

• $path — il percorso su cui operare (obbligatorio).
• $levels — il numero di livelli di directory da risalire. Il valore predefinito è 1. Disponibile da PHP 7.0; deve essere 1 o superiore.

Restituisce la directory padre di $path come string.

Parametri

Esempi

Ottenere la directory di un file

Questo esempio recupera la directory che contiene example.txt:

Output:

/home/user1

Ottenere la directory padre di una directory

Una barra finale viene trattata come la fine del nome di una directory, quindi dirname() restituisce comunque la directory padre:

Output:

/home/user1

Risalire più livelli con $levels

Passa un secondo argomento per risalire più in alto nella struttura ad albero in una sola chiamata:

<?php

echo dirname("/usr/local/lib", 2);

Output:

/usr

Questo equivale a dirname(dirname("/usr/local/lib")), ma risulta più leggibile quando occorre risalire di più livelli.

Casi limite da conoscere

dirname() produce alcuni risultati che sorprendono alla prima lettura:

<?php

echo dirname("example.txt"), "\n";   // "."  — no directory part, so current dir
echo dirname("/"), "\n";             // "/"  — root has no parent
echo dirname(""), "\n";              // "."

• Un percorso senza componente di directory restituisce . (la directory corrente), non una string vuota.
• Il percorso radice restituisce se stesso.
• Su Windows, sia / che \ sono accettati come separatori di directory.

dirname() vs. funzioni correlate

• basename() — l'opposto di dirname(): restituisce l'ultimo componente (il nome del file o della cartella) invece della directory padre.
• pathinfo() — restituisce un array con dirname, basename, extension e filename tutti insieme, molto utile quando si hanno bisogno di più informazioni.
• realpath() — risolve un percorso rispetto al filesystem reale (seguendo symlink e ..), a differenza di dirname(), che opera solo sul testo.

Un pattern comune consiste nel costruire percorsi relativi al file corrente:

<?php

// Load config that sits one directory above this script.
require dirname(__DIR__) . "/config.php";

Conclusione

dirname() estrae la directory padre da un percorso come semplice operazione su string. Tieni a mente che non controlla mai il filesystem, che un percorso senza directory restituisce ., e che l'argomento $levels consente di risalire più directory in una sola chiamata. Per la parte complementare del nome del file in un percorso, usa basename(); per ottenere tutto in una volta sola, usa pathinfo().

Esercitazione