mkdir()

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

Функция mkdir() — это встроенная функция PHP, которая создаёт новую директорию в файловой системе. Она используется всякий раз, когда скрипту нужно создать папку во время выполнения — например, для хранения загруженных файлов, создания директорий кэша для каждого пользователя или подготовки папки для экспорта перед записью в неё отчётов.

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

Вот базовый синтаксис функции mkdir():

Синтаксис PHP для mkdir()

mkdir(string $directory, int $permissions = 0777, bool $recursive = false, ?resource $context = null): bool

Параметры

Примечание о правах доступа и umask

Переданное значение $permissions не применяется буквально. Операционная система вычитает из него процессный umask. Например, при распространённом umask 022 вызов mkdir($dir, 0777) создаст директорию с режимом 0755, а не 0777. По этой причине всегда передавайте тот режим, который вам действительно нужен, и не предполагайте, что 0777 означает «доступна всем для записи» — как правило, это не так.

В целях безопасности предпочитайте 0755 (владелец может читать/записывать/выполнять, остальные — только читать/выполнять) значению по умолчанию 0777. Если вам нужен точный режим независимо от umask, вызовите chmod() после создания директории.

Как использовать функцию mkdir()?

Использовать функцию mkdir() достаточно просто. Вот шаги, которые нужно выполнить:

1. Укажите путь к директории, которую хотите создать.
2. Вызовите функцию mkdir(), передав путь к директории в качестве первого параметра, необязательный режим прав доступа в качестве второго параметра и булев флаг в качестве третьего параметра для создания родительских директорий при необходимости.

Вот пример кода, демонстрирующий использование функции mkdir():

Как использовать функцию mkdir()?

<?php

$dir = '/path/to/new/directory';
// 0755 is recommended for security (owner: rwx, others: rx)
$permissions = 0755;
if (!is_dir($dir)) {
    if (mkdir($dir, $permissions, true)) {
        echo "Directory created successfully!";
    } else {
        echo "Failed to create directory.";
    }
} else {
    echo "Directory already exists!";
}

В этом примере мы используем is_dir(), чтобы проверить, существует ли целевая директория. Мы задаём более безопасный режим прав доступа (0755) и передаём true в качестве третьего аргумента для включения рекурсивного создания. Функция mkdir() возвращает булево значение, поэтому мы оборачиваем вызов в оператор if, чтобы корректно обработать успех или неудачу. Если директория не существует, мы пытаемся её создать и выводим сообщение об успехе или неудаче. Если она уже существует, выводим соответствующее сообщение.

Создание вложенных директорий

Без рекурсивного флага mkdir() может создать только последний сегмент пути — все родительские директории уже должны существовать. Передача true в качестве третьего аргумента указывает PHP создать всю цепочку за один раз:

<?php

// Fails if "cache" or "cache/images" don't already exist:
// mkdir('cache/images/thumbs');           // Warning + returns false

// Works — creates cache, cache/images and cache/images/thumbs as needed:
if (mkdir('cache/images/thumbs', 0755, true)) {
    echo 'Nested directories created.';
}

Возвращаемое значение и обработка ошибок

mkdir() возвращает true при успехе и false при неудаче. При неудаче она также генерирует E_WARNING — например, когда родительская директория отсутствует, путь уже существует или у процесса нет прав на запись.

Есть два чистых способа справиться с этим предупреждением:

<?php

// 1. Guard with is_dir() so you never try to recreate an existing folder.
$dir = 'uploads';
if (!is_dir($dir) && !mkdir($dir, 0755, true) && !is_dir($dir)) {
    // The second is_dir() guards against a race where another
    // process created the directory between our two checks.
    throw new RuntimeException("Directory \"$dir\" could not be created");
}

// 2. Suppress the warning with @ only if you immediately check the result.
if (!@mkdir($dir, 0755) && !is_dir($dir)) {
    echo 'Could not create directory.';
}

Не используйте @ само по себе, без проверки возвращаемого значения — молчаливое подавление предупреждения делает ошибки незаметными.

Распространённые подводные камни

• Директория уже существует. mkdir() возвращает false и выдаёт предупреждение. Всегда проверяйте с помощью is_dir() заранее или используйте рассмотренный выше идиоматический приём с рекурсивным созданием.
• Права доступа фильтруются через umask. Как описано выше, переданный режим маскируется. Используйте chmod() для точного режима.
• Относительные пути зависят от рабочей директории. Относительный путь разрешается относительно текущей директории скрипта, которая может отличаться от расположения файла. При сомнениях используйте абсолютный путь (например, __DIR__ . '/uploads').
• Windows полностью игнорирует аргумент прав доступа — там это не имеет никакого эффекта.

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

• rmdir() — удалить пустую директорию (аналог mkdir() для удаления).
• scandir() — получить список содержимого директории.
• chmod() — изменить права доступа к директории после её создания.
• fopen() — открыть или создать файл, когда директория уже существует.

Заключение

Функция mkdir() — полезный инструмент PHP для создания новых директорий в файловой системе. Ключевые моменты, которые нужно помнить: передавайте явный, безопасный режим прав доступа (например, 0755), а не полагайтесь на значение по умолчанию 0777; используйте рекурсивный флаг, когда родительские директории могут отсутствовать; всегда проверяйте возвращаемое булево значение, чтобы ошибки не оставались незамеченными. Придерживаясь этих привычек, mkdir() станет надёжным строительным блоком для любого скрипта, работающего с файловой системой.

Практика