Множественное поле сущности HL блока Битрикс

Стандартный генератор сущностей Битрикс не умеет в множественные поля.

Совсем недавно столкнулся со следующей ситуацией:

  • есть HL блок Document с множественным полем типа «Текст»
  • для этого HL блока создана сущность через стандартный генератор сущностей доступный в разделе Производительность -> Таблицы
  • на выходе получаем описание этого поля в виде Bitrix\Main\ORM\Fields\TextField

При попытке прочитать значение поля через сущность (DocumentTable) получаем вместо массива значений строку «Array». Создание и обновление значений также не проходит. Как же быть?

Примерно так выглядит описание нашего поля в сущности:

use Bitrix\Main\ORM\Fields\TextField;
use Bitrix\Main\ORM\Data\DataManager;

class DocumentTable extends DataManager
{
    // ...
    public static function getMap()
    {
        return [
            //...
            new TextField(
                'DOCUMENT_FILE_KEY',
                [
                    'column_name' => 'UF_DOCUMENT_FILE_KEY',
                    'title'       => Loc::getMessage('DOCUMENT_ENTITY_UF_DOCUMENT_FILE_KEY_FIELD'),
                ]
            ),
            //...
        ];
    }
    // ...
}

Само поле в Битрикс:

Как оказалось, для нормального взаимодействия с этим полем (чтение / создание / обновление) через массив значений на уровне работы с сущностью, достаточно немного изменить описание поля:

use Bitrix\Main\ORM\Fields\ArrayField;
use Bitrix\Main\ORM\Data\DataManager;

class DocumentTable extends DataManager
{
    // ...
    public static function getMap()
    {
        return [
            //...
            (new ArrayField(
                'DOCUMENT_FILE_KEY',
                [
                    'column_name' => 'UF_DOCUMENT_FILE_KEY',
                    'title'       => Loc::getMessage('DOCUMENT_ENTITY_UF_DOCUMENT_FILE_KEY_FIELD'),
                ]
            ))->configureSerializationPhp(),
            //...
        ];
    }
}

Теперь чтение значения множественного поля DOCUMENT_FILE_KEY через сущность DocumentTable возвращает значение поля как массив значений:

$documentObject = DocumentTable::query()
    ->setSelect([
        'ID',
        'DOCUMENT_FILE_KEY',
    ])
    ->setFilter([
        'ID' => 1,
    ])
    ->exec()
    ->fetchObject();

// выводит массив значений поля DOCUMENT_FILE_KEY 
print_r($documentObject->get('DOCUMENT_FILE_KEY'));

Создание и обновление также работает корректно (через массив значений):

// Добавляет запись в HL блок
DocumentTable::add(1, [
    'DOCUMENT_FILE_KEY' => [
    	'1',
    	'2'
    ],
]);

// Обновляет запись в HL блоке
DocumentTable::update(1, [
    'DOCUMENT_FILE_KEY' => [
    	'3',
    	'4'
    ],
]);

Очень жаль, что этот момент в документации к Битрикс как следует не подсвечен.