waOrder

System-wide management of clients’ orders.

Contents...

This class is used to pass information about any types of orders to payment and shipping plugins.

The parent class is ArrayAccess; therefore, you can set class instance properties directly, without using class methods:

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

// setting the order currency
$order->currency = 'USD';

Order properties

The following class instance properties are available:

  • id: numeric order ID,
  • id_str: formatted (string) order ID,
  • contact_id: client contact ID,
  • currency: currency ISO code,
  • total: total order amount,
  • tax: amount of applicable tax,
  • discount: total discount amount,
  • subtotal: subtotal amount, i.e. the cost of all order items without the shipping cost,
  • shipping: shipping cost,
  • shipping_name: shopping option name,
  • payment_name: payment method name,
  • tax_included: flag of a tax included in the items’ prices,
  • recurrent: flag of a recurrent payment order,
  • save_card: flag of an order to be paid for by a bank card whose data has been saved for future payments,
  • description: localized description in the current language,
  • description_en: common description in English,
  • datetime: date and time of the order,
  • update_datetime: date and time of the latest order update,
  • paid_datetime: date and time of the order payment,
  • shipping_params: shipping option parameters,
  • shipping_data: shipping-related order properties,
  • shipping_rate_id: shipping option ID,
  • shipping_plugin: shipping plugin identifier,
  • shipping_tax_rate: shipping tax rate,
  • shipping_tax_included: flag of the tax included in the shipping cost,
  • shipping_address: shipping address as an array with the following keys:
  • shipping_address['firstname']: payer’s first name, if the billing address matches the shipping address,
  • shipping_address['lastname']: payer’s last name, if the billing address matches the shipping address,
  • shipping_address['name']: payer’s full name, if the billing address matches the shipping address,
  • shipping_address['zip']: ZIP code,
  • shipping_address['street']: street address,
  • shipping_address['city']: locality name,
  • shipping_address['region']: region code,
  • shipping_address['region_name']: region name,
  • shipping_address['country']: country ISO code,
  • shipping_address['country_name']: country name,
  • shipping_address['address']: full address as a string,
  • billing_params: payment method parameters,
  • billing_data: payment-related order properties,
  • billing_address: billing address, with the same keys as described for the 'shipping_address' property,
  • items: order item list (see the structure description in the description of the class constructor),
  • total_quantity: total quantity of order items,
  • contact_email (readonly): client’s main email address,
  • contact_name (readonly): client’s full name,
  • comment: comment to the order,
  • params: array of extra order parameters,
  • card_native_id: identifier of a payment card of the client, saved for recurrent orders.

Methods

public function __construct ($data = [])

Creates a class instance to work with an individual order.

Parameters

  • $data

    Array of order parameters with the following optional keys:

    • contact: Instance of the waContact class containing the client data.
    • params: Array of order parameters with optional keys of the following kinds:
      • [type]_[group]_[name]: Instead of [type] can be used shipping, and payment or billing. Instead of [group] can be used params (shipping or payment parameters), data (shipping or payment-related order data). Instead of [name] can be used various parameter keys.
      • shipping_[name]: Instead of [name] can be used parameter names rate_id (shipping rate ID), plugin (shipping plugin identifier), name (shipping option name).
    • items: Order item list. Each list item must be an array with the following keys:
      • id: numeric ID,
      • name,
      • price,
      • description (optional),
      • img (optional): image URL,
      • height (optional),
      • width (optional),
      • length (optional),
      • weight (optional),
      • quantity (optional): default is 1,
      • discount (optional): discount pre unit, used to calculate the total discount amount if the total_discount property is empty,
      • total_discount (optional): total discount amount pre-calculated for the specified item quantity,
      • product_codes (optional): list of assigned product codes, each being an array with the following keys:
        • id: numeric code ID,
        • code: string code identifier,
        • name (optional),
        • icon (optional): icon URL,
        • logo (optional): logo URL,
        • values: array of code values assigned to the order item.

Example

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

public function getContact()

Returns a waContact class instance with the client’s data.

Example

$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)

Returns a client property value.

Parameters

  • $field

    Client contact field name identifier.

  • $format

    Format in which the field value must be returned. Supported are formats described for method get() of class waContact.

Example

$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');

Result

name@domain.ru

public function hasFractionalQuantity()

Returns information about the availability of order items with fractional quantities.

Example

$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();

Result

true

public function repackFractionalQuantity()

Converts fractional order item quantities into integers. If an item’s quantity is expressed in a fractional number then it is replace with 1 and the information abt the fractional quantity, with the quantity unit name (if available), is added in the parentheses to the item name. The item price is multiplied by the old quantity value. The method returns a new class instance containing the converted items information; the original class instance is not affected.

Example

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

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

Result

[
    [
        'id' => 123,
        'name' => 'Potatoes (2.5 lb.)',
        '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()

Returns information about the availability of order items with custom quantity units. If a flag with the 'has_custom_stock_units' key was passed to the class constructor within the input parameter then the method returns a Boolean equivalent of its value. Otherwise, the method will look for non-empty quantity unit names with the 'stock_unit' key in the order items’ properties.

Example

$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();

Result

// because non-empty parameter value with the 'has_custom_stock_units' flag was passed to the class constructor
true

Example

$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' => 'lb',
        ],
        [
            'id' => $items[1]['id'],
            'name' => $items[1]['name'],
            'price' => $items[1]['price'],
            'quantity' => 3,
            'stock_unit' => 'lb',
        ],
    ],
]);

$order->hasStockUnits();

Result

// because order items have quantity unit names with the 'stock_unit' key
true

public function getTotalDiscount()

Returns the total discount amount. The result is calculated using total_discount values in the order items’ properties.

Example

$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();

Result

45

public function getTotalQuantity()

Returns the total quantity of all order items.

Example

$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();

Result

30