WooCommerce Code Reference

WC_Coupon_Data_Store_CPT extends WC_Data_Store_WP
in package
implements WC_Coupon_Data_Store_Interface, WC_Object_Data_Store_Interface

WC Coupon Data Store: Custom Post Type.

Tags
version
3.0.0

Interfaces, Classes and Traits

WC_Coupon_Data_Store_Interface
Coupon Data Store Interface
WC_Object_Data_Store_Interface
Object Data Store Interface

Table of Contents

$internal_meta_keys  : array
Data stored in meta keys, but not considered "meta" for a coupon.
$meta_type  : string
Internal meta type used to store coupon data.
$must_exist_meta_keys  : array
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.
$updated_props  : array
The updated coupon properties
add_meta()  : int
Add new piece of meta.
check_and_hold_coupon()  : bool|int|string|null
Check and records coupon usage tentatively for short period of time so that counts validation is correct. Returns early if there is no limit defined for the coupon.
check_and_hold_coupon_for_user()  : null|false|int
Check and records coupon usage tentatively for passed user aliases for short period of time so that counts validation is correct. Returns early if there is no limit per user for the coupon.
create()  : mixed
Method to create a new coupon in the database.
decrease_usage_count()  : int
Decrease usage count for current coupon.
delete()  : bool
Deletes a coupon from the database.
delete_from_lookup_table()  : mixed
Delete lookup table data for an ID.
delete_meta()  : mixed
Deletes meta based on meta ID.
get_code_by_id()  : string
Return a coupon code for a specific ID.
get_ids_by_code()  : array
Return an array of IDs for for a specific coupon code.
get_internal_meta_keys()  : array
Return list of internal meta keys.
get_tentative_usage_count()  : int
Returns tentative usage count for coupon.
get_tentative_usages_for_user()  : string|null
Get tentative coupon usages for user.
get_usage_by_email()  : int
Get the number of uses for a coupon by email address
get_usage_by_user_id()  : int
Get the number of uses for a coupon by user ID.
increase_usage_count()  : int
Increase usage count for current coupon.
parse_date_for_wp_query()  : array
Map a valid date query var to WP_Query arguments.
read()  : mixed
Method to read a coupon.
read_meta()  : array
Returns an array of meta for an object.
update()  : mixed
Updates a coupon in the database.
update_meta()  : mixed
Update meta.
exclude_internal_meta_keys()  : bool
Callback to remove unwanted meta data.
get_data_for_lookup_table()  : array
Get data to save to a lookup table.
get_db_info()  : array
Table structure is slightly different between meta types, this function will return what we need to know.
get_primary_key_for_lookup_table()  : string
Get primary key name for lookup table.
get_props_to_update()  : array
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
Retrieve stopwords used when parsing search terms.
get_term_ids()  : array
Get and store terms from a taxonomy.
get_valid_search_terms()  : array
Check if the terms are suitable for searching.
get_wp_query_args()  : array
Get valid WP_Query args from a WC_Object_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.
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.
add_coupon_used_by()  : mixed
Helper function to add a `_used_by` record to track coupons used by the user.
get_tentative_held_time()  : int
Get held time for resources before cancelling the order. Use 60 minutes as sane default.
get_tentative_usage_query()  : string
Generate query to calculate tentative usages for the coupon.
get_tentative_usage_query_for_user()  : string
Generate query to calculate tentative usages for the coupon by the user.
update_post_meta()  : mixed
Helper method that updates all the post meta for a coupon based on it's settings in the WC_Coupon class.
update_usage_count_meta()  : int
Increase or decrease the usage count for a coupon by 1.

Properties

$internal_meta_keys

Data stored in meta keys, but not considered "meta" for a coupon.

protected array $internal_meta_keys = array('discount_type', 'coupon_amount', 'expiry_date', 'date_expires', 'usage_count', 'individual_use', 'product_ids', 'exclude_product_ids', 'usage_limit', 'usage_limit_per_user', 'limit_usage_to_x_items', 'free_shipping', 'product_categories', 'exclude_product_categories', 'exclude_sale_items', 'minimum_amount', 'maximum_amount', 'customer_email', '_used_by', '_edit_lock', '_edit_last')
Tags
since
3.0.0

$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

check_and_hold_coupon()

Check and records coupon usage tentatively for short period of time so that counts validation is correct. Returns early if there is no limit defined for the coupon.

public check_and_hold_coupon(WC_Coupon $coupon) : bool|int|string|null
Parameters
$coupon : WC_Coupon

Coupon object.

Return values
bool|int|string|nullReturns meta key if coupon was held, null if returned early.

check_and_hold_coupon_for_user()

Check and records coupon usage tentatively for passed user aliases for short period of time so that counts validation is correct. Returns early if there is no limit per user for the coupon.

public check_and_hold_coupon_for_user(WC_Coupon $coupon, array $user_aliases, string $user_alias) : null|false|int
Parameters
$coupon : WC_Coupon

Coupon object.

$user_aliases : array

Emails or Ids to check for user.

$user_alias : string

Email/ID to use as used_by value.

Return values
null|false|int

decrease_usage_count()

Decrease usage count for current coupon.

public decrease_usage_count(WC_Coupon &$coupon[, string $used_by = '' ]) : int
Parameters
$coupon : WC_Coupon

Coupon object.

$used_by : string = ''

Either user ID or billing email.

Tags
since
3.0.0
Return values
intNew usage count.

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

get_ids_by_code()

Return an array of IDs for for a specific coupon code.

public get_ids_by_code(string $code) : array

Can return multiple to check for existence.

Parameters
$code : string

Coupon code.

Tags
since
3.0.0
Return values
arrayArray of IDs.

get_tentative_usages_for_user()

Get tentative coupon usages for user.

public get_tentative_usages_for_user(int $coupon_id, array $user_aliases) : string|null
Parameters
$coupon_id : int

Coupon ID.

$user_aliases : array

Array of user aliases to check tentative usages for.

Return values
string|null

increase_usage_count()

Increase usage count for current coupon.

public increase_usage_count(WC_Coupon &$coupon[, string $used_by = '' ][, WC_Order $order = null ]) : int
Parameters
$coupon : WC_Coupon

Coupon object.

$used_by : string = ''

Either user ID or billing email.

$order : WC_Order = null

(Optional) If passed, clears the hold record associated with order.

Tags
since
3.0.0
Return values
intNew usage count.

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 $wp_query_args = array() ]) : array

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 = array()

WP_Query args.

Tags
since
3.2.0
Return values
arrayModified $wp_query_args

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
Parameters
$id : int

ID of object to update.

$table : string

Lookup table name.

Tags
since
3.6.0
Return values
array

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
Tags
since
3.0.0
Return values
arrayArray elements: table, object_id_field, meta_id_field

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 $meta_key_to_props[, string $meta_type = 'post' ]) : array
Parameters
$object : WC_Data

The WP_Data object (WC_Coupon for coupons, etc).

$meta_key_to_props : array

A mapping of meta keys => prop names.

$meta_type : string = 'post'

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

Return values
arrayA mapping of meta keys => prop names, filtered by ones that should be updated.

get_term_ids()

Get and store terms from a taxonomy.

protected get_term_ids(WC_Data|int $object, string $taxonomy) : array
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
arrayof terms

get_valid_search_terms()

Check if the terms are suitable for searching.

protected get_valid_search_terms(array $terms) : array

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

Terms to check.

Tags
since
3.4.0
Return values
arrayTerms that are not stopwords.

get_wp_query_args()

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

protected get_wp_query_args(array $query_vars) : array
Parameters
$query_vars : array

query vars from a WC_Object_Query.

Tags
since
3.1.0
Return values
array

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

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.

add_coupon_used_by()

Helper function to add a `_used_by` record to track coupons used by the user.

private add_coupon_used_by(WC_Coupon $coupon, string $used_by, string $coupon_held_key) : mixed
Parameters
$coupon : WC_Coupon

Coupon object.

$used_by : string

Either user ID or billing email.

$coupon_held_key : string

(Optional) Update meta key to _used_by instead of adding a new record.

Return values
mixed

get_tentative_held_time()

Get held time for resources before cancelling the order. Use 60 minutes as sane default.

private get_tentative_held_time() : int

Note that the filter woocommerce_coupon_hold_minutes only support minutes because it's getting used elsewhere as well, however this function returns in seconds.

Return values
int

get_tentative_usage_query()

Generate query to calculate tentative usages for the coupon.

private get_tentative_usage_query(int $coupon_id) : string
Parameters
$coupon_id : int

Coupon ID to get tentative usage query for.

Return values
stringQuery for tentative usages.

get_tentative_usage_query_for_user()

Generate query to calculate tentative usages for the coupon by the user.

private get_tentative_usage_query_for_user(int $coupon_id, array $user_aliases) : string
Parameters
$coupon_id : int

Coupon ID.

$user_aliases : array

List of user aliases to check for usages.

Return values
stringTentative usages query.

update_usage_count_meta()

Increase or decrease the usage count for a coupon by 1.

private update_usage_count_meta(WC_Coupon &$coupon[, string $operation = 'increase' ]) : int
Parameters
$coupon : WC_Coupon

Coupon object.

$operation : string = 'increase'

'increase' or 'decrease'.

Tags
since
3.0.0
Return values
intNew usage count