Свои типы полей ORM

Тип поля в ORM — это код, отвечающий за преобразование значения между PHP и БД. Создавая собственный класс поля, вы инкапсулируете сериализацию, валидацию и приведение типов там, где им и место — в модели, а не в бизнес-логике.

Зачем свои типы полей

Штатных типов D7 (IntegerField, StringField, DatetimeField и др.) хватает для простых схем. Собственный тип нужен, когда значение имеет структуру или требует особой обработки:

• хранение массива или JSON в одной текстовой колонке;
• прозрачное шифрование/дешифрование значения при записи и чтении;
• нормализация телефона, приведение денежной суммы к копейкам;
• единая валидация формата для всех сущностей проекта.

Смысл в том, чтобы прикладной код работал с удобным PHP-значением (массивом, объектом), а поле само занималось преобразованием к строке для БД и обратно.

Иерархия классов полей

Все скалярные типы наследуются от Bitrix\Main\ORM\Fields\ScalarField, который, в свою очередь, происходит от базового Field. Ключевые уровни:

Свой скалярный тип проще всего унаследовать от готового близкого класса (например, TextField для строкового хранилища) и переопределить преобразование значения.

Save и Fetch модификаторы

Самый быстрый способ добавить сериализацию без нового класса — навесить на существующее поле модификаторы. Метод addSaveDataModifier() преобразует значение перед записью, addFetchDataModifier() — после чтения:

(new TextField('SETTINGS'))
  ->addSaveDataModifier(fn($v) => json_encode($v, JSON_UNESCAPED_UNICODE))
  ->addFetchDataModifier(fn($v) => json_decode($v, true));

После этого прикладной код читает и пишет обычный массив, а в БД лежит JSON-строка. Так реализована и штатная сериализация в некоторых полях ядра.

Собственный класс поля

Когда логику нужно переиспользовать в десятках сущностей, вынесите её в отдельный класс. Наследуйтесь от подходящего поля и переопределите преобразование:

namespace Vendor\Orm\Fields;

use Bitrix\Main\ORM\Fields\TextField;

class JsonField extends TextField
{
  public function __construct($name, array $parameters = [])
  {
    parent::__construct($name, $parameters);
    $this->addSaveDataModifier([$this, 'encode']);
    $this->addFetchDataModifier([$this, 'decode']);
  }
  public function encode($v) { return $v === null ? null : json_encode($v, JSON_UNESCAPED_UNICODE); }
  public function decode($v) { return $v === null ? null : json_decode($v, true); }
}

В getMap() теперь достаточно написать new JsonField('SETTINGS'). Логика централизована, а сущности остаются чистыми.

Готовый ArrayField и его аналоги

Прежде чем писать свой класс, проверьте штатные решения. В ядре есть Bitrix\Main\ORM\Fields\ArrayField — он сериализует массив в строку и обратно, по умолчанию через PHP-сериализацию, но допускает и свой сериализатор:

use Bitrix\Main\ORM\Fields\ArrayField;

(new ArrayField('DATA'))
  ->configureSerializationJson(); // хранить как JSON

• configureSerializationPhp() — формат serialize() (по умолчанию);
• configureSerializationJson() — читаемый JSON;
• можно передать пару собственных колбэков сериализации/десериализации.

Валидаторы значения

Собственный тип поля — удобное место для валидации. Добавьте валидатор через addValidator(), и он сработает при add()/update(), вернув ошибку в объекте Result:

use Bitrix\Main\ORM\Fields\Validators\LengthValidator;

(new StringField('CODE'))
  ->addValidator(new LengthValidator(2, 32))
  ->addValidator(function ($value, $primary, $row, $field) {
    return preg_match('/^[A-Z0-9_]+$/', $value) ? true : 'Только латиница и цифры';
  });

Валидатор возвращает true при успехе или строку/объект ошибки. Встраивая проверки в класс поля, вы гарантируете единые правила во всех сущностях, где это поле используется.

Итог

Свои типы полей ORM держат сериализацию, приведение и валидацию внутри модели. Начните с малого: addSaveDataModifier/addFetchDataModifier или готовый ArrayField. Когда логика повторяется — выносите её в наследника ScalarField. Помните про ограничение: по сериализованным колонкам не построить SQL-фильтр.

Мы в B2Bsite проектируем модель данных под нестандартные сценарии хранения — от структурированных настроек до данных обмена с внешними системами. Если вашему проекту нужна аккуратная ORM-схема с кастомными типами и валидацией, поможем спроектировать и внедрить её без потери производительности.