Работа с медиабиблиотекой в 1С-Битрикс: получение данных, добавление и удаление элементов, создание и удаление коллекций

Медиабиблиотека в 1С-Битрикс – это отдельный функционал модуля fileman, позволяющий хранить и управлять различными медиафайлами (изображениями, видео, документами и т.д.). В отличие от простого хранения файлов через \Bitrix\Main\FileTable, медиабиблиотека даёт возможность создавать коллекции (по сути, тематические папки/альбомы), назначать имена, описания и группировать файлы. Ниже рассмотрим, как с ней работать: получим информацию о существующих коллекциях и их содержимом, а также научимся создавать новые коллекции, добавлять в них элементы и удалять ненужные.

Важно: все примеры кода предполагают, что скрипт запускается в среде 1С-Битрикс с корректной инициализацией пролога, а также с подключённым модулем fileman. Если вы работаете вне компонентов, то не забудьте добавить:

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");
CModule::IncludeModule("fileman");
require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/fileman/classes/general/medialib.php");
CMedialib::Init();

1. Получение списка коллекций и их содержимого

Самый простой способ получить все коллекции из медиабиблиотеки и вывести их состав – использовать классы CMedialibCollection и CMedialibItem.

Пример кода

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

if (CModule::IncludeModule("fileman")) {
    require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/fileman/classes/general/medialib.php");
    CMedialib::Init();

    // Получаем все коллекции медиабиблиотеки
    $collections = CMedialibCollection::GetList(array(
        'arFilter' => array(),              // Фильтр, например, можно указать 'ACTIVE' => 'Y'
        'arOrder'  => array('NAME' => 'ASC')// Сортировка по названию
    ));

    if (!empty($collections)) {
        foreach ($collections as $collection) {
            echo "<h3>Коллекция: {$collection['NAME']} (ID: {$collection['ID']})</h3>";

            // Получаем элементы (файлы) внутри коллекции
            $mediaItems = CMedialibItem::GetList(array(
                "types" => array("all"),
                "arFilter" => array("collection" => $collection['ID'])
            ));

            if (!empty($mediaItems)) {
                foreach ($mediaItems as $item) {
                    echo "<pre>";
                    print_r($item);
                    echo "</pre>";
                }
            } else {
                echo "Нет элементов в коллекции<br><br>";
            }
        }
    } else {
        echo "В медиабиблиотеке нет коллекций.";
    }
}

Здесь:

• CMedialibCollection::GetList – возвращает массив коллекций с учётом заданных фильтров и сортировки.
• CMedialibItem::GetList – возвращает элементы (файлы) для указанной коллекции.
• Поля внутри каждого $item могут содержать путь к файлу (PATH), информацию о названии (NAME), описании (DESCRIPTION) и прочие метаданные.

2. Создание новой коллекции

Для создания (или изменения) коллекции в медиабиблиотеке используется метод CMedialibCollection::Edit. Если в массиве параметров 'id' => 0, то будет создана новая коллекция.

Пример кода

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

if (CModule::IncludeModule("fileman")) {
    require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/fileman/classes/general/medialib.php");
    CMedialib::Init();

    // Параметры новой коллекции
    $newCollectionParams = array(
        'id' => 0, // 0 означает, что коллекция создаётся, а не редактируется
        'arFields' => array(
            'NAME'        => 'Новая коллекция',
            'DESCRIPTION' => 'Это описание новой коллекции',
            'ACTIVE'      => 'Y',       // Коллекция будет активна
            'ML_TYPE'     => 1,         // Тип: 1 - изображения, 2 - видео и т.д.
            // 'PARENT_ID' => <ID родительской коллекции>, если надо вложить одну коллекцию в другую
        )
    );

    $newCollectionId = CMedialibCollection::Edit($newCollectionParams);

    if ($newCollectionId > 0) {
        echo "Коллекция успешно создана, ID: {$newCollectionId}";
    } else {
        echo "Ошибка при создании коллекции.";
    }
}

Обратите внимание:

• Поле ML_TYPE отвечает за категорию (изображения, видео, аудио и т.д.), но его использование не строго обязательно, если у вас универсальный набор данных в медиабиблиотеке.
• Можно задавать PARENT_ID, чтобы вложить новую коллекцию внутрь уже существующей.

3. Удаление коллекции

Чтобы удалить коллекцию вместе со всеми элементами внутри неё, достаточно вызвать CMedialibCollection::Delete, передав в него ID коллекции:

$collectionId = 123; // ID коллекции, которую хотим удалить

CMedialibCollection::Delete($collectionId);

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

4. Добавление новых элементов (файлов) в медиабиблиотеку

Добавление нового файла в медиабиблиотеку происходит через класс CMedialibItem и метод Edit. При этом файл должен быть заранее загружен в папку на сервере (например, через стандартную загрузку CFile::SaveFile или другим способом), а затем мы просто указываем путь к файлу (или его SOURCE_ID) и к какой коллекции он относится.

Пример кода

require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

if (CModule::IncludeModule("fileman")) {
    require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/fileman/classes/general/medialib.php");
    CMedialib::Init();

    // Допустим, мы уже загрузили файл и знаем его ID в b_file (например, 789)
    $fileId = 789;
    // Путь к файлу в /upload/medialibrary/
    $filePath = "/upload/medialibrary/my_image.jpg";
    // ID коллекции, куда нужно добавить элемент
    $collectionId = 123;

    $arFields = array(
        'NAME'         => 'Моё изображение',
        'DESCRIPTION'  => 'Описание для изображения',
        // 'KEYWORDS'   => 'Ключевые слова', // при необходимости
        'SOURCE_ID'    => $fileId,    // ID файла в таблице b_file
        'PATH'         => $filePath,
        'FILE_NAME'    => 'my_image.jpg',
        // Если нужно прикрепить элемент сразу к нескольким коллекциям:
        'arCollections' => array($collectionId),
        // Если только к одной, достаточно указать 'COLLECTION_ID'
        // 'COLLECTION_ID' => $collectionId,
    );

    // Параметры добавления элемента
    $arParams = array(
        'arFields' => $arFields
    );

    $newItemId = CMedialibItem::Edit($arParams);

    if ($newItemId > 0) {
        echo "Новый элемент успешно добавлен в медиабиблиотеку, ID: {$newItemId}";
    } else {
        echo "Ошибка при добавлении элемента.";
    }
}

Здесь ключевые моменты:

• SOURCE_ID – это ID файла в таблице b_file. Он появляется, когда мы загружаем файл через стандартный функционал CFile::SaveFile.
• PATH – реальный путь к файлу (от корня сайта).
• COLLECTION_ID или arCollections – указываем, в какие коллекции поместить элемент.

5. Удаление элементов из медиабиблиотеки

Если нужно удалить конкретный элемент (файл) по его ID в медиабиблиотеке, воспользуйтесь методом CMedialibItem::Delete:

$itemId = 456; // ID элемента из медиабиблиотеки

CMedialibItem::Delete($itemId);

Обратите внимание, что это удалит сам объект медиабиблиотеки (то есть запись в fileman-структуре). Физический файл с сервера может удалиться только в том случае, если он не привязан к другим элементам и нигде не используется. Если вам нужно гарантированно удалить сам файл, придётся дополнительно вызвать CFile::Delete($fileId) (ID файла в таблице b_file), проверив, что он более нигде не задействован.

6. Коротко о разнице с \Bitrix\Main\FileTable

Иногда возникает путаница между классом \Bitrix\Main\FileTable и функционалом медиабиблиотеки:

• \Bitrix\Main\FileTable / CFile отвечает за физические файлы, которые лежат в папке /upload и зарегистрированы в таблице b_file.
• Медиабиблиотека (CMedialibCollection, CMedialibItem) – это надстройка над файлами для удобной организации, позволяющая создавать тематические коллекции, добавлять описание, ключевые слова, делать иерархии коллекций и т.д.

Если ваша задача – просто получить список всех файлов, загруженных на сайт, вы можете работать напрямую через CFile или FileTable. Но если нужно группировать их в коллекции и управлять ими, как в «галерее», стоит использовать медиабиблиотеку модуля fileman.

Заключение

Медиабиблиотека в 1С-Битрикс значительно упрощает организацию и хранение файлов, поскольку:

• Позволяет объединять файлы в коллекции и управлять ими пакетно.
• Дает возможность добавлять к элементам описания, теги и ключевые слова.
• Упрощает поиск и переиспользование медиафайлов в разных разделах сайта.

В этой статье мы рассмотрели основные операции:

1. Получение списка коллекций и их содержимого.
2. Создание новой коллекции при помощи метода CMedialibCollection::Edit.
3. Удаление коллекции (CMedialibCollection::Delete).
4. Добавление нового элемента (файла) в медиабиблиотеку через CMedialibItem::Edit.
5. Удаление элемента (CMedialibItem::Delete).

Использование этих методов позволит вам автоматизировать управление мультимедийным контентом сайта и упростит работу с файлами в различных модулях и компонентах. Обязательно следите за тем, чтобы при удалении не удалялись нужные материалы, используемые в других местах сайта.