glob()

Esta página aborda a função PHP glob(): o que ela faz, sua sintaxe e flags, os curingas no estilo shell que ela reconhece, e padrões práticos como combinar múltiplas extensões, listar apenas diretórios, ordenar resultados e percorrer uma árvore recursivamente. Também explica as armadilhas comuns — arquivos ocultos, a diferença entre "sem correspondência" e "erro", e quando usar uma ferramenta diferente.

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

A função glob() pesquisa em um diretório os nomes de caminho que correspondem a um padrão curinga no estilo shell e os retorna como um array. O nome vem do globbing do shell Unix — o mesmo mecanismo que seu terminal usa quando você digita ls *.txt.

Ao contrário de uma pesquisa com expressão regular, glob() faz a correspondência diretamente no sistema de arquivos, portanto retorna apenas caminhos que realmente existem. É a maneira mais rápida de responder perguntas como "me dê todos os .jpg desta pasta" ou "quais arquivos de configuração começam com db-".

Sintaxe

glob(string $pattern, int $flags = 0): array|false

Valor de retorno: um array com os nomes de caminho correspondentes, um array vazio quando nada corresponde, ou false em caso de erro irrecuperável (por exemplo, um diretório que não pode ser lido). Como um resultado vazio e uma falha são ambos "falsy", use === false quando precisar detectar especificamente erros.

Os curingas que glob() reconhece

glob() reconhece padrões no estilo shell, não expressões regulares:

Um primeiro exemplo

<?php

$files = glob('*.txt');

if ($files === false) {
    echo 'glob() failed to read the directory.' . PHP_EOL;
} else {
    foreach ($files as $file) {
        echo $file . PHP_EOL;
    }
}

Este código pesquisa todos os arquivos terminados em .txt no diretório de trabalho atual e imprime cada nome em sua própria linha. Observe a verificação === false: ela distingue uma falha real do caso perfeitamente válido de "sem arquivos .txt aqui", que simplesmente retorna um array vazio que o foreach ignora.

As flags de glob()

O segundo argumento combina uma ou mais constantes com o operador OR bit a bit (|):

Correspondendo a várias extensões com GLOB_BRACE

<?php

$images = glob('uploads/*.{jpg,jpeg,png,gif}', GLOB_BRACE);

foreach ($images as $image) {
    echo $image . PHP_EOL;
}

GLOB_BRACE permite que uma única chamada cubra quatro extensões, o que é muito mais limpo do que executar glob() quatro vezes e mesclar os resultados.

Listando apenas subdiretórios

<?php

$dirs = glob('storage/*', GLOB_ONLYDIR);

foreach ($dirs as $dir) {
    echo $dir . PHP_EOL;
}

Com GLOB_ONLYDIR, arquivos simples dentro de storage/ são filtrados, restando apenas os diretórios — útil para iterar sobre pastas por usuário, buckets de cache e similares.

Ordenando os resultados

Por padrão, glob() retorna as correspondências em ordem alfabética crescente. Se precisar de uma ordem diferente — por exemplo, o arquivo mais recente primeiro — ordene o array você mesmo:

<?php

$files = glob('logs/*.log');

usort($files, static fn ($a, $b) => filemtime($b) <=> filemtime($a));

print_r($files);

Aqui usort() reordena a lista pelo tempo de modificação (filemtime()), do mais recente para o mais antigo. Passe GLOB_NOSORT para glob() quando for reordenar de qualquer forma — isso evita a ordenação inicial redundante em diretórios grandes.

Pesquisando recursivamente

glob() em si não desce para subdiretórios — * nunca cruza uma /. Para percorrer uma árvore inteira, combine glob() com GLOB_ONLYDIR e recursão:

<?php

function findFiles(string $dir, string $pattern): array
{
    $files = glob($dir . '/' . $pattern);

    foreach (glob($dir . '/*', GLOB_ONLYDIR) as $subDir) {
        $files = array_merge($files, findFiles($subDir, $pattern));
    }

    return $files;
}

print_r(findFiles('src', '*.php'));

Para árvores profundas ou muito grandes, o RecursiveDirectoryIterator do PHP geralmente é uma opção melhor, mas este padrão é suficiente para a maioria das tarefas do dia a dia.

Armadilhas comuns

• Arquivos ocultos são ignorados. Um * inicial não corresponde a dot-files, portanto glob('*') não retornará .env ou .gitignore. Faça a correspondência explicitamente com um padrão como glob('.*').
• Array vazio vs. false. Um foreach sobre um array vazio é inofensivo, mas count(), array_map() e similares emitirão avisos se glob() retornar false. Use === false primeiro para verificar.
• Sem regex. glob() entende apenas curingas no estilo shell. Para correspondência com expressão regular em uma lista existente de nomes, use preg_grep() ou teste nomes individuais com fnmatch().
• Caminhos entre plataformas. Use barras normais (/) nos padrões mesmo no Windows, ou construa caminhos com DIRECTORY_SEPARATOR, para que o mesmo código funcione em qualquer lugar.

Quando usar glob() vs. outras ferramentas

• Use glob() quando quiser uma lista rápida e ordenada de caminhos que correspondam a um curinga simples em um único diretório.
• Use scandir() quando quiser todas as entradas de um diretório (incluindo dot-files) e pretender filtrá-las você mesmo.
• Use opendir() / readdir() para leitura eficiente em memória de diretórios enormes.
• Use fnmatch() para testar um único nome contra um padrão shell sem acessar o sistema de arquivos.

Depois de obter uma lista de caminhos, pathinfo(), is_file() e file_exists() ajudam a inspecionar cada um deles. Consulte a visão geral do Sistema de Arquivos PHP para uma perspectiva mais ampla.

Conclusão

glob() é a maneira mais ergonômica de encontrar arquivos por padrão em PHP: passe um curinga no estilo shell e receba de volta um array ordenado de caminhos reais. Lembre-se de verificar false quando erros forem importantes, use GLOB_BRACE e GLOB_ONLYDIR para manter os padrões organizados, e recorra a um iterador recursivo quando precisar pesquisar uma árvore inteira.

Prática