is_dir()

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

Функция is_dir() — это встроенная функция PHP, которая проверяет, существует ли указанный путь и является ли он директорией (папкой). Она возвращает true, если путь — это существующая директория, и false во всех остальных случаях: обычный файл, несуществующий путь или путь, к которому нет прав доступа.

Это одна из функций PHP для «проверки типа» в файловой системе, наряду с is_file(), is_link() и file_exists(). Используйте is_dir(), когда нужно убедиться, что директория существует, прежде чем читать её содержимое, записывать в неё файлы или создавать её.

Синтаксис

is_dir(string $filename): bool

• $filename — путь для проверки. Может быть абсолютным (/var/www/uploads) или относительным текущему рабочему каталогу скрипта (uploads). Завершающий слеш допустим.
• Возвращаемое значение — true, если $filename существует и является директорией, иначе false.

Простой пример

__DIR__ — это магическая константа, которая всегда указывает на существующую директорию, поэтому данный пример гарантированно выведет ветку «is a directory».

Различие между директорией и файлом

Чаще всего is_dir() используют для того, чтобы определить, что именно скрывается за путём. Сравните с is_file():

<?php

$paths = [__DIR__, __FILE__, '/path/that/does/not/exist'];

foreach ($paths as $path) {
    if (is_dir($path)) {
        echo "$path -> directory\n";
    } elseif (is_file($path)) {
        echo "$path -> file\n";
    } else {
        echo "$path -> missing\n";
    }
}

__FILE__ — это полный путь к текущему скрипту, поэтому он определяется как файл, а выдуманный путь — как отсутствующий.

Практический пример: создание директории, если она не существует

Защита mkdir() с помощью is_dir() позволяет избежать предупреждения, если папка уже существует:

<?php

$dir = sys_get_temp_dir() . '/my_app_cache';

if (!is_dir($dir)) {
    mkdir($dir, 0755, true); // true = create parent dirs too
    echo "Created: $dir";
} else {
    echo "Already exists: $dir";
}

Распространённые ошибки

• is_dir() возвращает false, а не ошибку, если путь не существует. Результат false не означает «это файл» — путь может просто отсутствовать. Используйте file_exists(), если нужно лишь убедиться, что что-то по этому пути есть.
• Символические ссылки разыменовываются. Если путь — это символическая ссылка, указывающая на директорию, is_dir() вернёт true. Для обнаружения самой ссылки используйте is_link().
• Результаты кешируются. PHP кеширует результаты stat(), поэтому если директория была создана или удалена другим процессом во время выполнения скрипта, вы можете получить устаревший ответ. Вызовите clearstatcache(), чтобы принудительно выполнить повторную проверку.
• Относительные пути зависят от рабочей директории. is_dir('data') разрешается относительно текущей рабочей директории (getcwd()), а не местоположения скрипта. Используйте __DIR__ . '/data', если имеете в виду «рядом с данным скриптом».

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

Заключение

is_dir() — это безопасный и стандартный способ убедиться, что путь является существующей директорией, прежде чем выполнять с ней какие-либо действия. Помните, что функция разыменовывает символические ссылки, кеширует результат и разрешает относительные пути относительно текущей рабочей директории. Использование is_dir() совместно с file_exists(), is_file() и mkdir() покрывает почти все ситуации, связанные с работой с директориями.

Практика