La Guida Definitiva alla Funzione basename() di PHP

Prima o poi nel tuo percorso di sviluppo PHP avrai bisogno di manipolare i percorsi dei file. Che si tratti di ottenere il nome di un file, la sua estensione o la directory che lo contiene, lavorerai spesso con i percorsi dei file. Una delle funzioni più comunemente usate per questo scopo è la funzione basename() di PHP.

In questa guida, approfondiremo la funzione basename(), coprendo tutto ciò che devi sapere per usarla efficacemente nei tuoi progetti PHP.

Cos'è la funzione basename()?

La funzione basename() è una funzione PHP integrata che restituisce il componente finale del nome di un percorso file. In parole più semplici, restituisce il nome di un file o di una directory da un percorso specificato.

La sintassi per usare la funzione basename() è la seguente:

La sintassi della funzione PHP basename()

basename( string $path, string $suffix );

La funzione accetta due parametri:

• $path - Il percorso di un file o di una directory.
• $suffix - Un suffisso opzionale da rimuovere dal nome del file.

Vediamo alcuni esempi per capire come funziona la funzione.

Esempio della funzione PHP basename()

Come si può notare, la funzione basename() restituisce il nome del file o della directory alla fine del percorso.

Come funziona la funzione basename()?

La funzione basename() opera mediante pura manipolazione di stringhe — non accede mai al filesystem. Trova l'ultimo separatore di directory nel percorso e restituisce tutto ciò che viene dopo. Poiché non valida il percorso, il file o la directory non devono necessariamente esistere affinché basename() restituisca un risultato.

Vale la pena ricordare alcuni comportamenti:

• I separatori finali vengono rimossi. basename("/var/www/html/") restituisce html, non una stringa vuota. La funzione elimina le barre finali prima di estrarre il componente.
• Il separatore dipende dalla piattaforma. Sui sistemi Unix-like solo / viene trattato come separatore. Su Windows vengono riconosciuti sia / che \. Ciò significa che un percorso in stile Windows come C:\xampp\app.php viene restituito invariato su Linux/macOS, poiché \ non è un separatore lì.
• È orientato ai byte, non "intelligente". basename() non analizza gli URL. Passare http://example.com/page.html?id=5 restituisce page.html?id=5 — la query string viene mantenuta perché segue l'ultimo /. Per gli URL, usa prima parse_url().

Se viene fornito il parametro opzionale $suffix, esso rimuove quel suffisso dalla fine del nome del file prima di restituirlo.

Rimuovere suffissi con $suffix

Il secondo argomento consente di eliminare un suffisso noto — nella maggior parte dei casi un'estensione di file — in un solo passaggio:

<?php

echo basename("/uploads/2024/report.final.pdf") . PHP_EOL;            // report.final.pdf
echo basename("/uploads/2024/report.final.pdf", ".pdf") . PHP_EOL;    // report.final
echo basename("/home/user/archive.tar.gz", ".tar.gz") . PHP_EOL;      // archive

Due insidie comuni da tenere a mente:

• La corrispondenza è sensibile alle maiuscole. basename("/img/PHOTO.PNG", ".png") restituisce PHOTO.PNG invariato, perché .PNG ≠ .png. Normalizza prima le maiuscole oppure passa il suffisso esattamente come appare.
• Rimuove solo il suffisso, non una "vera" estensione. Se hai bisogno dell'estensione stessa, o del nome senza qualunque estensione presente, usa invece pathinfo() — che gestisce le estensioni correttamente:

<?php

$path = "/path/to/archive.tar.gz";

echo pathinfo($path, PATHINFO_FILENAME) . PHP_EOL;   // archive.tar
echo pathinfo($path, PATHINFO_EXTENSION) . PHP_EOL;  // gz

Perché la funzione basename() è utile?

La funzione basename() è estremamente utile quando si lavora con i percorsi dei file in PHP. Alcuni casi d'uso comuni includono:

• Ottenere il nome di un file da mostrare agli utenti.
• Rimuovere l'estensione dal nome di un file.
• Ottenere il nome della directory che contiene un file.

Usando la funzione basename(), puoi facilmente manipolare i percorsi dei file per ottenere le informazioni di cui hai bisogno.

Esempio pratico: un nome di download sicuro

Un'attività comune consiste nel prendere un percorso file lato server e mostrare all'utente solo il nome del file — ad esempio in un header di download. basename() è lo strumento giusto perché scarta la parte della directory indipendentemente dalla profondità del percorso:

<?php

$storedPath = "/var/www/storage/invoices/2024/INV-00042.pdf";
$downloadName = basename($storedPath);

header("Content-Disposition: attachment; filename=\"$downloadName\"");
// filename="INV-00042.pdf"

Questo è importante anche per la sicurezza: quando un percorso è costruito a partire dall'input dell'utente, basename() collassa eventuali segmenti di traversal ../ in un singolo nome, risultando una protezione utile contro il directory traversal quando si vuole ottenere solo il nome del file.

Best practice per usare la funzione basename()

Quando si usa la funzione basename() nei propri progetti PHP, ci sono alcune best practice da tenere a mente.

Usa sempre la funzione basename() per estrarre i nomi dei file

Quando estrai nomi di file dai percorsi, usa sempre la funzione basename(). Sebbene sia possibile usare funzioni di manipolazione delle stringhe per ottenere lo stesso risultato, la funzione basename() è più affidabile ed efficiente.

Presta attenzione al parametro $suffix

Se stai usando il parametro $suffix per rimuovere un'estensione, assicurati di includere il punto iniziale . e di far corrispondere esattamente i caratteri finali. Il confronto è sensibile alle maiuscole, e il suffisso verrà rimosso solo se corrisponde esattamente alla fine del nome del file.

Gestisci gli errori in modo appropriato

Se la funzione basename() incontra un errore (come un percorso vuoto), restituisce una stringa vuota "". Assicurati di gestire questa situazione in modo appropriato nel tuo codice per evitare comportamenti inattesi.

Conclusione

La funzione basename() è uno strumento potente per lavorare con i percorsi dei file in PHP. Comprendendo come funziona e seguendo le best practice per il suo utilizzo, puoi rendere i tuoi progetti PHP più efficienti e affidabili.

Con questa guida, dovresti ora avere una comprensione completa della funzione basename() ed essere in grado di usarla efficacemente nei tuoi progetti PHP.

Il diagramma seguente riassume come basename() risolve un percorso:

graph TD;
    A[Path] --> B{basename()};
    B -->|No suffix| C[File name];
    B -->|With suffix| D[File name without suffix];

Funzioni correlate

basename() è una delle diverse funzioni PHP per lavorare con i percorsi. Usa una funzione diversa quando hai bisogno di:

• dirname() — la parte della directory di un percorso (l'opposto di basename()).
• pathinfo() — directory, nome file, nome base ed estensione tutti insieme.
• realpath() — il percorso assoluto e canonico con i symlink risolti.
• file_exists() — per verificare se il percorso punta effettivamente a un file o a una directory reale.

Esercitati