WooCommerce Code Reference

WC_Abstract_Legacy_Order extends WC_Data
in package

Legacy Abstract Order

Legacy and deprecated functions are here to keep the WC_Abstract_Order clean. This class will be removed in future versions.

Tags
version
3.0.0
category

Abstract Class

author

WooThemes

Table of Contents

$cache_group  : string
Stores meta in cache for future reads.
$changes  : array<string|int, mixed>
Core data changes for this object.
$data  : array<string|int, mixed>
Core data for this object. Name value pairs (name + default value).
$data_store  : object
Contains a reference to the data store for this class.
$default_data  : array<string|int, mixed>
Set to _data on construct so we can track and reset data if needed.
$extra_data  : array<string|int, mixed>
Extra data for this object. Name value pairs (name + default value).
$id  : int
ID for this object.
$legacy_datastore_props  : array<string|int, mixed>
List of properties that were earlier managed by data store. However, since DataStore is a not a stored entity in itself, they used to store data in metadata of the data object.
$meta_data  : array<string|int, mixed>
Stores additional meta data.
$object_read  : bool
This is false until the object is read from the DB.
$object_type  : string
This is the name of this object type.
__clone()  : mixed
When the object is cloned, make sure meta is duplicated correctly.
__construct()  : mixed
Default constructor.
__get()  : mixed
Magic __get method for backwards compatibility.
__isset()  : bool
Magic __isset method for backwards compatibility. Handles legacy properties which could be accessed directly in the past.
__sleep()  : array<string|int, mixed>
Only store the object ID to avoid serializing the data object instance.
__toString()  : string
Change data to JSON format.
__wakeup()  : mixed
Re-run the constructor with the object ID.
add_coupon()  : int
Add coupon code to the order.
add_fee()  : int
Add a fee to the order.
add_meta_data()  : mixed
Add meta data.
add_shipping()  : int
Add a shipping row to the order.
add_tax()  : int
Add a tax row to the order.
apply_changes()  : mixed
Merge changes with data and clear.
cancel_order()  : mixed
Cancel the order and restore the cart (before payment).
decrease_coupon_usage_counts()  : mixed
Decrease applied coupon counts.
delete()  : bool
Delete an object, set the ID to 0, and return result.
delete_meta_data()  : mixed
Delete meta data.
delete_meta_data_by_mid()  : mixed
Delete meta data.
delete_meta_data_value()  : mixed
Delete meta data with a matching value.
display_item_downloads()  : mixed
Display download links for an order item.
display_item_meta()  : mixed
Display meta data belonging to an item.
email_order_items_table()  : string
Output items for display in html emails.
expand_item_meta()  : array<string|int, mixed>
Expand item meta into the $item array.
generate_meta_cache_key()  : string
Generate cache key from id and group.
get_changes()  : array<string|int, mixed>
Return data changes only.
get_data()  : array<string|int, mixed>
Returns all data for this object.
get_data_keys()  : array<string|int, mixed>
Returns array of expected data keys for this object.
get_data_store()  : object
Get the data store.
get_download_url()  : string
Get the Download URL.
get_extra_data_keys()  : array<string|int, mixed>
Returns all "extra" data keys for an object (for sub objects like product types).
get_id()  : int
Returns the unique ID for this object.
get_item_downloads()  : array<string|int, mixed>
Get the downloadable files for an item in this order.
get_item_meta()  : array<string|int, mixed>|string
Get order item meta.
get_item_meta_array()  : array<string|int, mixed>
Get all item meta data in array format in the order it was saved. Does not group meta by key like get_item_meta().
get_meta()  : mixed
Get Meta Data by Key.
get_meta_cache_key()  : string
Helper method to compute meta cache key. Different from WP Meta cache key in that meta data cached using this key also contains meta_id column.
get_meta_data()  : array<string|int, mixed>
Get All Meta Data.
get_object_read()  : bool
Get object read property.
get_order()  : bool
Gets an order from the database.
get_order_currency()  : mixed
Get currency.
get_product_from_item()  : WC_Product|bool
Get a product (either product or variation).
get_total_shipping()  : float
Gets shipping total. Alias of WC_Order::get_shipping_total().
get_used_coupons()  : array<string|int, mixed>
Get coupon codes only.
has_meta()  : array<string|int, mixed>
has_meta function for order items. This is different to the WC_Data version and should be removed in future versions.
increase_coupon_usage_counts()  : mixed
Increase applied coupon counts.
init_meta_data()  : mixed
Helper function to initialize metadata entries from filtered raw meta data.
legacy_set_total()  : bool
Set an order total.
meta_exists()  : bool
See if meta data exists, since get_meta always returns a '' or array().
populate()  : mixed
Populates an order from the loaded post data.
prime_raw_meta_data_cache()  : mixed
Prime caches for raw meta data. This includes meta_id column as well, which is not included by default in WP meta data.
read_meta_data()  : mixed
Read Meta Data from the database. Ignore any internal properties.
record_product_sales()  : mixed
Record sales.
reduce_order_stock()  : mixed
Reduce stock levels for all line items in the order.
save()  : int
Save should create or update based on object existence.
save_meta_data()  : mixed
Update Meta Data in the database.
send_stock_notifications()  : mixed
Send the stock notifications.
set_address()  : mixed
Set the customer address.
set_defaults()  : mixed
Set all props to default values.
set_id()  : mixed
Set ID.
set_meta_data()  : mixed
Set all meta data from array.
set_object_read()  : mixed
Set object read property.
set_props()  : bool|WP_Error
Set a collection of props in one go, collect any errors, and return the result.
update_coupon()  : int
Update coupon for order. Note this does not update order totals.
update_fee()  : int
Update fee for order.
update_meta_data()  : mixed
Update meta data by key or ID, if provided.
update_product()  : int
Update a line item for the order.
update_shipping()  : int
Update shipping method for order.
update_tax()  : int
Update tax line on order.
error()  : mixed
When invalid data is found, throw an exception unless reading from the DB.
filter_null_meta()  : bool
Filter null meta values from array.
get_hook_prefix()  : string
Prefix for action and filter hooks on data.
get_prop()  : mixed
Gets a prop for a getter method.
init()  : mixed
Load the order object. Called from the constructor.
is_internal_meta_key()  : bool
Check if the key is an internal one.
maybe_read_meta_data()  : mixed
Read meta data if null.
set_date_prop()  : mixed
Sets a date prop whilst handling formatting and datetime objects.
set_prop()  : mixed
Sets a prop for a setter method.

Properties

$default_data

Set to _data on construct so we can track and reset data if needed.

protected array<string|int, mixed> $default_data = array()
Tags
since
3.0.0

$extra_data

Extra data for this object. Name value pairs (name + default value).

protected array<string|int, mixed> $extra_data = array()

Used as a standard way for sub classes (like product types) to add additional information to an inherited class.

Tags
since
3.0.0

$legacy_datastore_props

List of properties that were earlier managed by data store. However, since DataStore is a not a stored entity in itself, they used to store data in metadata of the data object.

protected array<string|int, mixed> $legacy_datastore_props = array()

With custom tables, some of these are moved from metadata to their own columns, but existing code will still try to add them to metadata. This array is used to keep track of such properties.

Only reason to add a property here is that you are moving properties from DataStore instance to data object. If you are adding a new property, consider adding it to to $data array instead.

Methods

__construct()

Default constructor.

public __construct(int|object|array<string|int, mixed> $read) : mixed
Parameters
$read : int|object|array<string|int, mixed>

ID to load from the DB (optional) or already queried data.

Return values
mixed

__isset()

Magic __isset method for backwards compatibility. Handles legacy properties which could be accessed directly in the past.

public __isset(string $key) : bool
Parameters
$key : string
Return values
bool

__sleep()

Only store the object ID to avoid serializing the data object instance.

public __sleep() : array<string|int, mixed>
Return values
array<string|int, mixed>

__wakeup()

Re-run the constructor with the object ID.

public __wakeup() : mixed

If the object no longer exists, remove the ID.

Return values
mixed

add_coupon()

Add coupon code to the order.

public add_coupon([string|array<string|int, mixed> $code = array() ], int $discount, int $discount_tax) : int
Parameters
$code : string|array<string|int, mixed> = array()
$discount : int

tax amount.

$discount_tax : int

amount.

Tags
throws
WC_Data_Exception
Return values
intorder item ID

add_fee()

Add a fee to the order.

public add_fee(object $fee) : int

Order must be saved prior to adding items.

Fee is an amount of money charged for a particular piece of work or for a particular right or service, and not supposed to be negative.

Parameters
$fee : object

Fee data.

Tags
throws
WC_Data_Exception
Return values
intUpdated order item ID.

add_meta_data()

Add meta data.

public add_meta_data(string $key, string|array<string|int, mixed> $value[, bool $unique = false ]) : mixed
Parameters
$key : string

Meta key.

$value : string|array<string|int, mixed>

Meta value.

$unique : bool = false

Should this be a unique key?.

Tags
since
2.6.0
Return values
mixed

add_tax()

Add a tax row to the order.

public add_tax(int $tax_rate_id, int $tax_amount, int $shipping_tax_amount) : int
Parameters
$tax_rate_id : int
$tax_amount : int

amount of tax.

$shipping_tax_amount : int

shipping amount.

Tags
throws
WC_Data_Exception
Return values
intorder item ID

cancel_order()

Cancel the order and restore the cart (before payment).

public cancel_order([string $note = '' ]) : mixed
Parameters
$note : string = ''

(default: '') Optional note to add.

Tags
deprecated
3.0.0

Moved to event handler.

Return values
mixed

delete()

Delete an object, set the ID to 0, and return result.

public delete([bool $force_delete = false ]) : bool
Parameters
$force_delete : bool = false

Should the date be deleted permanently.

Tags
since
2.6.0
Return values
boolresult

delete_meta_data()

Delete meta data.

public delete_meta_data(string $key) : mixed
Parameters
$key : string

Meta key.

Tags
since
2.6.0
Return values
mixed

delete_meta_data_by_mid()

Delete meta data.

public delete_meta_data_by_mid(int $mid) : mixed
Parameters
$mid : int

Meta ID.

Tags
since
2.6.0
Return values
mixed

delete_meta_data_value()

Delete meta data with a matching value.

public delete_meta_data_value(string $key, mixed $value) : mixed
Parameters
$key : string

Meta key.

$value : mixed

Meta value. Entries will only be removed that match the value.

Tags
since
7.7.0
Return values
mixed

display_item_downloads()

Display download links for an order item.

public display_item_downloads(array<string|int, mixed> $item) : mixed
Parameters
$item : array<string|int, mixed>
Return values
mixed

display_item_meta()

Display meta data belonging to an item.

public display_item_meta(array<string|int, mixed> $item) : mixed
Parameters
$item : array<string|int, mixed>
Return values
mixed

email_order_items_table()

Output items for display in html emails.

public email_order_items_table([array<string|int, mixed> $args = array() ]) : string
Parameters
$args : array<string|int, mixed> = array()

Items args.

Tags
deprecated
3.0.0

Moved to template functions.

Return values
string

expand_item_meta()

Expand item meta into the $item array.

public expand_item_meta(array<string|int, mixed> $item) : array<string|int, mixed>
Parameters
$item : array<string|int, mixed>

before expansion.

Tags
deprecated
3.0.0

Item meta no longer expanded due to new order item classes. This function now does nothing to avoid data breakage.

Return values
array<string|int, mixed>

generate_meta_cache_key()

Generate cache key from id and group.

public static generate_meta_cache_key(int|string $id, string $cache_group) : string
Parameters
$id : int|string

Object ID.

$cache_group : string

Group name use to store cache. Whole group cache can be invalidated in one go.

Tags
since
4.7.0
Return values
stringMeta cache key.

get_changes()

Return data changes only.

public get_changes() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed>

get_data()

Returns all data for this object.

public get_data() : array<string|int, mixed>
Tags
since
2.6.0
Return values
array<string|int, mixed>

get_data_keys()

Returns array of expected data keys for this object.

public get_data_keys() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed>

get_download_url()

Get the Download URL.

public get_download_url(int $product_id, int $download_id) : string
Parameters
$product_id : int
$download_id : int
Return values
string

get_extra_data_keys()

Returns all "extra" data keys for an object (for sub objects like product types).

public get_extra_data_keys() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed>

get_item_downloads()

Get the downloadable files for an item in this order.

public get_item_downloads(array<string|int, mixed> $item) : array<string|int, mixed>
Parameters
$item : array<string|int, mixed>
Return values
array<string|int, mixed>

get_item_meta()

Get order item meta.

public get_item_meta(mixed $order_item_id[, string $key = '' ][, bool $single = false ]) : array<string|int, mixed>|string
Parameters
$order_item_id : mixed
$key : string = ''

(default: '')

$single : bool = false

(default: false)

Tags
deprecated
3.0.0
Return values
array<string|int, mixed>|string

get_item_meta_array()

Get all item meta data in array format in the order it was saved. Does not group meta by key like get_item_meta().

public get_item_meta_array(mixed $order_item_id) : array<string|int, mixed>
Parameters
$order_item_id : mixed
Return values
array<string|int, mixed>of objects

get_meta()

Get Meta Data by Key.

public get_meta([string $key = '' ][, bool $single = true ][, string $context = 'view' ]) : mixed
Parameters
$key : string = ''

Meta Key.

$single : bool = true

return first found meta with key, or all with $key.

$context : string = 'view'

What the value is for. Valid values are view and edit.

Tags
since
2.6.0
Return values
mixed

get_meta_cache_key()

Helper method to compute meta cache key. Different from WP Meta cache key in that meta data cached using this key also contains meta_id column.

public get_meta_cache_key() : string
Tags
since
4.7.0
Return values
string

get_meta_data()

Get All Meta Data.

public get_meta_data() : array<string|int, mixed>
Tags
since
2.6.0
Return values
array<string|int, mixed>of objects.

get_total_shipping()

Gets shipping total. Alias of WC_Order::get_shipping_total().

public get_total_shipping() : float
Tags
deprecated
3.0.0

since this is an alias only.

Return values
float

get_used_coupons()

Get coupon codes only.

public get_used_coupons() : array<string|int, mixed>
Tags
deprecated
3.7.0
  • Replaced with better named method to reflect the actual data being returned.
Return values
array<string|int, mixed>

has_meta()

has_meta function for order items. This is different to the WC_Data version and should be removed in future versions.

public has_meta(int $order_item_id) : array<string|int, mixed>
Parameters
$order_item_id : int
Tags
deprecated
3.0
Return values
array<string|int, mixed>of meta data.

init_meta_data()

Helper function to initialize metadata entries from filtered raw meta data.

public init_meta_data([array<string|int, mixed> $filtered_meta_data = array() ]) : mixed
Parameters
$filtered_meta_data : array<string|int, mixed> = array()

Filtered metadata fetched from DB.

Return values
mixed

legacy_set_total()

Set an order total.

public legacy_set_total(float $amount[, string $total_type = 'total' ]) : bool
Parameters
$amount : float
$total_type : string = 'total'
Return values
bool

meta_exists()

See if meta data exists, since get_meta always returns a '' or array().

public meta_exists([string $key = '' ]) : bool
Parameters
$key : string = ''

Meta Key.

Tags
since
3.0.0
Return values
bool

populate()

Populates an order from the loaded post data.

public populate(mixed $result) : mixed
Parameters
$result : mixed
Tags
deprecated
3.0
Return values
mixed

prime_raw_meta_data_cache()

Prime caches for raw meta data. This includes meta_id column as well, which is not included by default in WP meta data.

public static prime_raw_meta_data_cache(array<string|int, mixed> $raw_meta_data_collection, string $cache_group) : mixed
Parameters
$raw_meta_data_collection : array<string|int, mixed>

Array of objects of { object_id => array( meta_row_1, meta_row_2, ... }.

$cache_group : string

Name of cache group.

Tags
since
4.7.0
Return values
mixed

read_meta_data()

Read Meta Data from the database. Ignore any internal properties.

public read_meta_data([bool $force_read = false ]) : mixed

Uses it's own caches because get_metadata does not provide meta_ids.

Parameters
$force_read : bool = false

True to force a new DB read (and update cache).

Tags
since
2.6.0
Return values
mixed

send_stock_notifications()

Send the stock notifications.

public send_stock_notifications( $product,  $new_stock,  $qty_ordered) : mixed
Parameters
$product :
$new_stock :
$qty_ordered :
Tags
deprecated
3.0.0

No longer needs to be called directly.

Return values
mixed

set_address()

Set the customer address.

public set_address(array<string|int, mixed> $address[, string $type = 'billing' ]) : mixed
Parameters
$address : array<string|int, mixed>

Address data.

$type : string = 'billing'

Type of address; 'billing' or 'shipping'.

Return values
mixed

set_meta_data()

Set all meta data from array.

public set_meta_data(array<string|int, mixed> $data) : mixed
Parameters
$data : array<string|int, mixed>

Key/Value pairs.

Tags
since
2.6.0
Return values
mixed

set_object_read()

Set object read property.

public set_object_read([bool $read = true ]) : mixed
Parameters
$read : bool = true

Should read?.

Tags
since
3.0.0
Return values
mixed

set_props()

Set a collection of props in one go, collect any errors, and return the result.

public set_props(array<string|int, mixed> $props[, string $context = 'set' ]) : bool|WP_Error

Only sets using public methods.

Parameters
$props : array<string|int, mixed>

Key value pairs to set. Key is the prop and should map to a setter function name.

$context : string = 'set'

In what context to run this.

Tags
since
3.0.0
Return values
bool|WP_Error

update_coupon()

Update coupon for order. Note this does not update order totals.

public update_coupon(object|int $item, array<string|int, mixed> $args) : int
Parameters
$item : object|int
$args : array<string|int, mixed>
Tags
throws
WC_Data_Exception
Return values
intupdated order item ID

update_fee()

Update fee for order.

public update_fee(object|int $item, array<string|int, mixed> $args) : int

Note this does not update order totals.

Parameters
$item : object|int
$args : array<string|int, mixed>
Tags
throws
WC_Data_Exception
Return values
intupdated order item ID

update_meta_data()

Update meta data by key or ID, if provided.

public update_meta_data(string $key, string|array<string|int, mixed> $value, int $meta_id) : mixed
Parameters
$key : string

Meta key.

$value : string|array<string|int, mixed>

Meta value.

$meta_id : int

Meta ID.

Tags
since
2.6.0
Return values
mixed

update_product()

Update a line item for the order.

public update_product(object|int $item, WC_Product $product, array<string|int, mixed> $args) : int

Note this does not update order totals.

Parameters
$item : object|int

order item ID or item object.

$product : WC_Product
$args : array<string|int, mixed>

data to update.

Tags
throws
WC_Data_Exception
Return values
intupdated order item ID

update_shipping()

Update shipping method for order.

public update_shipping(object|int $item, array<string|int, mixed> $args) : int

Note this does not update the order total.

Parameters
$item : object|int
$args : array<string|int, mixed>
Tags
throws
WC_Data_Exception
Return values
intupdated order item ID

update_tax()

Update tax line on order.

public update_tax(object|int $item, array<string|int, mixed> $args) : int

Note this does not update order totals.

Parameters
$item : object|int
$args : array<string|int, mixed>
Tags
since
3.0
throws
WC_Data_Exception
Return values
intupdated order item ID

error()

When invalid data is found, throw an exception unless reading from the DB.

protected error(string $code, string $message[, int $http_status_code = 400 ][, array<string|int, mixed> $data = array() ]) : mixed
Parameters
$code : string

Error code.

$message : string

Error message.

$http_status_code : int = 400

HTTP status code.

$data : array<string|int, mixed> = array()

Extra error data.

Tags
throws
WC_Data_Exception

Data Exception.

since
3.0.0
Return values
mixed

filter_null_meta()

Filter null meta values from array.

protected filter_null_meta(mixed $meta) : bool
Parameters
$meta : mixed

Meta value to check.

Tags
since
3.0.0
Return values
bool

get_prop()

Gets a prop for a getter method.

protected get_prop(string $prop[, string $context = 'view' ]) : mixed

Gets the value from either current pending changes, or the data itself. Context controls what happens to the value before it's returned.

Parameters
$prop : string

Name of prop to get.

$context : string = 'view'

What the value is for. Valid values are view and edit.

Tags
since
3.0.0
Return values
mixed

is_internal_meta_key()

Check if the key is an internal one.

protected is_internal_meta_key(string $key) : bool
Parameters
$key : string

Key to check.

Tags
since
3.2.0
Return values
booltrue if it's an internal key, false otherwise

set_date_prop()

Sets a date prop whilst handling formatting and datetime objects.

protected set_date_prop(string $prop, string|int $value) : mixed
Parameters
$prop : string

Name of prop to set.

$value : string|int

Value of the prop.

Tags
since
3.0.0
Return values
mixed

set_prop()

Sets a prop for a setter method.

protected set_prop(string $prop, mixed $value) : mixed

This stores changes in a special array so we can track what needs saving the DB later.

Parameters
$prop : string

Name of prop to set.

$value : mixed

Value of the prop.

Tags
since
3.0.0
Return values
mixed