Руководство по работе с классом ExtraTable для наценок в Битрикс D7

В современных интернет-магазинах нередко возникает необходимость управлять наценками на товары. Для этого в 1С-Битрикс реализован специальный класс \Bitrix\Catalog\ExtraTable, позволяющий хранить информацию о наценках в собственной таблице и работать с ними, опираясь на принципы D7 (ORM). Давайте рассмотрим, как устроен этот класс, какие методы он предоставляет и как ими пользоваться на практике.

1. Назначение класса ExtraTable

Класс \Bitrix\Catalog\ExtraTable служит для управления таблицей наценок (например, добавления, чтения и удаления записей). Он основан на механизме ORM, который пришёл в 1С-Битрикс начиная с версии 14 (и позже усовершенствован). С точки зрения архитектуры класс позволяет:

• Определять структуру таблицы наценок (список полей, их тип, валидаторы).
• Стандартными методами add(), update(), delete(), getList() управлять записями в таблице, как с любой другой сущностью D7.
• Расширять функциональность при необходимости, используя механизм наследования D7.

2. Цепочка наследования

До версии 18.0.2 модуля main (ядра Битрикс), класс \Bitrix\Catalog\ExtraTable наследовал Bitrix\Main\Entity\DataManager. Начиная с версии 18.0.2, наследование идёт от Bitrix\Main\ORM\Data\DataManager. В любом случае, подход к работе с классом и методами остаётся очень схожим:

namespace Bitrix\Catalog;

use Bitrix\Main\ORM\Data\DataManager;

class ExtraTable extends DataManager
{
    // ...
}

Это означает, что мы имеем доступ ко всем возможностям D7 — маппингу полей, валидации, возможности делать выборки, фильтрацию, сортировку и т.д.

3. Структура таблицы наценок

Таблица для наценок имеет стандартное название (которое возвращается методом getTableName()), где хранятся следующие поля:

3.1. Поле ID

• Хранит уникальный идентификатор записи.
• Является основным ключом таблицы (primary key).

3.2. Поле NAME

• Название наценки, строка длиной до 50 символов.
• Для этого поля может применяться валидация (см. validateName()).

3.3. Поле PERCENTAGE

• Числовое поле для хранения величины наценки.
• Тип Decimal(18,2) означает, что можно задавать целую и дробную часть (два знака после запятой).

4. Основные методы класса ExtraTable

Класс \Bitrix\Catalog\ExtraTable (наследуется от DataManager) обязательно реализует несколько методов, характерных для всех ORM-сущностей в Битрикс D7.

4.1. getTableName()

Возвращает название таблицы в базе данных, с которой будет работать класс:

public static function getTableName()
{
    return 'b_catalog_extra';
}

Чаще всего вам не придётся вызывать этот метод вручную, так как он используется внутри ORM, но в некоторых случаях бывает полезно знать точное имя таблицы, чтобы, например, выполнять низкоуровневые операции.

4.2. getMap()

Метод возвращает описание полей (их тип и дополнительные параметры). Примерная реализация может выглядеть так (упрощённая схема):

public static function getMap()
{
    return [
        new \Bitrix\Main\Entity\IntegerField('ID', [
            'primary'      => true,
            'autocomplete' => true,
            'title'        => 'ID наценки',
        ]),
        new \Bitrix\Main\Entity\StringField('NAME', [
            'required' => true,
            'validation' => [__CLASS__, 'validateName'],
            'title' => 'Название наценки',
        ]),
        new \Bitrix\Main\Entity\FloatField('PERCENTAGE', [
            'required' => true,
            'title' => 'Величина наценки',
        ]),
    ];
}

Обратите внимание, что в реальном коде для поля PERCENTAGE может быть использован другой тип (например, \Bitrix\Main\ORM\Fields\FloatField или \Bitrix\Main\ORM\Fields\DecimalField) — это зависит от того, как разработчики модуля реализовали хранение данных в таблице.

4.3. validateName()

Позволяет определить набор правил, по которым будет проходить проверка значения в поле NAME. Пример:

public static function validateName()
{
    return [
        new \Bitrix\Main\Entity\Validator\Length(null, 50),
    ];
}

Здесь мы указываем, что название наценки не должно превышать 50 символов. Можно также добавить дополнительные валидаторы, если необходимо.

5. Примеры использования

Ниже приведён набор часто встречающихся операций с наценками: добавление, чтение (получение списка), а также удаление.

5.1. Подключение модуля и добавление новой наценки

Чтобы работать с классом, необходимо подключить модуль catalog (где физически располагается класс ExtraTable):

\Bitrix\Main\Loader::includeModule('catalog');

$result = \Bitrix\Catalog\ExtraTable::add([
    'NAME'       => 'Моя новая наценка',
    'PERCENTAGE' => 20
]);

if (!$result->isSuccess())
{
    // Вывод сообщений об ошибках
    print_r($result->getErrorMessages());
}
else
{
    echo "Новая наценка успешно добавлена. ID = " . $result->getId();
}

Здесь:

• Метод add() возвращает объект типа AddResult.
• Если при добавлении произошла ошибка валидации или другие неполадки, можно получить их список через метод getErrorMessages().

5.2. Получение списка всех наценок

Чтобы получить все записи, можно воспользоваться методом getList(), который вернёт список записей в виде массива:

$data = \Bitrix\Catalog\ExtraTable::getList()->fetchAll();
echo '
' . print_r($data, 1) . '
';

• Метод fetchAll() возвращает все записи выборки в виде обычного массива.
• Также можно использовать возможности getList() для фильтрации, сортировки и т.д.:

$data = \Bitrix\Catalog\ExtraTable::getList([
    'select' => ['ID', 'NAME', 'PERCENTAGE'],
    'filter' => ['>PERCENTAGE' => 10], // только наценки > 10
    'order'  => ['ID' => 'DESC']       // сортируем по убыванию ID
])->fetchAll();

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

Для удаления используем метод delete(ID), передавая ему идентификатор записи:

$ids = array_column(\Bitrix\Catalog\ExtraTable::getList()->fetchAll(), 'ID');
foreach ($ids as $value)
{
    \Bitrix\Catalog\ExtraTable::delete($value);
}

В данном примере мы сначала получаем все идентификаторы наценок, а потом подряд удаляем каждую запись. Конечно, в реальном проекте вы можете удалять только те записи, которые больше не нужны.

6. Рекомендации и частые ошибки

1. Не забывайте подключать модуль: прежде чем работать с классом ExtraTable, нужно подключить модуль catalog:

\Bitrix\Main\Loader::includeModule('catalog');

2. Следите за типами полей: PERCENTAGE — это Decimal(18,2), значит, при добавлении или обновлении значения нужно соблюдать формат. Хотя PHP обычно сам преобразует типы, всё же лучше пользоваться правильными данными (например, строкой вида '20.00' или числом с плавающей точкой).
3. Ограничения по длине NAME: если название наценки будет слишком длинным, метод validateName() вернёт ошибку, и вставка/обновление запишет её в лог.
4. Внимание к версиям: если вы используете версию до 18.0.2 модуля main, класс будет наследовать Bitrix\Main\Entity\DataManager. Начиная с 18.0.2 — Bitrix\Main\ORM\Data\DataManager. С точки зрения реализации для разработчика принципиальной разницы нет — основной функционал схож.

7. Заключение

Работа с наценками в 1С-Битрикс через класс \Bitrix\Catalog\ExtraTable максимально удобна благодаря механизму D7 (ORM). Вы можете использовать стандартные методы add(), update(), delete() и getList(), а также расширять функциональность благодаря цепочке наследования. Соблюдая описанные принципы, вы легко сможете управлять списком наценок, контролировать их значения и валидацию.

Надеемся, данное руководство поможет вам быстрее и эффективнее осваивать разработку в рамках 1С-Битрикс, создавая надёжные и гибкие решения для интернет-магазинов и корпоративных порталов. Если возникнут дополнительные вопросы — смело обращайтесь к официальной документации и форумам, где сообщество регулярно обсуждает тонкости разработки на платформе Битрикс. Удачи в работе!