WooCommerce Code Reference

WC_Coupon_Data_Store_CPT extends WC_Data_Store_WP
in package

WooCommerce

DataStores

implements WC_Coupon_Data_Store_Interface, WC_Object_Data_Store_Interface

WC Coupon Data Store: Custom Post Type.

Interfaces, Classes and Traits

WC_Coupon_Data_Store_Interface: WC Coupon Data Store Interface
WC_Object_Data_Store_Interface: WC Data Store Interface

$internal_meta_keys : array<string|int, mixed>: 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<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.
$updated_props : array<string|int, mixed>: 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.
filter_raw_meta_data() : mixed|void: Helper method to filter internal meta keys from all meta data rows for the object.
get_code_by_id() : string: Return a coupon code for a specific ID.
get_ids_by_code() : array<string|int, mixed>: Return an array of IDs for for a specific coupon code.
get_internal_meta_keys() : array<string|int, mixed>: 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<string|int, mixed>: Map a valid date query var to WP_Query arguments.
read() : mixed: Method to read a coupon.
read_meta() : array<string|int, mixed>: 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<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_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_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.
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.
add_coupon_used_by() : mixed: Helper function to add a `_used_by` record to track coupons used by the user.
get_coupon_meta_as_array() : array<string|int, mixed>: Get a metadata value that is stored as either a string consisting of a comma-separated list of values or as a serialized array.
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.
refresh_coupon_data() : void: This function clears coupon data from the WP cache after certain operations which, for performance reasons, are done via SQL queries.
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.

$internal_meta_keys

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


    protected
        array<string|int, mixed>
    $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')

$meta_type

Internal meta type used to store coupon data.


    protected
        string
    $meta_type
     = 'post'

$must_exist_meta_keys

Meta data which should exist in the DB, even if empty.


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

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

$updated_props

The updated coupon properties


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

add_meta()

Add new piece of meta.


    public
                add_meta(WC_Data &$object, stdClass $meta) : int

Parameters

$object : WC_Data: WC_Data object.
$meta : stdClass: (containing ->key and ->value).

Return values

int — meta ID

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|null — Returns 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<string|int, mixed> $user_aliases, string $user_alias) : null|false|int

Parameters

$coupon : WC_Coupon: Coupon object.
$user_aliases : array<string|int, mixed>: Emails or Ids to check for user.
$user_alias : string: Email/ID to use as used_by value.

Return values

null|false|int —

create()

Method to create a new coupon in the database.


    public
                create(WC_Coupon &$coupon) : mixed

Parameters

$coupon : WC_Coupon: Coupon object.

Return values

mixed —

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.

Return values

int — New usage count.

delete()

Deletes a coupon from the database.


    public
                delete(WC_Coupon &$coupon[, array<string|int, mixed> $args = array() ]) : bool

Parameters

$coupon : WC_Coupon: Coupon object.
$args : array<string|int, mixed> = array(): Array of args to pass to the delete method.

Return values

bool — result

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.

Return values

mixed —

delete_meta()

Deletes meta based on meta ID.


    public
                delete_meta(WC_Data &$object, stdClass $meta) : mixed

Parameters

$object : WC_Data: WC_Data object.
$meta : stdClass: (containing at least ->id).

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.

Return values

mixed|void —

get_code_by_id()

Return a coupon code for a specific ID.


    public
                get_code_by_id(int $id) : string

Parameters

$id : int: Coupon ID.

Return values

string — Coupon Code

get_ids_by_code()

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


    public
                get_ids_by_code(string $code) : array<string|int, mixed>

Can return multiple to check for existence.

Parameters

$code : string: Coupon code.

Return values

array<string|int, mixed> — Array of IDs.

get_internal_meta_keys()

Return list of internal meta keys.


    public
                get_internal_meta_keys() : array<string|int, mixed>

Return values

array<string|int, mixed> —

get_tentative_usage_count()

Returns tentative usage count for coupon.


    public
                get_tentative_usage_count(int $coupon_id) : int

Parameters

$coupon_id : int: Coupon ID.

Return values

int — Tentative usage count.

get_tentative_usages_for_user()

Get tentative coupon usages for user.


    public
                get_tentative_usages_for_user(int $coupon_id, array<string|int, mixed> $user_aliases) : string|null

Parameters

$coupon_id : int: Coupon ID.
$user_aliases : array<string|int, mixed>: Array of user aliases to check tentative usages for.

Return values

string|null —

get_usage_by_email()

Get the number of uses for a coupon by email address


    public
                get_usage_by_email(WC_Coupon &$coupon, string $email) : int

Parameters

$coupon : WC_Coupon: Coupon object.
$email : string: Email address.

Return values

int —

get_usage_by_user_id()

Get the number of uses for a coupon by user ID.


    public
                get_usage_by_user_id(WC_Coupon &$coupon, int $user_id) : int

Parameters

$coupon : WC_Coupon: Coupon object.
$user_id : int: User ID.

Return values

int —

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.

Return values

int — New 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<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.

Return values

array<string|int, mixed> — Modified $wp_query_args

read()

Method to read a coupon.


    public
                read(WC_Coupon &$coupon) : mixed

Parameters

$coupon : WC_Coupon: Coupon object.

Return values

mixed —

read_meta()

Returns an array of meta for an object.


    public
                read_meta(WC_Data &$object) : array<string|int, mixed>

Parameters

$object : WC_Data: WC_Data object.

Return values

array<string|int, mixed> —

update()

Updates a coupon in the database.


    public
                update(WC_Coupon &$coupon) : mixed

Parameters

$coupon : WC_Coupon: Coupon object.

Return values

mixed —

update_meta()

Update meta.


    public
                update_meta(WC_Data &$object, stdClass $meta) : mixed

Parameters

$object : WC_Data: WC_Data object.
$meta : stdClass: (containing ->id, ->key and ->value).

Return values

mixed —

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.

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>

Return values

array<string|int, mixed> — Array 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.

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>

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.

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.

Return values

array<string|int, mixed> — Terms 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<string|int, mixed> $query_vars) : array<string|int, mixed>

Parameters

$query_vars : array<string|int, mixed>: query vars from a WC_Object_Query.

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.

Return values

string —

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.

Return values

int|null — The 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.

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.

Return values

bool — True 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_coupon_meta_as_array()

Get a metadata value that is stored as either a string consisting of a comma-separated list of values or as a serialized array.


    private
                get_coupon_meta_as_array(int $coupon_id, string $meta_key) : array<string|int, mixed>

WooCommerce always stores the coupon product ids as a comma-separated string, but it seems that some plugins mistakenly change these to an array.

Parameters

$coupon_id : int: The coupon id.
$meta_key : string: The meta key to get.

Return values

array<string|int, mixed> — The metadata value as an array, with empty values removed.

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

string — Query 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<string|int, mixed> $user_aliases) : string

Parameters

$coupon_id : int: Coupon ID.
$user_aliases : array<string|int, mixed>: List of user aliases to check for usages.

Return values

string — Tentative usages query.

refresh_coupon_data()

This function clears coupon data from the WP cache after certain operations which, for performance reasons, are done via SQL queries.


    private
                refresh_coupon_data(WC_Coupon &$coupon) : void

Parameters

$coupon : WC_Coupon: The coupon object.

Return values

void —

update_post_meta()

Helper method that updates all the post meta for a coupon based on it's settings in the WC_Coupon class.


    private
                update_post_meta(WC_Coupon &$coupon) : mixed

Parameters

$coupon : WC_Coupon: Coupon object.

Return values

mixed —

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'.

Return values

int — New usage count

WooCommerce Code Reference

WC_Coupon_Data_Store_CPT extends WC_Data_Store_WP in package WooCommerce DataStores implements WC_Coupon_Data_Store_Interface, WC_Object_Data_Store_Interface

Tags

Interfaces, Classes and Traits

Table of Contents

Properties

$internal_meta_keys

Tags

$meta_type

Tags

$must_exist_meta_keys

Tags

$object_id_field_for_meta

$updated_props

Tags

Methods

add_meta()

Parameters

Tags

Return values

check_and_hold_coupon()

Parameters

Return values

check_and_hold_coupon_for_user()

Parameters

Return values

create()

Parameters

Tags

Return values

decrease_usage_count()

Parameters

Tags

Return values

delete()

Parameters

Tags

Return values

delete_from_lookup_table()

Parameters

Tags

Return values

delete_meta()

Parameters

Tags

Return values

filter_raw_meta_data()

Parameters

Tags

Return values

get_code_by_id()

Parameters

Tags

Return values

get_ids_by_code()

Parameters

Tags

Return values

get_internal_meta_keys()

Tags

Return values

get_tentative_usage_count()

Parameters

Return values

get_tentative_usages_for_user()

Parameters

Return values

get_usage_by_email()

Parameters

Tags

Return values

get_usage_by_user_id()

Parameters

Tags

Return values

increase_usage_count()

Parameters

Tags

Return values

parse_date_for_wp_query()

WC_Coupon_Data_Store_CPT extends WC_Data_Store_WP
in package

WooCommerce

DataStores

implements WC_Coupon_Data_Store_Interface, WC_Object_Data_Store_Interface