pathinfo()

O que é a Função pathinfo()?

A função pathinfo() é uma função nativa do PHP que divide um caminho de arquivo em suas partes — o diretório, o nome do arquivo e a extensão — e as retorna como um array associativo. É o auxiliar ideal sempre que você precisa responder perguntas como "em qual pasta está esse arquivo?" ou "qual é a extensão de um arquivo enviado?" sem precisar escrever sua própria análise de string.

Um ponto fundamental a entender desde o início: pathinfo() funciona exclusivamente na string que você fornece. Ela nunca acessa o sistema de arquivos, portanto o caminho não precisa apontar para um arquivo que realmente existe. Isso a torna rápida e segura para usar em valores fornecidos pelo usuário (por exemplo, o nome original de um arquivo enviado).

Esta página cobre a sintaxe, o array retornado por pathinfo(), como solicitar um único componente e os casos extremos que costumam confundir as pessoas (sem extensão, dotfiles, extensões com múltiplas partes).

Sintaxe

pathinfo(string $path, int $flags = PATHINFO_ALL): array|string

• $path — o caminho do arquivo a ser inspecionado. Pode ser absoluto ou relativo e não precisa existir.
• $flags — opcional. Quando omitido (ou definido como PATHINFO_ALL), a função retorna um array associativo. Quando definido com uma única flag, retorna apenas aquele componente como uma string.

O array retornado por pathinfo()

Por padrão, pathinfo() retorna um array associativo com até quatro chaves:

Aqui passamos o caminho do arquivo e armazenamos o array resultante em $info, depois lemos cada componente pela sua chave.

Importante: a chave extension só existe quando o caminho contém um .. Se o caminho não tiver extensão, essa chave simplesmente estará ausente do array, portanto acessar $info['extension'] diretamente geraria um aviso de "Undefined array key". Proteja-se com $info['extension'] ?? '' em caso de dúvida.

Retornando um único componente

Se você precisar apenas de uma parte, passe uma flag como segundo argumento. As flags possíveis são PATHINFO_DIRNAME, PATHINFO_BASENAME, PATHINFO_EXTENSION e PATHINFO_FILENAME. Com uma única flag, a função retorna uma string em vez de um array:

Esta é a forma mais limpa de obter apenas a extensão — por exemplo, para verificar se um upload é de um tipo permitido.

Casos extremos a observar

pathinfo() é tolerante, mas alguns resultados surpreendem as pessoas:

<?php

// 1. No extension: the 'extension' key is missing entirely.
print_r(pathinfo('/etc/hosts'));
// Array ( [dirname] => /etc [basename] => hosts [filename] => hosts )

// 2. Multi-part extension: only the LAST part counts as the extension.
print_r(pathinfo('archive.tar.gz'));
// Array ( [dirname] => . [basename] => archive.tar.gz
//         [extension] => gz [filename] => archive.tar )

// 3. Dotfile: the leading dot makes the whole name the "extension".
print_r(pathinfo('/home/user/.bashrc'));
// Array ( [dirname] => /home/user [basename] => .bashrc
//         [extension] => bashrc [filename] =>  )

Observações:

• Um caminho sem diretório (caso 2) reporta dirname como . (o diretório atual).
• Para nomes no estilo .tar.gz, pathinfo() trata apenas gz como extensão — não há forma nativa de obter tar.gz em uma única chamada.
• Um dotfile como .bashrc é lido como "um arquivo sem nome com extensão bashrc", o que raramente é o que se deseja. Trate esses casos manualmente se o seu código os permitir.

Quando usar pathinfo()

Use pathinfo() quando precisar de mais de uma parte de um caminho ao mesmo tempo, ou quando quiser um array nomeado e legível em vez de lembrar qual função dedicada faz o quê:

• Use pathinfo($p) para obter o diretório, o nome e a extensão juntos.
• Use basename() se quiser apenas o nome do arquivo — ele também permite remover um sufixo conhecido.
• Use dirname() se quiser apenas o diretório, e ele lida com múltiplos níveis via seu argumento $levels.
• Use realpath() quando precisar resolver um caminho em relação ao sistema de arquivos real (links simbólicos, .., etc.) — ao contrário de pathinfo(), ele acessa o disco e retorna false para arquivos inexistentes.

Para uma visão mais ampla sobre leitura e escrita de arquivos, consulte PHP File Handling.

Conclusão

pathinfo() é a forma mais rápida de dividir um caminho de arquivo em seu diretório, nome base, extensão e nome simples do arquivo. Lembre-se de que ela apenas analisa a string (nunca verifica se o arquivo existe), que a chave extension está ausente quando não há extensão, e que apenas a extensão final é reportada para nomes como archive.tar.gz. Para necessidades de um único componente, as funções dedicadas basename() e dirname() costumam ser mais claras.

Prática