Описание класса для работы с таблицей валют CurrencyTable в 1С-Битрикс

Класс CurrencyTable предназначен для работы с таблицей, содержащей данные о валютах в системе «1С-Битрикс». Он управляет операциями чтения, записи, обновления и удаления записей в соответствующей таблице базы данных.

Описание класса CurrencyTable в 1С-Битрикс

До версии 18.0.2 модуля main класс CurrencyTable наследовался от Bitrix\Main\Entity\DataManager. Начиная с версии 18.0.2 и выше, он наследуется от Bitrix\Main\ORM\Data\DataManager. При этом изменения в основном коснулись namespaces и внутренней логики ORM, но общий принцип работы остался таким же.

1. Основные задачи класса

Создание, чтение, обновление и удаление (CRUD) записей о валютах.
Валидация данных при добавлении и изменении записей.
Управление схемой данных (описание структуры полей, типов данных, индексов и пр.), унаследованное от DataManager.
Получение списка (getList) и выборка по идентификатору (getById) данных о валютах.

2. Основные поля таблицы

Наиболее часто встречающиеся поля:

CURRENCY: Код валюты (например, USD, EUR, RUB).
AMOUNT: Коэффициент пересчёта (курс) валюты к базовой валюте.
AMOUNT_CNT: Количество единиц валюты (например, 10 единиц = 1 основная валюта).
SORT: Порядок сортировки записи.
BASE: Признак базовой валюты (Y/N).
DATE_UPDATE: Дата и время последнего обновления записи.
DATE_CREATE: Дата и время создания записи.
Другие поля, используемые при расширении функционала.

3. Методы класса

3.1. `getTableName()`

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


public static function getTableName()
{
    return 'b_catalog_currency'; // Примерное название
}

3.2. `getMap()`

Возвращает карту (map) полей таблицы. На основе этой карты ORM понимает, какие поля есть в таблице, их типы данных, настройки валидации и связи.


public static function getMap()
{
    return [
        new Main\Entity\StringField('CURRENCY', [
            'primary' => true,
            'required' => true,
            'validation' => [__CLASS__, 'validateCurrencyCode'],
            'title' => 'Код валюты',
        ]),
        new Main\Entity\FloatField('AMOUNT', [
            'required' => true,
            'default_value' => 1.0,
            'title' => 'Курс к базовой валюте',
        ]),
        // ... другие поля ...
    ];
}

3.3. Методы CRUD (наследуются от `DataManager`)

Класс CurrencyTable, как и все классы-наследники DataManager, имеет стандартный набор методов для работы с записями:

add(array $data) — Добавление новой записи.
update(mixed $primary, array $data) — Обновление существующей записи.
delete(mixed $primary) — Удаление записи.
getList(array $parameters = []) — Получение списка записей.
getById(mixed $id) — Упрощённая выборка записи по первичному ключу.

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

Пример 1. Получение списка валют


use Bitrix\Main\Loader;
use Bitrix\Currency\CurrencyTable;

Loader::includeModule('currency');

// Получаем список всех валют
$result = CurrencyTable::getList([
    'select' => ['CURRENCY', 'AMOUNT', 'AMOUNT_CNT', 'SORT', 'BASE'],
    'order'  => ['SORT' => 'ASC']
]);

while ($currency = $result->fetch()) {
    echo 'Валюта: ' . $currency['CURRENCY'] 
       . ', Курс: ' . $currency['AMOUNT'] 
       . ', Количество: ' . $currency['AMOUNT_CNT'] 
       . '<br>';
}

Пример 2. Получение валюты по коду (getById)


use Bitrix\Main\Loader;
use Bitrix\Currency\CurrencyTable;

Loader::includeModule('currency');

$currencyCode = 'USD';

$currencyData = CurrencyTable::getById($currencyCode)->fetch();
if ($currencyData) {
    echo 'Найдена валюта: ' . $currencyData['CURRENCY'] 
         . ' (курс: ' . $currencyData['AMOUNT'] . ')';
} else {
    echo 'Валюта не найдена';
}

Пример 3. Добавление новой валюты


use Bitrix\Main\Loader;
use Bitrix\Currency\CurrencyTable;
use Bitrix\Main\Type\DateTime;

Loader::includeModule('currency');

$result = CurrencyTable::add([
    'CURRENCY'   => 'ABC',
    'AMOUNT'     => 75.50,
    'AMOUNT_CNT' => 1,
    'SORT'       => 100,
    'BASE'       => 'N',
    'DATE_UPDATE'=> new DateTime(),
    'DATE_CREATE'=> new DateTime(),
]);

if ($result->isSuccess()) {
    echo 'Валюта успешно добавлена!';
} else {
    $errors = $result->getErrorMessages();
    echo 'Ошибка при добавлении валюты: ' . implode(', ', $errors);
}

Пример 4. Обновление записи


use Bitrix\Main\Loader;
use Bitrix\Currency\CurrencyTable;

Loader::includeModule('currency');

$currencyCode = 'USD';
$updateResult = CurrencyTable::update($currencyCode, [
    'AMOUNT' => 76.00,
]);

if ($updateResult->isSuccess()) {
    echo 'Курс валюты обновлён!';
} else {
    $errors = $updateResult->getErrorMessages();
    echo 'Ошибка обновления: ' . implode(', ', $errors);
}

Пример 5. Удаление записи


use Bitrix\Main\Loader;
use Bitrix\Currency\CurrencyTable;

Loader::includeModule('currency');

$currencyCode = 'ABC';
$deleteResult = CurrencyTable::delete($currencyCode);

if ($deleteResult->isSuccess()) {
    echo 'Валюта удалена';
} else {
    $errors = $deleteResult->getErrorMessages();
    echo 'Ошибка удаления: ' . implode(', ', $errors);
}

5. Особенности и рекомендации

Перед использованием класса CurrencyTable необходимо подключить модуль currency через Loader::includeModule('currency').
В более ранних версиях (до 18.0.2 модуля main) используйте неймспейс Bitrix\Main\Entity.
При добавлении или обновлении записей проверяйте результат ($result->isSuccess()), чтобы корректно обрабатывать возможные ошибки.
Используйте события (OnBeforeAdd, OnAfterUpdate и т. д.) и валидацию полей для расширения функционала.
Следите за корректностью использования базовой валюты (BASE = Y).

Итог

Класс CurrencyTable — удобный инструмент для управления таблицей валют в 1С-Битрикс. Он предоставляет стандартные ORM-возможности, позволяя быстро осуществлять CRUD-операции и расширять функционал по необходимости. При правильной настройке и обработке ошибок вы сможете эффективно управлять данными о валютах и обеспечивать стабильную работу проекта.

Теги: D7, справочник