ExpressionField — поле-выражение ORM
Пространство имен: Bitrix\Main\ORM\Fields
Модуль: main — подключать отдельно не нужно
Доступно с версии: 12.0.0
Когда использовать
Поле ExpressionField вычисляет значение SQL-выражением, например COUNT(*), LENGTH(%s) или %s * %s. Поле нужно для агрегатов, вычисляемых колонок и условий фильтра по выражению. Поле не хранится в таблице и доступно только для чтения.
Поле описывают в параметре runtime запроса getList или в методе getMap таблицы. Конструктор принимает имя поля, выражение и список полей, которые ORM подставляет в выражение вместо %s.
new ExpressionField('NAME_LEN', 'LENGTH(%s)', 'NAME');
new ExpressionField('CNT', 'COUNT(*)');
new ExpressionField('TOTAL', '%s * %s', ['PRICE', 'QUANTITY']);
Метод configureValueType задает тип значения. По умолчанию тип — StringField.
Если выражение содержит агрегатную функцию, ORM сама группирует выборку по остальным полям select, order и условий HAVING. Такую выборку нельзя прочитать объектами через fetchObject.
Запрос регистрирует копию поля из runtime. Вызовы configure* у исходного объекта после регистрации на запрос не влияют.
Старое имя класса Bitrix\Main\Entity\ExpressionField работает как псевдоним.
Подробнее — в статьях Выборка данных и Построитель запросов.
Методы класса
| Метод | Описание | С версии |
|---|---|---|
| configureValueType | Задает класс поля, которое описывает тип значения | |
| configureValueField | Задает объект поля, которое описывает тип значения | |
| getValueType | Возвращает класс поля типа значения | |
| getValueField | Возвращает объект поля типа значения | |
| getExpression | Возвращает выражение в исходном виде | |
| getBuildFrom | Возвращает поля, которые ORM подставляет в выражение | |
| getBuildFromChains | Возвращает цепочки полей выражения | |
| getFullExpression | Возвращает выражение с раскрытыми вложенными выражениями | |
| isAggregated | Проверяет, есть ли в выражении агрегатная функция | |
| hasSubquery | Проверяет, есть ли в выражении подзапрос | |
| isConstant | Проверяет, что выражение не зависит от полей | |
| checkAggregation | Находит агрегатные функции в строке выражения | |
| checkSubquery | Проверяет, есть ли подзапрос в строке выражения | |
| removeSubqueries | Удаляет из строки выражения подзапросы и строковые литералы | |
| cast | Приводит значение к типу поля | |
| convertValueFromDb | Преобразует значение из базы данных | |
| convertValueToDb | Преобразует значение для базы данных |
Наследование
Класс наследует Bitrix\Main\ORM\Fields\Field и реализует IReadable.
Реализация методов базового класса
| Метод | Особенность реализации |
|---|---|
__construct($name, $expression, $buildFrom = null, $parameters = []) |
Принимает выражение и поля для подстановки. buildFrom — строка, массив строк или функций, которые возвращают SqlExpression. Без параметра data_type задает тип значения StringField. Параметр parameters — старый формат настроек, для нового кода используйте методы configure* |
setEntity |
Создает поле типа значения по configureValueType или берет объект из configureValueField. При старом формате с параметром data_type создает поле через Entity::initializeField. Выбрасывает Bitrix\Main\SystemException, если тип значения — не скалярное поле |
getTypeMask |
Возвращает FieldTypeMask::EXPRESSION |
getDataType |
Устарел. Возвращает тип данных поля типа значения |
validateValue |
Выбрасывает Bitrix\Main\NotImplementedException, потому что значение поля-выражения нельзя записать |
__clone |
Сбрасывает запомненные цепочки и полное выражение у копии |
Вызов методов поля типа значения
Методы, которых нет в ExpressionField и Field, поле передает полю типа значения. Например, getColumnName вернет имя колонки поля типа значения. Методы Field, например getTitle, отвечают от самого выражения. До привязки к сущности такой вызов завершится ошибкой PHP.