Как загрузить и сохранить файл в 1С-Битрикс: CFile::MakeFileArray, SaveFile и D7 FileTable

Форма отправлена, в коде стоит CFile::SaveFile, а на выходе ноль и ни одной строки в таблице b_file? Чаще всего виноваты не "битрикс", а пустой $_FILES после лимита post_max_size=8M или отсутствие MODULE_ID в массиве файла. Ниже – как на CMS "1С-Битрикс: Управление сайтом" принять файл из формы, пройти цепочку MakeFileArray → SaveFile, привязать ID к инфоблоку или UF и отладить типичные сбои.

Класс CFile – стандартный способ зарегистрировать файл в ядре CMS: массив как у $_FILES, затем SaveFile с MODULE_ID и подпапкой в /upload. Успех – только целочисленный ID больше нуля и открывающийся SRC. При замене картинки передавайте old_file и del, иначе в b_file останется мусор. Это не Bitrix24: портальный Disk и REST Base64 здесь не используются.

В поиске часто попадают гайды про диск Bitrix24 – это другой продукт. Здесь только CMS: PHP, b_file и /upload. Update картинки – в гайде по Update, свойство "Файл" – в материале про свойства товаров, UF file – в статье про UF.

Разберите, когда нужен CFile на CMS, а не ручная заливка в /upload

CFile регистрирует файл в b_file и на диске /upload. Без него файл не привяжется к инфоблоку, UF или модулю. FTP подходит для статики, не для форм.

Делайте: для кода в своём модуле всегда идите через CFile. Не делайте: не смешивайте примеры disk.folder.uploadfile из CRM-портала с CMS – у них другая схема хранения.

Проверьте upload_dir, права на /upload и лимиты PHP до отладки CFile

Перед SaveFile проверьте окружение – иначе отладка CFile займёт час, хотя виноват php.ini. На тестовом стенде типичная картина: файл 12 МБ, post_max_size=8M, $_FILES пустой, а разработчик копает SaveFile.

1. Узнайте upload_dir: COption::GetOptionString('main', 'upload_dir', 'upload') – обычно это каталог /upload в корне сайта.
2. Проверьте права на /upload и подпапку (например iblock/abc): веб-сервер должен писать файлы (часто 755 на папку, 644 на файлы).
3. Сверьте php.ini: post_max_size должен быть не меньше upload_max_filesize. Иначе при большом файле PHP "молча" обнулит и $_POST, и $_FILES.
4. Убедитесь, что форма с файлом имеет enctype="multipart/form-data" – без этого $_FILES пустой.
5. Задайте MODULE_ID – код модуля-владельца (iblock, main, vendor.module) – иначе SaveFile часто возвращает false.
6. Запустите bitrix_server_test.php из дистрибутива – тест загрузки покажет права и лимиты до вашего кода.

Делайте: при пустом $_FILES сначала смотрите CONTENT_LENGTH и post_max_size, а не CFile. Не делайте: не вызывайте SaveFile с сырым путём на диск без MakeFileArray – ядро ждёт структуру как у $_FILES (name, size, tmp_name, type).

Соберите массив файла через CFile::MakeFileArray

MakeFileArray строит массив для SaveFile. path – ID файла, путь на сервере или URL.

$arFile = $_FILES['DOCUMENT'];
$arFile = CFile::MakeFileArray('/var/www/site/import/price.pdf');
$arFile = CFile::MakeFileArray(12345);
$arFile = CFile::MakeFileArray('https://example.com/image.jpg');

Для пути на диске (не ID) с версии 12.5.7 передайте skipInternal = true. Без tmp_name добавьте content и name вручную. Делайте: вызовите CheckFile или CheckImageFile до SaveFile. Не делайте: не передавайте только имя без tmp_name – получите false на форуме разработчиков.

Сохраните файл через CFile::SaveFile и удалите старый при замене

SaveFile кладёт файл в подпапку upload и пишет строку в b_file. Успех – только ID больше нуля.

$arFile = $_FILES['PREVIEW_PICTURE'];
$arFile['MODULE_ID'] = 'iblock';

// Замена: старый ID 999, удалить после успеха
$arFile['old_file'] = 999;
$arFile['del'] = 'Y';

$fileId = CFile::SaveFile($arFile, 'iblock/custom');

if (intval($fileId) > 0) {
    // Привязка к элементу – см. гайд по Update
    CIBlockElement::Update($elementId, [
        'PREVIEW_PICTURE' => CFile::MakeFileArray($fileId),
    ]);
} else {
    // Диагностика: права, CheckFile, MODULE_ID, tmp_name
}

Свойство "Файл" – через PROPERTY_VALUES в гайде по Update. UF file – через $USER_FIELD_MANAGER в статье про UF. Удаление: CFile::Delete($oldId) или old_file + del в SaveFile.

Делайте: проверяйте intval($fileId) > 0 сразу после SaveFile. Не делайте: не оставляйте старый file ID в свойстве при ручной заливке нового файла без del – диск зарастёт дублями.

Отладите типичные сбои: SaveFile=0, пустой $_FILES, MIME

Таблица быстрой диагностики – что проверить, если цепочка оборвалась.

Делайте: логируйте CheckFile и размер $_FILES до SaveFile. Не делайте: не считайте успехом файл в /upload без ID в b_file.

Прочитайте метаданные через GetFileArray и D7 FileTable

После сохранения путь – CFile::GetPath($id) или SRC из GetFileArray. Для пакетной выборки по списку ID удобнее D7, чем GetFileArray в цикле:

use Bitrix\Main\FileTable;

$rows = FileTable::getList([
    'filter' => ['@ID' => [101, 102, 103]],
    'select' => ['ID', 'ORIGINAL_NAME', 'SUBDIR', 'FILE_NAME'],
])->fetchAll();

// Ресайз картинки – по-прежнему CFile
$thumb = CFile::ResizeImageGet($fileId, ['width' => 200, 'height' => 200]);

FileTable читает b_file; новые файлы регистрируйте через SaveFile, не FileTable::add. Ресайз картинок – CFile::ResizeImageGet. В цикле по сотням элементов соберите ID и один getList вместо GetFileArray на каждой итерации – так вы избежите лишней нагрузки на диск.

Получите рабочий результат: чек-лист после загрузки

Перед выкладкой на прод пройдите список – так вы фиксируете, что цепочка $_FILES → MakeFileArray → SaveFile → привязка сработала.

1. SaveFile вернул ID больше нуля.
2. Строка в b_file с MODULE_ID и SUBDIR на месте.
3. GetPath($id) открывается в браузере без 404.
4. Старый file ID удалён при замене (del + old_file).
5. Свойство инфоблока или UF показывает файл в форме редактирования.

Все пункты выполнены – загрузка работает. Обработчик можно вынести в свой модуль с тем же MODULE_ID.

Нужна помощь с формой загрузки в каталоге или кастомным свойством "Файл" – обсудим задачу и разберём стенд. Похожие кейсы по инфоблокам – в портфолио.

Автор: Максим Мольков, разработчик 1С-Битрикс.
Источники: справочник CFile, CFile::SaveFile, урок "Загрузка файлов", документация PHP по загрузке файлов.

Частые вопросы