WooCommerce Code Reference

WC_Order_Data_Store_CPT extends Abstract_WC_Order_Data_Store_CPT
in package
implements WC_Object_Data_Store_Interface, WC_Order_Data_Store_Interface

WC Order Data Store: Stored in CPT.

Tags
version
3.0.0

Interfaces, Classes and Traits

WC_Object_Data_Store_Interface
WC Data Store Interface
WC_Order_Data_Store_Interface
WC Order Data Store Interface

Table of Contents

$internal_data_store_key_getters  : array<string|int, string>
Custom setters for props. Add key here if it has corresponding set_ and get_ method present.
$internal_meta_keys  : array<string|int, mixed>
Data stored in meta keys, but not considered "meta" for an order.
$meta_type  : string
Meta type. This should match up with the types available at https://developer.wordpress.org/reference/functions/add_metadata/.
$must_exist_meta_keys  : array<string|int, mixed>
Meta data which should exist in the DB, even if empty.
$object_id_field_for_meta  : string
This only needs set if you are using a custom metadata type (for example payment tokens.
add_meta()  : int
Add new piece of meta.
create()  : mixed
Method to create a new order in the database.
delete()  : void
Method to delete an order from the database.
delete_from_lookup_table()  : mixed
Delete lookup table data for an ID.
delete_items()  : mixed
Remove all line items (products, coupons, shipping, taxes) from the order.
delete_meta()  : mixed
Deletes meta based on meta ID.
filter_raw_meta_data()  : mixed|void
Helper method to filter internal meta keys from all meta data rows for the object.
get_coupon_held_keys()  : array<string|int, mixed>|string
Return array of coupon_code => meta_key for coupon which have usage limit and have tentative keys.
get_coupon_held_keys_for_users()  : mixed
Return array of coupon_code => meta_key for coupon which have usage limit per customer and have tentative keys.
get_download_permissions_granted()  : bool
Gets information about whether permissions were generated yet.
get_email_sent()  : bool
Whether email have been sent for this order.
get_internal_data_store_key_getters()  : array<string|int, string>
Return internal key getters name.
get_internal_meta_keys()  : array<string|int, mixed>
Return list of internal meta keys.
get_new_order_email_sent()  : bool
Whether email have been sent for this order.
get_order_count()  : int
Return count of orders with a specific status.
get_order_id_by_order_key()  : int
Finds an Order ID based on an order key.
get_order_item_type()  : string
Return the order type of a given item which belongs to WC_Order.
get_order_stock_reduced()  : bool
Stores information about whether stock was reduced.
get_order_type()  : string
Get the order type based on Order ID.
get_orders()  : array<string|int, mixed>|object
Get all orders matching the passed in args.
get_payment_token_ids()  : array<string|int, mixed>
Get token ids for an order.
get_recorded_coupon_usage_counts()  : bool
Gets information about whether coupon counts were updated.
get_recorded_sales()  : bool
Gets information about whether sales were recorded.
get_stock_reduced()  : bool
Gets information about whether stock was reduced.
get_title()  : string
Get the order's title.
get_total_refunded()  : float
Get amount already refunded.
get_total_shipping_refunded()  : float
Get the total shipping refunded.
get_total_tax_refunded()  : float
Get the total tax refunded.
get_unpaid_orders()  : array<string|int, mixed>
Get unpaid orders after a certain date,
order_exists()  : bool
Check if an order exists by id.
parse_date_for_wp_query()  : array<string|int, mixed>
Map a valid date query var to WP_Query arguments.
prime_caches_for_orders()  : mixed
Helper method to prime caches for orders. Call this if you are going to be fetching orders in a loop.
query()  : array<string|int, mixed>|object
Query for Orders matching specific criteria.
read()  : mixed
Method to read an order from the database.
read_items()  : array<string|int, mixed>
Read order items of a specific type from the database for this order.
read_meta()  : array<string|int, mixed>
Returns an array of meta for an object.
release_held_coupons()  : mixed
Release all coupons held by this order.
search_orders()  : array<string|int, mixed>
Search order data for a term and return ids.
set_coupon_held_keys()  : mixed
Add/Update list of meta keys that are currently being used by this order to hold a coupon.
set_download_permissions_granted()  : mixed
Stores information about whether permissions were generated yet.
set_email_sent()  : mixed
Stores information about whether email was sent.
set_new_order_email_sent()  : mixed
Stores information about whether email was sent.
set_order_stock_reduced()  : mixed
Gets information about whether stock was reduced.
set_recorded_coupon_usage_counts()  : mixed
Stores information about whether coupon counts were updated.
set_recorded_sales()  : mixed
Stores information about whether sales were recorded.
set_stock_reduced()  : mixed
Stores information about whether stock was reduced.
untrash_order()  : bool
Attempts to restore the specified order back to its original status (after having been trashed).
update()  : mixed
Method to update an order in the database.
update_meta()  : mixed
Update meta.
update_order_from_object()  : bool
Given an initialized order object, update the post/postmeta records.
update_payment_token_ids()  : mixed
Update token ids for an order.
update_post_modified_data()  : array<string|int, mixed>
Change the modified date of the post to match the order's modified date if passed.
clear_caches()  : mixed
Clear any caches.
exclude_internal_meta_keys()  : bool
Callback to remove unwanted meta data.
get_data_for_lookup_table()  : array<string|int, mixed>
Get data to save to a lookup table.
get_db_info()  : array<string|int, mixed>
Table structure is slightly different between meta types, this function will return what we need to know.
get_order_key()  : string
Get order key.
get_post_excerpt()  : string
Excerpt for post.
get_post_status()  : string
Get the status to save to the post object.
get_post_title()  : string
Get a title for the new post type.
get_primary_key_for_lookup_table()  : string
Get primary key name for lookup table.
get_props_to_update()  : array<string|int, mixed>
Gets a list of props and meta keys that need updated based on change state or if they are present in the database or not.
get_search_stopwords()  : array<string|int, mixed>
Retrieve stopwords used when parsing search terms.
get_term_ids()  : array<string|int, mixed>
Get and store terms from a taxonomy.
get_valid_search_terms()  : array<string|int, mixed>
Check if the terms are suitable for searching.
get_wp_query_args()  : array<string|int, mixed>
Get valid WP_Query args from a WC_Order_Query's query variables.
prefix_key()  : string
Internal meta keys we don't want exposed as part of meta_data. This is in addition to all data props with _ prefix.
prime_order_item_caches_for_orders()  : mixed
Prime following caches: 1. item-$order_item_id For individual items.
read_order_data()  : mixed
Read order data. Can be overridden by child classes to load other props.
string_to_timestamp()  : int|null
Converts a WP post date string into a timestamp.
update_lookup_table()  : null
Update a lookup table for an object.
update_or_delete_post_meta()  : bool
Update meta data in, or delete it from, the database.
update_order_meta_from_object()  : mixed
Helper method to update order metadata from initialized order object.
update_post_meta()  : mixed
Helper method that updates all the post meta for an order based on it's settings in the WC_Order class.
compile_orders()  : array<string|int, mixed>
Compile order response and set caches as needed for order ids.
get_orders_generate_customer_meta_query()  : array<string|int, mixed>
Generate meta query for wc_get_orders.
prime_raw_meta_cache_for_orders()  : mixed
Prime cache for raw meta data for orders in bulk. Difference between this and WP built-in metadata is that this method also fetches `meta_id` field which we use and cache it.
prime_refund_caches_for_order()  : mixed
Prime refund cache for orders.
set_order_props()  : mixed
Set the properties of an object and log the first error found while doing so.

Properties

$internal_data_store_key_getters

Custom setters for props. Add key here if it has corresponding set_ and get_ method present.

protected array<string|int, string> $internal_data_store_key_getters = array('_download_permissions_granted' => 'download_permissions_granted', '_recorded_sales' => 'recorded_sales', '_recorded_coupon_usage_counts' => 'recorded_coupon_usage_counts', '_order_stock_reduced' => 'order_stock_reduced', '_new_order_email_sent' => 'new_order_email_sent')

$internal_meta_keys

Data stored in meta keys, but not considered "meta" for an order.

protected array<string|int, mixed> $internal_meta_keys = array('_customer_user', '_order_key', '_order_currency', '_billing_first_name', '_billing_last_name', '_billing_company', '_billing_address_1', '_billing_address_2', '_billing_city', '_billing_state', '_billing_postcode', '_billing_country', '_billing_email', '_billing_phone', '_shipping_first_name', '_shipping_last_name', '_shipping_company', '_shipping_address_1', '_shipping_address_2', '_shipping_city', '_shipping_state', '_shipping_postcode', '_shipping_country', '_shipping_phone', '_completed_date', '_paid_date', '_edit_lock', '_edit_last', '_cart_discount', '_cart_discount_tax', '_order_shipping', '_order_shipping_tax', '_order_tax', '_order_total', '_payment_method', '_payment_method_title', '_transaction_id', '_customer_ip_address', '_customer_user_agent', '_created_via', '_order_version', '_prices_include_tax', '_date_completed', '_date_paid', '_payment_tokens', '_billing_address_index', '_shipping_address_index', '_recorded_sales', '_recorded_coupon_usage_counts', '_download_permissions_granted', '_order_stock_reduced', '_new_order_email_sent')
Tags
since
3.0.0

$meta_type

Meta type. This should match up with the types available at https://developer.wordpress.org/reference/functions/add_metadata/.

protected string $meta_type = 'post'

WP defines 'post', 'user', 'comment', and 'term'.

$object_id_field_for_meta

This only needs set if you are using a custom metadata type (for example payment tokens.

protected string $object_id_field_for_meta = ''

This should be the name of the field your table uses for associating meta with objects. For example, in payment_tokenmeta, this would be payment_token_id.

Methods

delete_from_lookup_table()

Delete lookup table data for an ID.

public delete_from_lookup_table(int $id, string $table) : mixed
Parameters
$id : int

ID of object to update.

$table : string

Lookup table name.

Tags
since
3.6.0
Return values
mixed

filter_raw_meta_data()

Helper method to filter internal meta keys from all meta data rows for the object.

public filter_raw_meta_data(WC_Data &$object, array<string|int, mixed> $raw_meta_data) : mixed|void
Parameters
$object : WC_Data

WC_Data object.

$raw_meta_data : array<string|int, mixed>

Array of std object of meta data to be filtered.

Tags
since
4.7.0
Return values
mixed|void

get_coupon_held_keys()

Return array of coupon_code => meta_key for coupon which have usage limit and have tentative keys.

public get_coupon_held_keys(WC_Order $order[, int $coupon_id = null ]) : array<string|int, mixed>|string

Pass $coupon_id if key for only one of the coupon is needed.

Parameters
$order : WC_Order

Order object.

$coupon_id : int = null

If passed, will return held key for that coupon.

Return values
array<string|int, mixed>|stringKey value pair for coupon code and meta key name. If $coupon_id is passed, returns meta_key for only that coupon.

get_coupon_held_keys_for_users()

Return array of coupon_code => meta_key for coupon which have usage limit per customer and have tentative keys.

public get_coupon_held_keys_for_users(WC_Order $order[, int $coupon_id = null ]) : mixed
Parameters
$order : WC_Order

Order object.

$coupon_id : int = null

If passed, will return held key for that coupon.

Return values
mixed

get_order_count()

Return count of orders with a specific status.

public get_order_count(string $status) : int
Parameters
$status : string

Order status. Function wc_get_order_statuses() returns a list of valid statuses.

Return values
int

get_order_id_by_order_key()

Finds an Order ID based on an order key.

public get_order_id_by_order_key(string $order_key) : int
Parameters
$order_key : string

An order key has generated by.

Return values
intThe ID of an order, or 0 if the order could not be found

get_orders()

Get all orders matching the passed in args.

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

List of args passed to wc_get_orders().

Tags
deprecated
3.1.0
  • Use wc_get_orders instead.
see
wc_get_orders()
Return values
array<string|int, mixed>|object

order_exists()

Check if an order exists by id.

public order_exists(int $order_id) : bool
Parameters
$order_id : int

The order id to check.

Tags
since
8.0.0
Return values
boolTrue if an order exists with the given name.

parse_date_for_wp_query()

Map a valid date query var to WP_Query arguments.

public parse_date_for_wp_query(mixed $query_var, string $key[, array<string|int, mixed> $wp_query_args = array() ]) : array<string|int, mixed>

Valid date formats: YYYY-MM-DD or timestamp, possibly combined with an operator from $valid_operators. Also accepts a WC_DateTime object.

Parameters
$query_var : mixed

A valid date format.

$key : string

meta or db column key.

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

WP_Query args.

Tags
since
3.2.0
Return values
array<string|int, mixed>Modified $wp_query_args

prime_caches_for_orders()

Helper method to prime caches for orders. Call this if you are going to be fetching orders in a loop.

public prime_caches_for_orders(array<string|int, mixed> $order_ids, array<string|int, mixed> $query_vars) : mixed
Parameters
$order_ids : array<string|int, mixed>

List of order IDS to prime caches for.

$query_vars : array<string|int, mixed>

Original query arguments.

Return values
mixed

query()

Query for Orders matching specific criteria.

public query(array<string|int, mixed> $query_vars) : array<string|int, mixed>|object
Parameters
$query_vars : array<string|int, mixed>

query vars from a WC_Order_Query.

Tags
since
3.1.0
Return values
array<string|int, mixed>|object

release_held_coupons()

Release all coupons held by this order.

public release_held_coupons(WC_Order $order[, bool $save = true ]) : mixed
Parameters
$order : WC_Order

Current order object.

$save : bool = true

Whether to delete keys from DB right away. Could be useful to pass false if you are building a bulk request.

Return values
mixed

search_orders()

Search order data for a term and return ids.

public search_orders(string $term) : array<string|int, mixed>
Parameters
$term : string

Searched term.

Return values
array<string|int, mixed>of ids

set_coupon_held_keys()

Add/Update list of meta keys that are currently being used by this order to hold a coupon.

public set_coupon_held_keys(WC_Order $order, array<string|int, mixed> $held_keys, array<string|int, mixed> $held_keys_for_user) : mixed

This is used to figure out what all meta entries we should delete when order is cancelled/completed.

Parameters
$order : WC_Order

Order object.

$held_keys : array<string|int, mixed>

Array of coupon_code => meta_key.

$held_keys_for_user : array<string|int, mixed>

Array of coupon_code => meta_key for held coupon for user.

Return values
mixed

set_download_permissions_granted()

Stores information about whether permissions were generated yet.

public set_download_permissions_granted(WC_Order|int $order, bool $set) : mixed
Parameters
$order : WC_Order|int

Order ID or order object.

$set : bool

True or false.

Return values
mixed

set_recorded_coupon_usage_counts()

Stores information about whether coupon counts were updated.

public set_recorded_coupon_usage_counts(WC_Order|int $order, bool $set) : mixed
Parameters
$order : WC_Order|int

Order ID or order object.

$set : bool

True or false.

Return values
mixed

update_post_modified_data()

Change the modified date of the post to match the order's modified date if passed.

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

An array of slashed, sanitized, and processed post data.

$postarr : array<string|int, mixed>

An array of sanitized (and slashed) but otherwise unmodified post data.

Tags
hooked

wp_insert_post_data See function update_order_from_object.

Return values
array<string|int, mixed>Data with updated modified date.

exclude_internal_meta_keys()

Callback to remove unwanted meta data.

protected exclude_internal_meta_keys(object $meta) : bool
Parameters
$meta : object

Meta object to check if it should be excluded or not.

Return values
bool

get_data_for_lookup_table()

Get data to save to a lookup table.

protected get_data_for_lookup_table(int $id, string $table) : array<string|int, mixed>
Parameters
$id : int

ID of object to update.

$table : string

Lookup table name.

Tags
since
3.6.0
Return values
array<string|int, mixed>

get_db_info()

Table structure is slightly different between meta types, this function will return what we need to know.

protected get_db_info() : array<string|int, mixed>
Tags
since
3.0.0
Return values
array<string|int, mixed>Array elements: table, object_id_field, meta_id_field

get_post_status()

Get the status to save to the post object.

protected get_post_status(WC_order $order) : string

Plugins extending the order classes can override this to change the stored status/add prefixes etc.

Parameters
$order : WC_order

Order object.

Tags
since
3.6.0
Return values
string

get_primary_key_for_lookup_table()

Get primary key name for lookup table.

protected get_primary_key_for_lookup_table(string $table) : string
Parameters
$table : string

Lookup table name.

Tags
since
3.6.0
Return values
string

get_props_to_update()

Gets a list of props and meta keys that need updated based on change state or if they are present in the database or not.

protected get_props_to_update(WC_Data $object, array<string|int, mixed> $meta_key_to_props[, string $meta_type = 'post' ]) : array<string|int, mixed>
Parameters
$object : WC_Data

The WP_Data object (WC_Coupon for coupons, etc).

$meta_key_to_props : array<string|int, mixed>

A mapping of meta keys => prop names.

$meta_type : string = 'post'

The internal WP meta type (post, user, etc).

Return values
array<string|int, mixed>A mapping of meta keys => prop names, filtered by ones that should be updated.

get_search_stopwords()

Retrieve stopwords used when parsing search terms.

protected get_search_stopwords() : array<string|int, mixed>
Tags
since
3.4.0
Return values
array<string|int, mixed>Stopwords.

get_term_ids()

Get and store terms from a taxonomy.

protected get_term_ids(WC_Data|int $object, string $taxonomy) : array<string|int, mixed>
Parameters
$object : WC_Data|int

WC_Data object or object ID.

$taxonomy : string

Taxonomy name e.g. product_cat.

Tags
since
3.0.0
Return values
array<string|int, mixed>of terms

get_valid_search_terms()

Check if the terms are suitable for searching.

protected get_valid_search_terms(array<string|int, mixed> $terms) : array<string|int, mixed>

Uses an array of stopwords (terms) that are excluded from the separate term matching when searching for posts. The list of English stopwords is the approximate search engines list, and is translatable.

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

Terms to check.

Tags
since
3.4.0
Return values
array<string|int, mixed>Terms that are not stopwords.

get_wp_query_args()

Get valid WP_Query args from a WC_Order_Query's query variables.

protected get_wp_query_args(array<string|int, mixed> $query_vars) : array<string|int, mixed>
Parameters
$query_vars : array<string|int, mixed>

query vars from a WC_Order_Query.

Tags
since
3.1.0
Return values
array<string|int, mixed>

prefix_key()

Internal meta keys we don't want exposed as part of meta_data. This is in addition to all data props with _ prefix.

protected prefix_key(string $key) : string
Parameters
$key : string

Prefix to be added to meta keys.

Tags
since
2.6.0
Return values
string

prime_order_item_caches_for_orders()

Prime following caches: 1. item-$order_item_id For individual items.

protected prime_order_item_caches_for_orders(array<string|int, mixed> $order_ids, array<string|int, mixed> $query_vars) : mixed
  1. order-items-$order-id For fetching items associated with an order.
  2. order-item meta.
Parameters
$order_ids : array<string|int, mixed>

Order Ids to prime cache for.

$query_vars : array<string|int, mixed>

Query vars for the query.

Return values
mixed

string_to_timestamp()

Converts a WP post date string into a timestamp.

protected string_to_timestamp(string $time_string) : int|null
Parameters
$time_string : string

The WP post date string.

Tags
since
4.8.0
Return values
int|nullThe date string converted to a timestamp or null.

update_lookup_table()

Update a lookup table for an object.

protected update_lookup_table(int $id, string $table) : null
Parameters
$id : int

ID of object to update.

$table : string

Lookup table name.

Tags
since
3.6.0
Return values
null

update_or_delete_post_meta()

Update meta data in, or delete it from, the database.

protected update_or_delete_post_meta(WC_Data $object, string $meta_key, mixed $meta_value) : bool

Avoids storing meta when it's either an empty string or empty array. Other empty values such as numeric 0 and null should still be stored. Data-stores can force meta to exist using must_exist_meta_keys.

Note: WordPress get_metadata function returns an empty string when meta data does not exist.

Parameters
$object : WC_Data

The WP_Data object (WC_Coupon for coupons, etc).

$meta_key : string

Meta key to update.

$meta_value : mixed

Value to save.

Tags
since
3.6.0

Added to prevent empty meta being stored unless required.

Return values
boolTrue if updated/deleted.

compile_orders()

Compile order response and set caches as needed for order ids.

private compile_orders(array<string|int, mixed> $order_ids, array<string|int, mixed> $query_vars, WP_Query $query) : array<string|int, mixed>
Parameters
$order_ids : array<string|int, mixed>

List of order IDS to compile.

$query_vars : array<string|int, mixed>

Original query arguments.

$query : WP_Query

Query object.

Return values
array<string|int, mixed>Orders.

get_orders_generate_customer_meta_query()

Generate meta query for wc_get_orders.

private get_orders_generate_customer_meta_query(array<string|int, mixed> $values[, string $relation = 'or' ]) : array<string|int, mixed>
Parameters
$values : array<string|int, mixed>

List of customers ids or emails.

$relation : string = 'or'

'or' or 'and' relation used to build the WP meta_query.

Return values
array<string|int, mixed>

prime_raw_meta_cache_for_orders()

Prime cache for raw meta data for orders in bulk. Difference between this and WP built-in metadata is that this method also fetches `meta_id` field which we use and cache it.

private prime_raw_meta_cache_for_orders(array<string|int, mixed> $order_ids, array<string|int, mixed> $query_vars) : mixed
Parameters
$order_ids : array<string|int, mixed>

Order Ids to prime cache for.

$query_vars : array<string|int, mixed>

Query vars for the query.

Return values
mixed

prime_refund_caches_for_order()

Prime refund cache for orders.

private prime_refund_caches_for_order(array<string|int, mixed> $order_ids, array<string|int, mixed> $query_vars) : mixed
Parameters
$order_ids : array<string|int, mixed>

Order Ids to prime cache for.

$query_vars : array<string|int, mixed>

Query vars for the query.

Return values
mixed

set_order_props()

Set the properties of an object and log the first error found while doing so.

private set_order_props( &$order, array<string|int, mixed> $props) : mixed
Parameters
$order :

WC_Order $order Order object.

$props : array<string|int, mixed>

The properties to set.

Return values
mixed