scandir()

Introduzione

La gestione delle directory è una parte essenziale della programmazione PHP — quasi ogni script di backup, uploader di file o processore di risorse deve elencare il contenuto di una cartella. Questo articolo approfondisce la funzione PHP scandir(), che legge il contenuto di una directory in una singola chiamata. Imparerai cosa restituisce, come ordinare e filtrare il risultato, come si differenzia da glob() e come gestire gli errori in modo sicuro.

Cos'è scandir?

scandir() legge una directory e restituisce i nomi di tutte le voci in essa contenute — file e sottodirectory — come un array piatto di stringhe. L'array include sempre le due voci speciali . (la directory corrente) e .. (la directory padre), quindi quasi sempre le si filtra prima di utilizzare il risultato.

Se la directory non può essere letta, scandir() restituisce false ed emette un avviso. La funzione è disponibile da PHP 4.3.0 e funziona sia su sistemi Unix che su Windows.

Sintassi

scandir(string $directory, int $sorting_order = SCANDIR_SORT_ASCENDING, ?resource $context = null): array|false

La funzione restituisce un array di nomi di file in caso di successo o false in caso di errore.

I nomi vengono restituiti senza il percorso della directory. Per ottenere un percorso utilizzabile, anteponi la directory manualmente: $directory . '/' . $entry.

Come funziona scandir?

Nella sua forma più semplice si passa solo il percorso della directory. Il contenuto viene restituito ordinato alfabeticamente (in ordine crescente) perché questo è il $sorting_order predefinito. L'esempio seguente filtra . e .. con array_diff() in modo che rimangano solo le voci reali:

Esempio della funzione scandir() in PHP

<?php

$dir = "/path/to/directory";
$files = scandir($dir);

// Filter out the current and parent directory entries
$filtered = array_diff($files, ['.', '..']);

foreach ($filtered as $file) {
    echo $file . "<br>";
}

Questo codice mostra un elenco di file e sottodirectory nella directory specificata, escludendo . e ...

Ordinare il contenuto della directory

Passa un secondo argomento per controllare l'ordine del risultato. Le tre opzioni sono:

• SCANDIR_SORT_ASCENDING — alfabetico A→Z (il predefinito).
• SCANDIR_SORT_DESCENDING — alfabetico Z→A.
• SCANDIR_SORT_NONE — nessun ordinamento; le voci vengono restituite nell'ordine fornito dal filesystem. Questa è l'opzione più veloce ed è utile quando si intende ordinare l'elenco autonomamente, o quando l'ordine non è rilevante.

Ad esempio, data una directory contenente archive.txt, data.csv, report.txt, notes.md, image.png e una sottodirectory backups:

Come ordinare l'output di scandir() in ordine decrescente

<?php

$dir = "/path/to/directory";
$files = scandir($dir, SCANDIR_SORT_DESCENDING);

print_r($files);
// Array
// (
//     [0] => report.txt
//     [1] => notes.md
//     [2] => image.png
//     [3] => data.csv
//     [4] => backups
//     [5] => ..
//     [6] => .
// )

Gli stessi dati con SCANDIR_SORT_NONE vengono restituiti non ordinati (l'ordine esatto dipende dal filesystem), evitando il piccolo overhead dell'ordinamento.

Elencare solo file (o solo directory)

scandir() restituisce file e cartelle mescolati insieme. Per mantenere solo i file, verifica ogni voce con is_file(); per mantenere solo le directory, usa is_dir(). Ricorda di costruire prima il percorso completo:

<?php

$dir = "/path/to/directory";
$entries = array_diff(scandir($dir), ['.', '..']);

$filesOnly = array_filter($entries, fn($entry) => is_file($dir . '/' . $entry));

print_r(array_values($filesOnly));
// Array
// (
//     [0] => archive.txt
//     [1] => data.csv
//     [2] => image.png
//     [3] => notes.md
//     [4] => report.txt
// )

Filtrare per estensione file

Un'operazione comune è recuperare solo i file di un determinato tipo. Combina scandir() con pathinfo() per leggere l'estensione di ogni voce:

<?php

$dir = "/path/to/directory";
$entries = array_diff(scandir($dir), ['.', '..']);

$textFiles = array_filter(
    $entries,
    fn($entry) => pathinfo($entry, PATHINFO_EXTENSION) === 'txt'
);

print_r(array_values($textFiles));
// Array
// (
//     [0] => archive.txt
//     [1] => report.txt
// )

Se devi solo abbinare file tramite un pattern, glob() può farlo in un solo passaggio — ad esempio glob("$dir/*.txt") — e restituisce percorsi completi. Usa glob() per il pattern matching e scandir() quando vuoi ogni voce e pieno controllo sul filtraggio.

Gestione degli errori

La funzione scandir può fallire se il percorso della directory specificato non è valido o se la directory non dispone dei permessi appropriati. In caso di errore, restituisce false e genera un avviso. Non lancia eccezioni, quindi dovresti verificare direttamente il valore di ritorno. Ecco un esempio:

Esempio della funzione scandir() in PHP con gestione degli errori

<?php

$dir = "/path/to/directory";
$files = scandir($dir);

if ($files === false) {
    echo "Error: Could not read the directory.";
} else {
    foreach ($files as $file) {
        echo $file . "<br>";
    }
}

Questo codice controlla il valore di ritorno di scandir() e mostra un messaggio di errore se la directory non può essere letta. Poiché scandir() genera un avviso (non un'eccezione) quando fallisce, il controllo rigoroso === false è ciò che protegge effettivamente il codice — silenziare l'avviso con @scandir() è sconsigliato, poiché si perde il messaggio diagnostico.

Per evitare completamente l'avviso, verifica che il percorso sia una directory leggibile prima di chiamare scandir():

<?php

$dir = "/path/to/directory";

if (is_dir($dir)) {
    $files = scandir($dir);

    foreach (array_diff($files, ['.', '..']) as $file) {
        echo $file . "<br>";
    }
} else {
    echo "Error: '$dir' is not a valid directory.";
}

scandir() vs altre funzioni per le directory

Per una panoramica del toolkit più ampio, consulta Lavorare con le directory in PHP.

Conclusione

La funzione scandir() è un modo comodo e immediato per leggere il contenuto di una directory in PHP. Hai visto come elencare le voci, ordinarle con le tre costanti SCANDIR_SORT_*, mantenere solo i file o solo le directory, filtrare per estensione e gestire gli errori in modo sicuro. Usa scandir() quando vuoi l'elenco completo e pieno controllo; usa glob() quando basta un semplice pattern match.

Pratica