Работа со значениями свойств заказа в 1С-Битрикс

В этой статье разберем ключевые операции с свойствами, особенности работы в новых версиях и приведем практические примеры.

Введение

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

Важное предупреждение

Всегда сохраняйте изменения через \Bitrix\Sale\Order::save(). Прямой вызов save() для коллекции или отдельного свойства (PropertyValueCollection или PropertyValue) в будущих версиях будет вызывать ошибку уровня E_WARNING.

Получение свойств заказа

1. Работа с объектами

$order = \Bitrix\Sale\Order::load($orderId);
$collection = $order->getPropertyCollection();

foreach ($collection as $propertyObj) {
    $code = $propertyObj->getField('CODE');
    $value = $propertyObj->getValue();

    echo "Свойство $code: $value
";
}
    

2. Использование ORM-методов

$dbRes = \Bitrix\Sale\PropertyValue::getList([
    'select' => ['ID', 'ORDER_ID', 'VALUE', 'CODE'],
    'filter' => ['=ORDER_ID' => 123],
    'order' => ['ID' => 'ASC']
]);

while ($item = $dbRes->fetch()) {
    echo "ID: {$item['ID']}, Значение: {$item['VALUE']}
";
}
    

Обновление значений

try {
    $order = \Bitrix\Sale\Order::load(123);
    $collection = $order->getPropertyCollection();

    // Поиск по коду свойства
    $phoneProp = $collection->getItemByOrderPropertyCode('PHONE');

    if ($phoneProp) {
        $result = $phoneProp->setValue('+7 999 123-45-67');

        if (!$result->isSuccess()) {
            throw new Exception(implode(', ', $result->getErrorMessages()));
        }

        $order->save();
        echo "Телефон успешно обновлен!";
    }
} catch (Exception $e) {
    echo "Ошибка: " . $e->getMessage();
}
    

Удаление свойства

$order = \Bitrix\Sale\Order::load(456);
$collection = $order->getPropertyCollection();

// Удаление по ID значения свойства
if ($item = $collection->getItemById(789)) {
    $item->delete();
    $order->save();
    echo "Свойство удалено!";
}
    

Добавление нового свойства

Вариант 1: createItem()

$order = \Bitrix\Sale\Order::load(321);
$collection = $order->getPropertyCollection();

$newProp = $collection->createItem([
    'NAME' => 'Комментарий клиента',
    'TYPE' => 'TEXTAREA',
    'CODE' => 'CLIENT_COMMENT',
    'SORT' => 500
]);

$newProp->setValue('Нужна срочная доставка');
$order->save();
    

Вариант 2: create() + addItem()

$newProp = \Bitrix\Sale\PropertyValue::create(
    $collection,
    [
        'NAME' => 'Скидочный купон',
        'CODE' => 'DISCOUNT_COUPON',
        'TYPE' => 'STRING'
    ]
);

$newProp->setValue('SUMMER2024');
$collection->addItem($newProp);
$order->save();
    

Работа со специальными свойствами

// Получение email
$email = $collection->getUserEmail()->getValue();

// Обновление адреса доставки
$address = $collection->getDeliveryLocation();
$address->setValue('Москва, ул. Тверская, 15');

// Проверка почтового индекса
$zip = $collection->getDeliveryLocationZip()->getValue();
if (!preg_match('/^\d{6}$/', $zip)) {
    throw new Exception('Неверный формат индекса');
}
    

Получение метаданных свойства

$propertyObj = $collection->getItemByOrderPropertyCode('PHONE');
$propertyInfo = $propertyObj->getProperty();

echo "Название: {$propertyInfo['NAME']}
";
echo "Тип: {$propertyInfo['TYPE']}
";
echo "Обязательное: " . ($propertyInfo['REQUIRED'] ? 'Да' : 'Нет');

// Через объект свойства
$propertyEntity = $propertyObj->getPropertyObject();
echo "Макс. длина: " . $propertyEntity->getField('MAXLENGTH');
    

Типичные ошибки и решения

Ошибка:

Warning: PropertyValue::save() is deprecated

Решение:

Всегда сохраняйте через объект заказа:

// Неправильно:
$property->save();

// Правильно:
$order->save();
    

Ошибка при обновлении:

$result = $prop->setValue('data');
if (!$result->isSuccess()) {
    // Обработка ошибок
    $errors = $result->getErrorMessages();
}
    

Лучшие практики

1. Используйте коды свойств вместо ID для большей гибкости
2. Проверяйте существование свойства перед операциями:

if (!$collection->getItemByOrderPropertyCode('MY_CODE')) {
    throw new Exception('Свойство не найдено');
}
    

3. Для массового обновления:

$propsToUpdate = [
    'PHONE' => '+7 495 123-45-67',
    'EMAIL' => 'client@domain.ru'
];

foreach ($propsToUpdate as $code => $value) {
    if ($prop = $collection->getItemByOrderPropertyCode($code)) {
        $prop->setValue($value);
    }
}

$order->save();
    

Заключение

Правильная работа со свойствами заказа позволяет:

• Хранить дополнительную информацию о клиентах
• Интегрироваться с внешними системами
• Реализовывать сложную бизнес-логику

Все примеры проверены на версии Битрикс 22.0.300. Используйте официальную документацию для получения актуальной информации о новых методах.

Теория

Основные понятия

Свойства заказа — это дополнительные поля, которые могут быть привязаны к заказу. Они позволяют хранить и обрабатывать дополнительную информацию, такую как контактные данные клиента, комментарии, информацию о доставке и многое другое.

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

Работа с коллекциями свойств

Коллекция свойств — это объект, который содержит все свойства заказа. Он позволяет получать, обновлять и удалять свойства. Коллекция свойств предоставляет методы для работы с отдельными свойствами, такими как getItemByOrderPropertyCode, getItemById, createItem и другие.

ORM-методы

ORM (Object-Relational Mapping) — это технология, которая позволяет работать с базами данных, используя объекты и методы. В 1С-Битрикс ORM-методы предоставляют удобный способ работы с данными, включая свойства заказа. Методы getList, fetch и другие позволяют получать и обрабатывать данные из базы.

Обработка ошибок

Обработка ошибок — важная часть работы со свойствами заказа. При обновлении или добавлении свойств могут возникать ошибки, которые необходимо обрабатывать. Методы isSuccess и getErrorMessages позволяют проверять успешность операции и получать сообщения об ошибках.

Лучшие практики

Использование кодов свойств — вместо ID для большей гибкости. Коды свойств позволяют избежать проблем при изменении ID свойств.

Проверка существования свойства — перед операциями. Это позволяет избежать ошибок при работе с несуществующими свойствами.

Массовое обновление — для обновления нескольких свойств за один раз. Это позволяет сократить количество запросов к базе данных и ускорить работу.

Заключение

Правильная работа со свойствами заказа в 1С-Битрикс позволяет хранить и обрабатывать дополнительную информацию о клиентах, интегрироваться с внешними системами и реализовывать сложную бизнес-логику. Используйте официальную документацию для получения актуальной информации о новых методах и возможностях.