waOrder

Этот класс используется для передачи информации о произвольном заказе в плагины оплаты и доставки.

Родительский класс — ArrayAccess, поэтому свойства экземпляра класса можно заполнять напрямую — без использования методов:

$order = new waOrder([
    'contact' => new waContact(123),
    'items' => [
        [
            'id' => $item['id'],
            'name' => $item['name'],
            'price' => $item['price'],
            'quantity' => 10,
        ],
    ],
]);

// установка валюты заказа
$order->currency = 'RUB';

Свойства заказа

В экземпляре класса могут использоваться следующие свойства заказа:

• id: числовой ID заказа,
• id_str: отформатированный (строковый) ID заказа,
• contact_id: ID контакта клиента,
• currency: ISO-код валюты,
• total: сумма заказа,
• tax: размер применённого налога,
• discount: общий размер скидки,
• subtotal: подытог: стоимость позиций заказа без стоимости доставки,
• shipping: стоимость доставки,
• shipping_name: название варианта доставки,
• payment_name: название способа оплаты,
• tax_included: признак налога, включённого в стоимость позиций заказа,
• recurrent: признак повторяющегося заказа,
• save_card: признак заказа, для оплаты которого сохранена информация о платёжной карте клиента,
• description: локализованное описание на текущем языке,
• description_en: универсальное описание на английском языке,
• datetime: дата и время оформления заказа,
• update_datetime: дата и время последнего обновления заказа,
• paid_datetime: дата и время оплаты заказа,
• shipping_params: параметры варианта доставки,
• shipping_data: свойства заказа, связанные с доставкой,
• shipping_rate_id: ID варианта доставки,
• shipping_plugin: идентификатор плагина доставки,
• shipping_tax_rate: размер налога на доставку,
• shipping_tax_included: признак налога, включённого в стоимость доставки,
• shipping_address: адрес доставки в виде массива со следующими ключами:
• shipping_address['firstname']: имя плательщика, если адрес плательщика совпадает с адресом доставки,
• shipping_address['lastname']: фамилия плательщика, если адрес плательщика совпадает с адресом доставки,
• shipping_address['name']: полное имя плательщика, если адрес плательщика совпадает с адресом доставки,
• shipping_address['zip']: почтовый индекс,
• shipping_address['street']: название улицы, номер дома и квартиры,
• shipping_address['city']: название населённого пункта,
• shipping_address['region']: код региона,
• shipping_address['region_name']: название региона,
• shipping_address['country']: ISO-код страны,
• shipping_address['country_name']: название страны,
• shipping_address['address']: весь адрес в виде строки,
• billing_params: параметры способа оплаты,
• billing_data: свойства заказа, связанные с оплатой,
• billing_address: адрес плательщика — с теми же ключами, что и для свойства 'shipping_address' (адрес доставки),
• items: список позиций заказа (см. описание структуры в описании конструктора класса),
• total_quantity: общее количество позиций заказа,
• contact_email (только для чтения): основной email-адрес клиента,
• contact_name (только для чтения): полное имя клиента,
• comment: комментарий к заказу,
• params: массив дополнительных параметров заказа,
• card_native_id: идентификатор сохранённой платёжной карты клиента для оплаты повторяющихся заказов.

Методы

• __construct

  Конструктор.

• getContact

  Возвращает объект с данными клиента.

• getContactField

  Возвращает значение из данных клиента.

• hasFractionalQuantity

  Возвращает информацию наличии в заказе позиций с дробным количеством.

• repackFractionalQuantity

  Конвертирует дробные количества позиций заказа в целочисленные.

• hasStockUnits

  Возвращает информацию наличии в заказе позиций с нестандартными единицами измерения количества.

• getTotalDiscount

  Возвращает общий размер скидки.

• getTotalQuantity

  Возвращает общее количество всех позиций заказа.

public function __construct ($data = [])

Конструктор — создаёт экземпляр класса для работы с конкретным заказом.

Параметры

• $data

  Массив параметров заказа со следующими необязательными ключами:

  • contact: Экземпляр класса waContact с данными клиента.
  • params: Массив параметров с заказа с необязательными ключами следующих видов:
    • [type]_[group]_[name]: В качестве [type] могут использоваться обозначения типов shipping (доставка) и payment или billing (оплата). В качестве [group] могут использоваться обозначения групп params (параметры доставки или оплаты), data (параметры заказа для использования плагинами доставки либо оплаты). В качестве [name] могут использоваться произвольные ключи параметров.
    • shipping_[name]: В качестве [name] могут использоваться имена параметров rate_id (идентификатор тарифа доставки), plugin (идентификатор плагина доставки), name (название способа доставки).
  • items: Список позиций заказа. Каждый элемент списка — массив со следующими ключами:
    • id: идентификатор,
    • name: название,
    • price: цена,
    • description (необязательно): описание,
    • img (необязательно): URL изображения,
    • height (необязательно): высота,
    • width (необязательно): ширина,
    • length (необязательно): длина,
    • weight (необязательно): вес,
    • quantity (необязательно): количество (по умолчанию 1),
    • discount (необязательно): размер скидки для одной единицы позиции; используется для расчёта скидки, если не указано значение total_discount,
    • total_discount (необязательно): размер скидки, уже рассчитанный для указанного количества позиции,
    • product_codes (необязательно): список присвоенных товарных кодов; каждый элемент списка — массив со следующими ключами:
      • id: числовой идентификатор кода,
      • code: строковый идентификатор кода,
      • name (необязательно): название,
      • icon (необязательно): URL иконки,
      • logo (необязательно): URL логотипа,
      • values: массив значений, присвоенных позиции заказа.

Пример

$order = new waOrder([
    'contact' => new waContact(123),
    'items' => [
        [
            'id' => $item['id'],
            'name' => $item['name'],
            'price' => $item['price'],
            'quantity' => 10,
        ],
    ],
]);

public function getContact()

Возвращает экземпляр класса waContact с данными клиента.

Пример

$order = new waOrder([
    'contact' => new waContact(123),
    'items' => [
        [
            'id' => $item['id'],
            'name' => $item['name'],
            'price' => $item['price'],
            'quantity' => 10,
        ],
    ],
]);

$customer = $order->getContact();

public function getContactField ($field, $format = null)

Возвращает значение из данных клиента.

Параметры

• $field

  Имя контактного поля клиента.

• $format

  Формат, в котором нужно получить значение поля. Поддерживаются обозначения формата для метода get() класса waContact.

Пример

$order = new waOrder([
    'contact' => new waContact(123),
    'items' => [
        [
            'id' => $item['id'],
            'name' => $item['name'],
            'price' => $item['price'],
            'quantity' => 10,
        ],
    ],
]);

$customer_email = $order->getContactField('email', 'default');

Результат

name@domain.ru

public function hasFractionalQuantity()

Возвращает информацию наличии в заказе позиций с дробным количеством.

Пример

$order = new waOrder([
    'contact' => new waContact(123),
    'items' => [
        [
            'id' => $items[0]['id'],
            'name' => $items[0]['name'],
            'price' => $items[0]['price'],
            'quantity' => 2.5,
        ],
        [
            'id' => $items[1]['id'],
            'name' => $items[1]['name'],
            'price' => $items[1]['price'],
            'quantity' => 3,
        ],
    ],
]);

$order->hasFractionalQuantity();

Результат

true

public function repackFractionalQuantity()

Конвертирует дробные количества позиций заказа в целочисленные. Если количество позиции выражено дробным числом, оно заменяется на 1, а информация о дробном количестве вместе с названием единицы измерения (если оно указано) добавляется в скобках к названию позиции. Цена позиции умножается на старое значение количества. Метод возвращает новый экземпляр класса с конвертированной информацией о позициях заказа — в исходный экземпляр изменения не вносятся.

Пример

$order = new waOrder([
    'contact' => new waContact(123),
    'items' => [
        [
            'id' => $item['id'],
            'name' => $item['name'],
            'price' => $item['price'],
            'quantity' => 2.5,
            'stock_unit' => 'кг',
        ],
    ],
]);

waLog::dump($order->repackFractionalQuantity()->items);

Результат

[
    [
        'id' => 123,
        'name' => 'Картофель (2.5 кг)',
        'price' => 122.5,
        'quantity' => 1,
        'description' => NULL,
        'img' => NULL,
        'height' => NULL,
        'width' => NULL,
        'length' => NULL,
        'weight' => NULL,
        'product_codes' => [],
        'total' => 122.5,
    ],
]

public function hasStockUnits()

Возвращает информацию наличии в заказе позиций с нестандартными единицами измерения количества. Если в конструктор заказа был передан флаг с ключом 'has_custom_stock_units', то метод возвращает логический (Boolean) эквивалент этого значения. В противном случае метод ищет в свойствах позиций заказа наличие непустого обозначения единицы измерения с ключом 'stock_unit'.

Пример

$order = new waOrder([
    'has_custom_stock_units' => true,
    'contact' => new waContact(123),
    'items' => [
        [
            'id' => $items[0]['id'],
            'name' => $items[0]['name'],
            'price' => $items[0]['price'],
            'quantity' => 2.5,
        ],
        [
            'id' => $items[1]['id'],
            'name' => $items[1]['name'],
            'price' => $items[1]['price'],
            'quantity' => 3,
        ],
    ],
]);

$order->hasStockUnits();

Результат

// потому что в конструктор передан параметр 'has_custom_stock_units' с непустым значением
true

Пример

$order = new waOrder([
    'contact' => new waContact(123),
    'items' => [
        [
            'id' => $items[0]['id'],
            'name' => $items[0]['name'],
            'price' => $items[0]['price'],
            'quantity' => 2.5,
            'stock_unit' => 'кг',
        ],
        [
            'id' => $items[1]['id'],
            'name' => $items[1]['name'],
            'price' => $items[1]['price'],
            'quantity' => 3,
            'stock_unit' => 'кг',
        ],
    ],
]);

$order->hasStockUnits();

Результат

// потому что в свойствах позиций заказа есть заполненная единица измерения с ключом 'stock_unit'
true

public function getTotalDiscount()

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

Пример

$order = new waOrder([
    'contact' => new waContact(123),
    'items' => [
        [
            'id' => $items[0]['id'],
            'name' => $items[0]['name'],
            'price' => $items[0]['price'],
            'quantity' => 10,
            'total_discount' => 15,
        ],
        [
            'id' => $items[1]['id'],
            'name' => $items[1]['name'],
            'price' => $items[1]['price'],
            'quantity' => 20,
            'total_discount' => 30,
        ],
    ],
]);

$order->getTotalDiscount();

Результат

45

public function getTotalQuantity()

Возвращает общее количество всех позиций заказа.

Пример

$order = new waOrder([
    'contact' => new waContact(123),
    'items' => [
        [
            'id' => $items[0]['id'],
            'name' => $items[0]['name'],
            'price' => $items[0]['price'],
            'quantity' => 10,
        ],
        [
            'id' => $items[1]['id'],
            'name' => $items[1]['name'],
            'price' => $items[1]['price'],
            'quantity' => 20,
        ],
    ],
]);

$order->getTotalQuantity();

Результат

30