WooCommerce Code Reference

WC_Product_Variable_Data_Store_CPT extends WC_Product_Data_Store_CPT
in package
implements WC_Object_Data_Store_Interface, WC_Product_Variable_Data_Store_Interface

WC Variable Product Data Store: Stored in CPT.

Tags
version
3.0.0

Interfaces, Classes and Traits

WC_Object_Data_Store_Interface
WC Data Store Interface
WC_Product_Variable_Data_Store_Interface
WC Product Variable Data Store Interface

Table of Contents

$extra_data_saved  : bool
If we have already saved our extra data, don't do automatic / default handling.
$internal_meta_keys  : array<string|int, mixed>
Data stored in meta keys, but not considered "meta" for an object.
$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.
$prices_array  : array<string|int, mixed>
Cached & hashed prices array for child variations.
$updated_props  : array<string|int, mixed>
Stores updated props.
add_meta()  : int
Add new piece of meta.
child_has_dimensions()  : bool
Does a child have dimensions set?
child_has_stock_status()  : bool
Does a child have a stock status?
child_has_weight()  : bool
Does a child have a weight set?
child_is_in_stock()  : bool
Is a child in stock?
create()  : mixed
Method to create a new product in the database.
create_all_product_variations()  : int
Creates all possible combinations of variations from the attributes, without creating duplicates.
delete()  : bool
Method to delete a product from the database.
delete_from_lookup_table()  : mixed
Delete lookup table data for an ID.
delete_meta()  : mixed
Deletes meta based on meta ID.
delete_variations()  : mixed
Delete variations of a product.
filter_raw_meta_data()  : mixed|void
Helper method to filter internal meta keys from all meta data rows for the object.
find_matching_product_variation()  : int
Find a matching (enabled) variation within a variable product.
get_ending_sales()  : array<string|int, mixed>
Returns an array of IDs of products that have sales which are due to end.
get_featured_product_ids()  : array<string|int, mixed>
Returns a list of product IDs ( id as key => parent as value) that are featured. Uses get_posts instead of wc_get_products since we want some extra meta queries and ALL products (posts_per_page = -1).
get_internal_meta_keys()  : array<string|int, mixed>
Return list of internal meta keys.
get_on_sale_products()  : array<string|int, mixed>
Returns an array of on sale products, as an array of objects with an ID and parent_id present. Example: $return[0]->id, $return[0]->parent_id.
get_product_id_by_sku()  : int
Return product ID based on SKU.
get_product_type()  : bool|string
Get the product type based on product ID.
get_products()  : array<string|int, mixed>|object
Returns an array of products.
get_related_products()  : array<string|int, mixed>
Return a list of related products (using data like categories and IDs).
get_related_products_query()  : array<string|int, mixed>
Builds the related posts query.
get_shipping_class_id_by_slug()  : int|false
Get shipping class ID by slug.
get_starting_sales()  : array<string|int, mixed>
Returns an array of IDs of products that have sales starting soon.
is_existing_sku()  : bool
Check if product sku is found for any other product IDs.
parse_date_for_wp_query()  : array<string|int, mixed>
Map a valid date query var to WP_Query arguments.
query()  : array<string|int, mixed>|object
Query for Products matching specific criteria.
read()  : mixed
Method to read a product from the database.
read_children()  : array<string|int, mixed>
Loads variation child IDs.
read_meta()  : array<string|int, mixed>
Returns an array of meta for an object.
read_price_data()  : array<string|int, mixed>
Get an array of all sale and regular prices from all variations. This is used for example when displaying the price range at variable product level or seeing if the variable product is on sale.
read_stock_quantity()  : mixed
Re-reads stock from the DB ignoring changes.
read_variation_attributes()  : array<string|int, mixed>
Loads an array of attributes used for variations, as well as their possible values.
reviews_allowed_query_where()  : string
Add ability to get products by 'reviews_allowed' in WC_Product_Query.
search_products()  : array<string|int, mixed>
Search product data for a term and return ids.
sort_all_product_variations()  : mixed
Make sure all variations have a sort order set so they can be reordered correctly.
sync_managed_variation_stock_status()  : mixed
Stock managed at the parent level - update children being managed by this product.
sync_price()  : mixed
Sync variable product prices with children.
sync_stock_status()  : mixed
Sync variable product stock status with children.
sync_variation_names()  : mixed
Syncs all variation names if the parent name is changed.
untrash_variations()  : mixed
Untrash variations.
update()  : mixed
Method to update a product in the database.
update_average_rating()  : mixed
Update a products average rating meta.
update_meta()  : mixed
Update meta.
update_product_sales()  : mixed
Update a product's sale count directly.
update_product_stock()  : int|float
Update a product's stock amount directly.
update_rating_counts()  : mixed
Update a products rating counts.
update_review_count()  : mixed
Update a products review count meta.
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_price_hash()  : string
Create unique cache key based on the tax location (affects displayed/cached prices), product version and active price filters.
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.
handle_updated_props()  : mixed
Handle updated meta props after updating meta data.
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.
read_attributes()  : mixed
Read attributes from post meta.
read_downloads()  : mixed
Read downloads from post meta.
read_extra_data()  : mixed
Read extra data associated with the product, like button text or product URL for external products.
read_product_data()  : mixed
Read product data.
read_visibility()  : mixed
Convert visibility terms to props.
set_product_stock()  : mixed
Update a product's stock amount directly in the database.
string_to_timestamp()  : int|null
Converts a WP post date string into a timestamp.
update_attributes()  : mixed
Update attributes which are a mix of terms and meta data.
update_downloads()  : bool
Update downloads.
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_post_meta()  : mixed
Helper method that updates all the post meta for a product based on it's settings in the WC_Product class.
update_terms()  : mixed
For all stored terms in all taxonomies, save them to the DB.
update_version_and_type()  : mixed
Make sure we store the product type and version (to track data changes).
update_visibility()  : mixed
Update visibility terms based on props.

Properties

$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

create_all_product_variations()

Creates all possible combinations of variations from the attributes, without creating duplicates.

public create_all_product_variations(WC_Product $product[, int $limit = -1 ][, array<string|int, mixed> $default_values = array() ][, array<string|int, mixed> $metadata = array() ]) : int
Parameters
$product : WC_Product

Variable product.

$limit : int = -1

Limit the number of created variations.

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

Key value pairs to set on created variations.

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

Key value pairs to set as meta data on created variations.

Tags
since
3.6.0
todo

Add to interface in 4.0.

Return values
intNumber of created variations.

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

delete_variations()

Delete variations of a product.

public delete_variations(int $product_id[, bool $force_delete = false ]) : mixed
Parameters
$product_id : int

Product ID.

$force_delete : bool = false

False to trash.

Tags
since
3.0.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

find_matching_product_variation()

Find a matching (enabled) variation within a variable product.

public find_matching_product_variation(WC_Product $product[, array<string|int, mixed> $match_attributes = array() ]) : int
Parameters
$product : WC_Product

Variable product.

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

Array of attributes we want to try to match.

Tags
since
3.0.0
Return values
intMatching variation ID or 0.

Returns a list of product IDs ( id as key => parent as value) that are featured. Uses get_posts instead of wc_get_products since we want some extra meta queries and ALL products (posts_per_page = -1).

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

get_on_sale_products()

Returns an array of on sale products, as an array of objects with an ID and parent_id present. Example: $return[0]->id, $return[0]->parent_id.

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

get_products()

Returns an array of products.

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

Args to pass to WC_Product_Query().

Tags
see
wc_get_products
Return values
array<string|int, mixed>|object

Return a list of related products (using data like categories and IDs).

public get_related_products(array<string|int, mixed> $cats_array, array<string|int, mixed> $tags_array, array<string|int, mixed> $exclude_ids, int $limit, int $product_id) : array<string|int, mixed>
Parameters
$cats_array : array<string|int, mixed>

List of categories IDs.

$tags_array : array<string|int, mixed>

List of tags IDs.

$exclude_ids : array<string|int, mixed>

Excluded IDs.

$limit : int

Limit of results.

$product_id : int

Product ID.

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

Builds the related posts query.

public get_related_products_query(array<string|int, mixed> $cats_array, array<string|int, mixed> $tags_array, array<string|int, mixed> $exclude_ids, int $limit) : array<string|int, mixed>
Parameters
$cats_array : array<string|int, mixed>

List of categories IDs.

$tags_array : array<string|int, mixed>

List of tags IDs.

$exclude_ids : array<string|int, mixed>

Excluded IDs.

$limit : int

Limit of results.

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

get_shipping_class_id_by_slug()

Get shipping class ID by slug.

public get_shipping_class_id_by_slug(string $slug) : int|false
Parameters
$slug : string

Product shipping class slug.

Tags
since
3.0.0
Return values
int|false

is_existing_sku()

Check if product sku is found for any other product IDs.

public is_existing_sku(int $product_id, string $sku) : bool
Parameters
$product_id : int

Product ID.

$sku : string

Will be slashed to work around https://core.trac.wordpress.org/ticket/27421.

Tags
since
3.0.0
Return values
bool

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

query()

Query for Products 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_Product_Query.

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

read_price_data()

Get an array of all sale and regular prices from all variations. This is used for example when displaying the price range at variable product level or seeing if the variable product is on sale.

public read_price_data(WC_Product &$product[, bool $for_display = false ]) : array<string|int, mixed>

Can be filtered by plugins which modify costs, but otherwise will include the raw meta costs unlike get_price() which runs costs through the woocommerce_get_price filter. This is to ensure modified prices are not cached, unless intended.

Parameters
$product : WC_Product

Product object.

$for_display : bool = false

If true, prices will be adapted for display based on the woocommerce_tax_display_shop setting (including or excluding taxes).

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

reviews_allowed_query_where()

Add ability to get products by 'reviews_allowed' in WC_Product_Query.

public reviews_allowed_query_where(string $where, WP_Query $wp_query) : string
Parameters
$where : string

Where clause.

$wp_query : WP_Query

WP_Query instance.

Tags
since
3.2.0
Return values
string

search_products()

Search product data for a term and return ids.

public search_products(string $term[, string $type = '' ][, bool $include_variations = false ][, bool $all_statuses = false ][, null|int $limit = null ][, null|array<string|int, mixed> $include = null ][, null|array<string|int, mixed> $exclude = null ]) : array<string|int, mixed>
Parameters
$term : string

Search term.

$type : string = ''

Type of product.

$include_variations : bool = false

Include variations in search or not.

$all_statuses : bool = false

Should we search all statuses or limit to published.

$limit : null|int = null

Limit returned results. @since 3.5.0.

$include : null|array<string|int, mixed> = null

Keep specific results. @since 3.6.0.

$exclude : null|array<string|int, mixed> = null

Discard specific results. @since 3.6.0.

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

sort_all_product_variations()

Make sure all variations have a sort order set so they can be reordered correctly.

public sort_all_product_variations(int $parent_id) : mixed
Parameters
$parent_id : int

Product ID.

Return values
mixed

sync_managed_variation_stock_status()

Stock managed at the parent level - update children being managed by this product.

public sync_managed_variation_stock_status(WC_Product &$product) : mixed

This sync function syncs downwards (from parent to child) when the variable product is saved.

Parameters
$product : WC_Product

Product object.

Tags
since
3.0.0
Return values
mixed

sync_variation_names()

Syncs all variation names if the parent name is changed.

public sync_variation_names(WC_Product &$product[, string $previous_name = '' ][, string $new_name = '' ]) : mixed
Parameters
$product : WC_Product

Product object.

$previous_name : string = ''

Variation previous name.

$new_name : string = ''

Variation new name.

Tags
since
3.0.0
Return values
mixed

update_product_sales()

Update a product's sale count directly.

public update_product_sales(int $product_id[, int|null $quantity = null ][, string $operation = 'set' ]) : mixed

Uses queries rather than update_post_meta so we can do this in one query for performance.

Parameters
$product_id : int

Product ID.

$quantity : int|null = null

Quantity.

$operation : string = 'set'

set, increase and decrease.

Tags
since
3.0.0

this supports set, increase and decrease.

Return values
mixed

update_product_stock()

Update a product's stock amount directly.

public update_product_stock(int $product_id_with_stock[, int|float|null $stock_quantity = null ][, string $operation = 'set' ]) : int|float

Uses queries rather than update_post_meta so we can do this in one query (to avoid stock issues). Ignores manage stock setting on the product and sets quantities directly in the db: post meta and lookup tables. Uses locking to update the quantity. If the lock is not acquired, change is lost.

Parameters
$product_id_with_stock : int

Product ID.

$stock_quantity : int|float|null = null

Stock quantity.

$operation : string = 'set'

Set, increase and decrease.

Tags
since
3.0.0

this supports set, increase and decrease.

Return values
int|floatNew stock level.

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_price_hash()

Create unique cache key based on the tax location (affects displayed/cached prices), product version and active price filters.

protected get_price_hash(WC_Product &$product[, bool $for_display = false ]) : string

DEVELOPERS should filter this hash if offering conditional pricing to keep it unique.

Parameters
$product : WC_Product

Product object.

$for_display : bool = false

If taxes should be calculated or not.

Tags
since
3.0.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_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.

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

set_product_stock()

Update a product's stock amount directly in the database.

protected set_product_stock(int $product_id_with_stock, int|float|null $stock_quantity) : mixed

Updates both post meta and lookup tables. Ignores manage stock setting on the product.

Parameters
$product_id_with_stock : int

Product ID.

$stock_quantity : int|float|null

Stock quantity.

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.

update_post_meta()

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

protected update_post_meta(WC_Product &$product[, bool $force = false ]) : mixed
Parameters
$product : WC_Product

Product object.

$force : bool = false

Force update. Used during create.

Tags
since
3.0.0
Return values
mixed