Le guide complet de la fonction basename() en PHP

À un moment ou un autre dans votre parcours de développement PHP, vous aurez besoin de manipuler des chemins de fichiers. Que ce soit pour obtenir le nom d'un fichier, son extension ou le répertoire qui le contient, vous travaillerez beaucoup avec des chemins de fichiers. L'une des fonctions les plus couramment utilisées à cet effet est la fonction basename() de PHP.

Dans ce guide, nous allons examiner en profondeur la fonction basename(), en couvrant tout ce que vous devez savoir pour l'utiliser efficacement dans vos projets PHP.

Qu'est-ce que la fonction basename() ?

La fonction basename() est une fonction PHP intégrée qui retourne le dernier composant du nom d'un chemin de fichier. En termes simples, elle retourne le nom d'un fichier ou d'un répertoire à partir d'un chemin donné.

La syntaxe d'utilisation de la fonction basename() est la suivante :

Syntaxe de la fonction PHP basename()

basename( string $path, string $suffix );

La fonction prend deux paramètres :

• $path - Le chemin vers un fichier ou un répertoire.
• $suffix - Un suffixe optionnel à supprimer du nom de fichier.

Voyons quelques exemples pour comprendre comment fonctionne la fonction.

Exemple de la fonction PHP basename()

Comme vous pouvez le voir, la fonction basename() retourne le nom du fichier ou du répertoire situé à la fin du chemin.

Comment fonctionne la fonction basename() ?

La fonction basename() fonctionne par manipulation de chaînes de caractères pure — elle ne touche jamais le système de fichiers. Elle trouve le dernier séparateur de répertoire dans le chemin et retourne tout ce qui suit. Comme elle ne valide pas le chemin, le fichier ou le répertoire n'a pas besoin d'exister pour que basename() retourne un résultat.

Quelques comportements méritent d'être mémorisés :

• Les séparateurs de fin sont supprimés. basename("/var/www/html/") retourne html, et non une chaîne vide. La fonction supprime les barres obliques de fin avant d'extraire le dernier composant.
• Le séparateur dépend de la plateforme. Sur les systèmes de type Unix, seul / est traité comme séparateur. Sous Windows, / et \ sont tous deux reconnus. Cela signifie qu'un chemin de style Windows comme C:\xampp\app.php est retourné inchangé sous Linux/macOS, car \ n'y est pas un séparateur.
• La fonction est orientée octets, pas "intelligente". basename() n'analyse pas les URL. Passer http://example.com/page.html?id=5 retourne page.html?id=5 — la chaîne de requête est conservée car elle se trouve après le dernier /. Pour les URL, utilisez d'abord parse_url().

Si le paramètre optionnel $suffix est fourni, il supprime ce suffixe de la fin du nom de fichier avant de le retourner.

Suppression de suffixes avec $suffix

Le deuxième argument vous permet de supprimer un suffixe connu — le plus souvent une extension de fichier — en une seule étape :

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

Deux pièges courants à éviter :

• La correspondance est sensible à la casse. basename("/img/PHOTO.PNG", ".png") retourne PHOTO.PNG inchangé, car .PNG ≠ .png. Normalisez la casse en premier, ou passez le suffixe exactement tel qu'il apparaît.
• La fonction ne supprime que le suffixe, jamais une "vraie" extension. Si vous avez besoin de l'extension elle-même, ou du nom sans quelle que soit l'extension présente, utilisez pathinfo() à la place — elle comprend les extensions :

<?php

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

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

Pourquoi la fonction basename() est-elle utile ?

La fonction basename() est extrêmement utile lorsqu'on travaille avec des chemins de fichiers en PHP. Parmi les cas d'utilisation courants, on trouve :

• Obtenir le nom d'un fichier pour l'afficher aux utilisateurs.
• Supprimer l'extension d'un nom de fichier.
• Obtenir le nom du répertoire qui contient un fichier.

En utilisant la fonction basename(), vous pouvez facilement manipuler des chemins de fichiers pour obtenir les informations dont vous avez besoin.

Exemple concret : un nom de téléchargement sécurisé

Une tâche courante consiste à prendre un chemin de fichier côté serveur et à n'afficher que le nom du fichier à l'utilisateur — par exemple, dans un en-tête de téléchargement. basename() est l'outil approprié car il supprime la partie répertoire quelle que soit la profondeur du chemin :

<?php

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

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

C'est également important pour la sécurité : lorsqu'un chemin est construit à partir d'une entrée utilisateur, basename() réduit tous les segments de traversée ../ à un simple nom, ce qui en fait un garde-fou utile contre la traversée de répertoires lorsque vous ne voulez qu'un nom de fichier brut.

Bonnes pratiques pour utiliser la fonction basename()

Lorsque vous utilisez la fonction basename() dans vos projets PHP, voici quelques bonnes pratiques à garder à l'esprit.

Toujours utiliser la fonction basename() pour l'extraction de noms de fichiers

Pour extraire des noms de fichiers à partir de chemins, utilisez toujours la fonction basename(). Bien qu'il soit possible d'utiliser des fonctions de manipulation de chaînes pour obtenir le même résultat, la fonction basename() est plus fiable et efficace.

Faites attention au paramètre $suffix

Si vous utilisez le paramètre $suffix pour supprimer une extension de fichier, assurez-vous d'inclure le point initial . et vérifiez qu'il correspond exactement aux caractères finaux. La comparaison est sensible à la casse, et le suffixe ne sera supprimé que s'il correspond exactement à la fin du nom de fichier.

Gérez les erreurs de manière appropriée

Si la fonction basename() rencontre une erreur (par exemple un chemin vide), elle retourne une chaîne vide "". Assurez-vous de gérer cela de manière appropriée dans votre code pour éviter un comportement inattendu.

Conclusion

La fonction basename() est un outil puissant pour travailler avec des chemins de fichiers en PHP. En comprenant son fonctionnement et en suivant les bonnes pratiques pour son utilisation, vous pouvez rendre vos projets de développement PHP plus efficaces et fiables.

Avec ce guide, vous devriez maintenant avoir une compréhension complète de la fonction basename() et être en mesure de l'utiliser efficacement dans vos projets PHP.

Le diagramme ci-dessous résume comment basename() résout un chemin :

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

Fonctions connexes

basename() fait partie de plusieurs fonctions PHP permettant de travailler avec des chemins. Utilisez une autre fonction lorsque vous avez besoin de :

• dirname() — la partie répertoire d'un chemin (l'opposé de basename()).
• pathinfo() — le répertoire, le nom de fichier, le nom de base et l'extension en une seule fois.
• realpath() — le chemin absolu et canonique avec les liens symboliques résolus.
• file_exists() — pour vérifier si le chemin pointe réellement vers un fichier ou un répertoire existant.

Exercice