dirname()

Функция PHP dirname()

Функция dirname() возвращает часть пути, соответствующую родительскому каталогу. Получив полный путь к файлу или директории, она отсекает последний компонент и возвращает каталог, в котором он содержится. На этой странице описаны синтаксис, параметр $levels, граничные случаи и отличия dirname() от связанных функций работы с путями.

Это исключительно строковая операция: dirname() разбирает текст переданного пути. Она не обращается к файловой системе, поэтому путь не обязан указывать на реально существующий файл.

Синтаксис

dirname(string $path, int $levels = 1): string

• $path — путь, с которым выполняется операция (обязательный).
• $levels — количество уровней каталогов, на которое нужно подняться вверх. По умолчанию равно 1. Доступен начиная с PHP 7.0; должен быть не менее 1.

Функция возвращает родительский каталог $path в виде string.

Параметры

Примеры

Получить каталог файла

Следующий код извлекает каталог, содержащий example.txt:

Вывод:

/home/user1

Получить родительский каталог директории

Завершающий слеш воспринимается как конец имени каталога, поэтому dirname() всё равно возвращает родительский каталог:

Вывод:

/home/user1

Подъём на несколько уровней с помощью $levels

Передайте второй аргумент, чтобы подняться выше по дереву за один вызов:

<?php

echo dirname("/usr/local/lib", 2);

Вывод:

/usr

Это эквивалентно dirname(dirname("/usr/local/lib")), но читается чище, когда нужно подняться на несколько уровней.

Граничные случаи

dirname() имеет несколько результатов, которые поначалу удивляют:

<?php

echo dirname("example.txt"), "\n";   // "."  — no directory part, so current dir
echo dirname("/"), "\n";             // "/"  — root has no parent
echo dirname(""), "\n";              // "."

• Путь без компонента каталога возвращает . (текущий каталог), а не пустую строку.
• Корневой путь возвращает сам себя.
• В Windows в качестве разделителей каталогов принимаются как /, так и \.

dirname() и связанные функции

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

Распространённый шаблон — построение путей относительно текущего файла:

<?php

// Load config that sits one directory above this script.
require dirname(__DIR__) . "/config.php";

Заключение

dirname() извлекает родительский каталог из пути как простую строковую операцию. Помните, что она никогда не обращается к файловой системе, что путь без каталога возвращает . и что аргумент $levels позволяет подняться на несколько уровней за один вызов. Для получения компонента имени файла используйте basename(); для получения всего сразу — pathinfo().

Практика