glob()

Questa pagina tratta la funzione PHP glob(): cosa fa, la sua sintassi e i flag, i metacaratteri shell che riconosce, e pattern pratici come la corrispondenza con più estensioni, l'elenco delle sole directory, l'ordinamento dei risultati e la navigazione ricorsiva di un albero. Vengono spiegati anche gli errori comuni — i file nascosti, la differenza tra "nessuna corrispondenza" ed "errore", e quando è meglio usare uno strumento diverso.

Cos'è la funzione glob()?

La funzione glob() cerca in una directory i percorsi che corrispondono a un pattern con metacaratteri shell e li restituisce come array. Il nome deriva dal globbing della shell Unix — lo stesso meccanismo usato dal terminale quando si digita ls *.txt.

A differenza di una ricerca con espressioni regolari, glob() opera direttamente sul filesystem, quindi restituisce solo percorsi che esistono effettivamente. È il modo più rapido per rispondere a domande come "dammi tutti i .jpg in questa cartella" o "quali file di configurazione iniziano con db-".

Sintassi

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

Valore restituito: un array di percorsi corrispondenti, un array vuoto se nulla corrisponde, oppure false in caso di errore irrecuperabile (ad esempio, una directory che non può essere letta). Poiché sia un risultato vuoto che un errore sono "falsy", usare === false quando si vuole rilevare specificamente gli errori.

I metacaratteri riconosciuti da glob()

glob() riconosce i pattern in stile shell, non le espressioni regolari:

Un primo esempio

<?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;
    }
}

Questo cerca ogni file che termina in .txt nella directory di lavoro corrente e stampa ogni nome su una riga separata. Si noti il controllo === false: distingue un vero errore dal caso perfettamente valido di "nessun file .txt qui", che produce semplicemente un array vuoto che il foreach salta.

I flag di glob()

Il secondo argomento combina una o più costanti con l'operatore OR bit a bit (|):

Corrispondenza con più estensioni usando GLOB_BRACE

<?php

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

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

GLOB_BRACE permette a una sola chiamata di coprire quattro estensioni, molto più pulito che eseguire glob() quattro volte e unire i risultati.

Elencare solo le sottodirectory

<?php

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

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

Con GLOB_ONLYDIR, i file normali all'interno di storage/ vengono filtrati, quindi si ottengono solo le directory — utile per iterare su cartelle per utente, bucket di cache e simili.

Ordinare i risultati

Per impostazione predefinita glob() restituisce le corrispondenze in ordine alfabetico crescente. Se si ha bisogno di un ordine diverso — ad esempio il file più recente per primo — si ordina l'array manualmente:

<?php

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

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

print_r($files);

Qui usort() riordina l'elenco per data di modifica (filemtime()), dal più recente. Passare GLOB_NOSORT a glob() quando si ha intenzione di riordinare comunque — evita l'ordinamento iniziale ridondante su directory di grandi dimensioni.

Ricerca ricorsiva

glob() di per sé non scende nelle sottodirectory — * non attraversa mai un /. Per percorrere un intero albero, combinare glob() con GLOB_ONLYDIR e la ricorsione:

<?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'));

Per alberi profondi o molto grandi, RecursiveDirectoryIterator di PHP è di solito più adatto, ma questo pattern è sufficiente per la maggior parte dei lavori quotidiani.

Errori comuni

• I file nascosti vengono ignorati. Un * iniziale non corrisponde ai dot-file, quindi glob('*') non restituirà .env o .gitignore. Usare esplicitamente un pattern come glob('.*').
• Array vuoto vs. false. Un foreach su un array vuoto è innocuo, ma count(), array_map() e simili genereranno avvisi se glob() ha restituito false. Verificare prima con === false.
• Nessuna regex. glob() riconosce solo i metacaratteri shell. Per la corrispondenza con espressioni regolari su un elenco di nomi esistente, usare preg_grep() o testare singoli nomi con fnmatch().
• Percorsi multipiattaforma. Usare le barre in avanti (/) nei pattern anche su Windows, oppure costruire i percorsi con DIRECTORY_SEPARATOR, in modo che lo stesso codice funzioni ovunque.

Quando usare glob() vs. altri strumenti

• Usare glob() quando si vuole un elenco rapido e ordinato di percorsi che corrispondono a un semplice metacarattere in una directory.
• Usare scandir() quando si vuole ogni voce di una directory (inclusi i dot-file) e si intende filtrarla manualmente.
• Usare opendir() / readdir() per la lettura in streaming di directory molto grandi con basso consumo di memoria.
• Usare fnmatch() per testare un singolo nome rispetto a un pattern shell senza accedere al filesystem.

Una volta ottenuto un elenco di percorsi, pathinfo(), is_file() e file_exists() aiutano a esaminare ciascuno. Vedere la panoramica del PHP Filesystem per il quadro completo.

Conclusione

glob() è il modo più ergonomico per trovare file per pattern in PHP: si passa un metacarattere in stile shell e si ottiene un array ordinato di percorsi reali. Ricordare di verificare false quando gli errori sono importanti, usare GLOB_BRACE e GLOB_ONLYDIR per mantenere i pattern ordinati, e passare a un iteratore ricorsivo quando si ha bisogno di cercare in un intero albero.

Pratica