dirname()

Função PHP dirname()

A função dirname() retorna a porção do diretório pai de um caminho. Dado um caminho completo para um arquivo ou diretório, ela remove o componente final e retorna o diretório que o contém. Esta página cobre a sintaxe, o parâmetro $levels, casos extremos e como dirname() difere de funções de caminho relacionadas.

É uma operação puramente de string: dirname() analisa o texto do caminho que você passa. Ela não acessa o sistema de arquivos, portanto o caminho não precisa apontar para um arquivo que realmente existe.

Sintaxe

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

• $path — o caminho a ser processado (obrigatório).
• $levels — quantos níveis de diretório subir. O padrão é 1. Disponível desde PHP 7.0; deve ser 1 ou maior.

Retorna o diretório pai de $path como uma string.

Parâmetros

Exemplos

Obter o diretório de um arquivo

Este exemplo recupera o diretório que contém example.txt:

Saída:

/home/user1

Obter o pai de um diretório

Uma barra final é tratada como o fim do nome de um diretório, portanto dirname() ainda retorna o pai:

Saída:

/home/user1

Subir vários níveis com $levels

Passe um segundo argumento para subir mais na árvore em uma única chamada:

<?php

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

Saída:

/usr

Isso é equivalente a dirname(dirname("/usr/local/lib")), mas é mais legível quando você precisa subir vários níveis.

Casos extremos a conhecer

dirname() tem alguns resultados que surpreendem as pessoas da primeira vez:

<?php

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

• Um caminho sem componente de diretório retorna . (o diretório atual), e não uma string vazia.
• O caminho raiz retorna a si mesmo.
• No Windows, tanto / quanto \ são aceitos como separadores de diretório.

dirname() vs. funções relacionadas

• basename() — o oposto de dirname(): retorna o último componente (o nome do arquivo ou pasta), em vez do diretório pai.
• pathinfo() — retorna um array com dirname, basename, extension e filename de uma vez, o que é útil quando você precisa de mais de uma parte.
• realpath() — resolve um caminho no sistema de arquivos real (seguindo links simbólicos e ..), ao contrário de dirname(), que opera apenas no texto.

Um padrão comum é construir caminhos relativos ao arquivo atual:

<?php

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

Conclusão

dirname() extrai o diretório pai de um caminho como uma simples operação de string. Lembre-se de que ela nunca verifica o sistema de arquivos, que um caminho sem diretório retorna ., e que o argumento $levels permite subir vários diretórios em uma única chamada. Para a parte complementar do nome do arquivo em um caminho, use basename(); para obter tudo de uma vez, use pathinfo().

Prática