Исчерпывающее руководство по функции basename() в PHP

Рано или поздно в процессе разработки на PHP вам потребуется работать с путями к файлам. Будь то получение имени файла, его расширения или содержащего каталога — вы будете часто иметь дело с путями. Одной из наиболее часто используемых функций для этого является функция basename() в PHP.

В этом руководстве мы подробно разберём функцию basename(), охватив всё необходимое для её эффективного использования в PHP-проектах.

Что такое функция basename()?

Функция basename() — это встроенная функция PHP, которая возвращает конечный компонент имени файлового пути. Проще говоря, она возвращает имя файла или каталога из заданного пути.

Синтаксис функции basename() следующий:

Синтаксис функции PHP basename()

basename( string $path, string $suffix );

Функция принимает два параметра:

• $path — путь к файлу или каталогу.
• $suffix — необязательный суффикс для удаления из имени файла.

Рассмотрим несколько примеров, чтобы увидеть, как работает функция.

Пример функции PHP basename()

Как видите, функция basename() возвращает имя файла или каталога, находящегося в конце пути.

Как работает функция basename()?

Функция basename() выполняет исключительно строковые манипуляции — она никогда не обращается к файловой системе. Она находит последний разделитель каталогов в пути и возвращает всё, что идёт после него. Поскольку функция не проверяет путь, файл или каталог не обязан существовать для того, чтобы basename() вернула результат.

Несколько особенностей поведения стоит запомнить:

• Завершающие разделители отсекаются. basename("/var/www/html/") возвращает html, а не пустую string. Функция удаляет завершающие слеши перед извлечением последнего компонента.
• Разделитель зависит от платформы. В Unix-подобных системах только / считается разделителем. В Windows распознаются как /, так и \. Это означает, что путь в стиле Windows вроде C:\xampp\app.php на Linux/macOS возвращается без изменений, поскольку \ там не является разделителем.
• Функция работает побайтово, а не «умно». basename() не разбирает URL. При передаче http://example.com/page.html?id=5 возвращается page.html?id=5 — строка запроса сохраняется, так как идёт после последнего /. Для URL сначала используйте parse_url().

Если указан необязательный параметр $suffix, он удаляется из конца имени файла перед возвратом результата.

Удаление суффиксов с помощью $suffix

Второй аргумент позволяет убрать известный суффикс — чаще всего расширение файла — за один шаг:

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

Два момента, на которых часто ошибаются:

• Сравнение чувствительно к регистру. basename("/img/PHOTO.PNG", ".png") возвращает PHOTO.PNG без изменений, поскольку .PNG ≠ .png. Сначала нормализуйте регистр или передавайте суффикс именно в том виде, в котором он присутствует.
• Функция удаляет только суффикс, а не «настоящее» расширение. Если вам нужно само расширение или имя без какого бы то ни было расширения, используйте pathinfo() — она понимает расширения:

<?php

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

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

Почему функция basename() полезна?

Функция basename() невероятно полезна при работе с путями к файлам в PHP. Некоторые распространённые случаи применения:

• Получение имени файла для отображения пользователям.
• Удаление расширения файла из его имени.
• Получение имени каталога, содержащего файл.

Используя функцию basename(), вы можете легко манипулировать путями к файлам для получения нужной информации.

Практический пример: безопасное имя для скачивания

Распространённая задача — взять серверный путь к файлу и показать пользователю только имя файла, например в заголовке загрузки. basename() — правильный инструмент для этого, поскольку отбрасывает часть пути с каталогами независимо от его глубины:

<?php

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

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

Это также важно с точки зрения безопасности: когда путь формируется из пользовательского ввода, basename() сворачивает любые сегменты ../ до одного имени, что делает её полезной защитой от обхода каталогов, когда нужно получить только чистое имя файла.

Рекомендации по использованию функции basename()

При использовании функции basename() в PHP-проектах стоит помнить о нескольких правилах хорошего тона.

Всегда используйте функцию basename() для извлечения имён файлов

При извлечении имён файлов из путей всегда используйте функцию basename(). Хотя для достижения того же результата можно использовать строковые функции манипуляции, функция basename() надёжнее и эффективнее.

Будьте осторожны с параметром $suffix

Если вы используете параметр $suffix для удаления расширения файла, убедитесь, что включили ведущую точку . и суффикс точно соответствует завершающим символам. Сравнение чувствительно к регистру, и суффикс будет удалён только в том случае, если он точно совпадает с концом имени файла.

Обрабатывайте ошибки корректно

Если функция basename() сталкивается с ошибкой (например, пустым путём), она возвращает пустую string "". Убедитесь, что корректно обрабатываете это в коде, чтобы избежать неожиданного поведения.

Заключение

Функция basename() — мощный инструмент для работы с путями к файлам в PHP. Понимая принципы её работы и следуя рекомендациям по использованию, вы сможете сделать свои PHP-проекты более эффективными и надёжными.

После изучения данного руководства вы должны обладать полным пониманием функции basename() и уметь эффективно применять её в своих PHP-проектах.

Диаграмма ниже показывает, как basename() обрабатывает путь:

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

Связанные функции

basename() — одна из нескольких функций PHP для работы с путями. Используйте другие функции, когда вам нужно:

• dirname() — каталог из пути (противоположность basename()).
• pathinfo() — каталог, имя файла, базовое имя и расширение одновременно.
• realpath() — абсолютный канонический путь с разрешёнными символическими ссылками.
• file_exists() — проверка того, указывает ли путь на реальный файл или каталог.

Практика