Функции для работы с файловой системой в Битрикс D7.Создание директорий с помощью метода \Bitrix\Main\IO\Directory::createDirectory

Когда при разработке на 1С-Битрикс встает задача динамического создания каталогов, многие вспоминают старую функцию CheckDirPath(). Однако в современном ядре Bitrix существует более удобное и понятное решение: статический метод \Bitrix\Main\IO\Directory::createDirectory($path). Этот метод является «оберткой» над mkdir() с нужными правами доступа и созданием вложенных каталогов, что упрощает код и делает его более читаемым.

В данной статье мы рассмотрим, как пользоваться методом createDirectory, приведем несколько примеров кода и расскажем о нюансах, связанных с его использованием.

Коротко о методе createDirectory

Метод объявлен следующим образом:

public static function createDirectory($path)
{
    $dir = new self($path);
    $dir->create();

    return $dir;
}

• Пространство имен: \Bitrix\Main\IO\Directory
• Файл, где расположен класс: bitrix/modules/main/lib/io/directory.php
• Описание: Создает директорию по полному пути, включая все родительские (аналогично mkdir($path, BX_DIR_PERMISSIONS, true)).
• Аргумент:
  • $path — полный путь на сервере от корня ($_SERVER['DOCUMENT_ROOT'] в большинстве случаев).

Метод возвращает объект того же класса \Bitrix\Main\IO\Directory, что позволяет потом вызывать на нем дополнительные методы (например, проверять, существует ли каталог, устанавливать права и т.д.).

Отличие от старой функции CheckDirPath

В старом ядре 1С-Битрикс для создания директории использовалась функция:

CheckDirPath($path);

Она также создавала директорию (при необходимости — рекурсивно). Однако, начиная с перехода к современному ядру D7, предпочтительнее использовать класс \Bitrix\Main\IO\Directory и его метод createDirectory(). Это обеспечивает более объектно-ориентированный подход, лучшую интеграцию с другими классами ядра и удобные методы работы с директориями.

Пример 1. Создание каталога в папке /upload/

Наиболее распространенный сценарий — создание папки в разделе upload, куда часто загружаются файлы:

use \Bitrix\Main\IO\Directory;

$path = $_SERVER['DOCUMENT_ROOT'] . '/upload/custom_folder/';

Directory::createDirectory($path);

// Теперь каталог /upload/custom_folder/ должен существовать

1. Подключаем пространство имен Bitrix\Main\IO\Directory.
2. Формируем полный путь, опираясь на $_SERVER['DOCUMENT_ROOT'].
3. Вызываем статический метод createDirectory.
4. Как результат — создается каталог custom_folder (если он не существовал), а при необходимости и родительские каталоги.

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

Если нужно создать сразу несколько вложенных директорий (например, /upload/custom_folder/images/), то достаточно передать конечный путь:

use \Bitrix\Main\IO\Directory;

$path = $_SERVER['DOCUMENT_ROOT'] . '/upload/custom_folder/images/';

Directory::createDirectory($path);

Метод рекурсивно создаст цепочку директорий:

• custom_folder
• images

Если какой-то из каталогов уже существует, он будет пропущен и ошибки не произойдет.

Пример 3. Работа с объектом после создания

Поскольку createDirectory($path) возвращает объект класса \Bitrix\Main\IO\Directory, можно использовать его для дальнейших операций:

use \Bitrix\Main\IO\Directory;

$path = $_SERVER['DOCUMENT_ROOT'] . '/upload/projects/';

$directoryObject = Directory::createDirectory($path);

// Проверим, успешно ли создана директория
if ($directoryObject->isExists()) {
    echo "Директория успешно создана или уже существует.";
} else {
    echo "Не удалось создать директорию.";
}

// Дополнительно можно вывести размер каталога (если есть файлы)
echo "Размер каталога: " . $directoryObject->getSize() . " байт";

Здесь:

1. Создаем директорию.
2. Сохраняем возвращенный объект в $directoryObject.
3. Используем метод ->isExists() для проверки существования.
4. При необходимости — другие методы класса Directory (например, ->getSize()).

Пример 4. Создание директорий в компонентах

Допустим, в своем компоненте вы хотите автоматически создавать папку cache для хранения временных файлов:

use \Bitrix\Main\IO\Directory;

class CustomComponent extends CBitrixComponent
{
    public function onPrepareComponentParams($arParams)
    {
        // Допустим, путь к файлу для кеширования передается в параметрах
        $arParams['CACHE_DIR'] = $_SERVER['DOCUMENT_ROOT'].'/upload/custom_cache/';
        return $arParams;
    }

    public function executeComponent()
    {
        $this->createCacheDir();
        // ... другой код компонента ...
        $this->includeComponentTemplate();
    }

    protected function createCacheDir()
    {
        Directory::createDirectory($this->arParams['CACHE_DIR']);
    }
}

В примере выше в методе onPrepareComponentParams() указывается путь до нужной директории, а в executeComponent() вызывается метод, ответственный за ее создание. Таким образом, при каждом запуске компонента — если каталога не существует, он будет создан.

Пример 5. Создание папки при загрузке файла (API-обработчик)

Часто нужно сначала создать каталог, а затем сохранять в нем файл, загружаемый пользователем. Пример (упрощенный сценарий):

use \Bitrix\Main\IO\Directory;

// Допустим, у нас есть форма, которая отправляет файл
if ($_FILES['USER_FILE']['error'] === UPLOAD_ERR_OK)
{
    $uploadDir = $_SERVER['DOCUMENT_ROOT'] . '/upload/user_files/';
    Directory::createDirectory($uploadDir);

    $fileName = basename($_FILES['USER_FILE']['name']);
    $destination = $uploadDir . $fileName;

    if (move_uploaded_file($_FILES['USER_FILE']['tmp_name'], $destination)) {
        echo "Файл успешно загружен в $destination";
    } else {
        echo "Ошибка при сохранении файла.";
    }
}

1. Проверяем, что файл пришел без ошибок (UPLOAD_ERR_OK).
2. Формируем директорию для загрузки.
3. Вызываем Directory::createDirectory.
4. Сохраняем загруженный файл в созданную папку.

Дополнительные рекомендации

1. Используйте абсолютные пути. При работе с файлами и директориями в Bitrix всегда лучше опираться на $_SERVER['DOCUMENT_ROOT'] для формирования пути. Относительные пути могут вызвать ошибки при работе в разных окружениях (особенно под Windows или при необычных настройках веб-сервера).
2. Проверяйте код на тестовом окружении. Перед тем как выкатить в продакшен, обязательно протестируйте, чтобы избежать ситуаций, когда директорий невозможно создать по причине отсутствия прав или из-за неверной конфигурации.
3. Следите за правами доступа. По умолчанию BX_DIR_PERMISSIONS в 1С-Битрикс соответствует 0755 для директорий (или настройкам сервера). Если вам нужны другие права, вы можете установить их вручную позже или же воспользоваться методами для изменения прав (chmod). Но в большинстве случаев стандартные права подходят.
4. Используйте создание директорий «по требованию». Иногда имеет смысл не создавать каталоги заранее, а формировать их ровно в тот момент, когда это нужно. Это освобождает от хранения лишних пустых папок и упрощает логику, но требует дополнительной проверки существования папки перед использованием.

Заключение

Метод \Bitrix\Main\IO\Directory::createDirectory($path) — эффективное и удобное решение для создания каталогов в современном ядре 1С-Битрикс (D7). Он избавляет от необходимости писать «обвязку» для функции mkdir(), автоматически создает вложенные каталоги, а также возвращает объект Directory для дальнейшей работы.

Если вы еще используете старую функцию CheckDirPath(), настоятельно рекомендуем перейти на createDirectory, чтобы привести код к современным стандартам 1С-Битрикс и обеспечить лучшую читаемость и поддержку вашего проекта.