WooCommerce Code Reference

DataStore extends WC_Data_Store_WP
in package
implements WC_Object_Data_Store_Interface

WC Admin Note Data Store (Custom Tables)

Interfaces, Classes and Traits

WC_Object_Data_Store_Interface
WC Data Store Interface

Table of Contents

WC_ADMIN_NOTE_OPER_GLOBAL  = 'global'
$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.
add_meta()  : int
Add new piece of meta.
create()  : mixed
Method to create a new note in the database.
delete()  : bool
Deletes a note 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_internal_meta_keys()  : array<string|int, mixed>
Return list of internal meta keys.
get_note_ids_by_type()  : array<string|int, mixed>
Find the ids of all notes with a given type.
get_notes()  : array<string|int, mixed>
Return an ordered list of notes.
get_notes_count()  : string
Return a count of notes.
get_notes_where_clauses()  : string
Return where clauses for getting notes by status and type. For use in both the count and listing queries.
get_notes_with_name()  : array<string|int, mixed>
Find all the notes with a given name.
lookup_notes()  : array<string|int, mixed>
Return an ordered list of notes, without paging or applying the 'woocommerce_note_where_clauses' filter.
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 note.
read_meta()  : array<string|int, mixed>
Returns an array of meta for an object.
update()  : mixed
Updates a note in the database.
update_meta()  : mixed
Update meta.
args_to_where_clauses()  : string
Return where clauses for notes queries without applying woocommerce_note_where_clauses filter.
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.
get_escaped_arguments_array_by_key()  : array<string|int, mixed>
Parses the query arguments passed in as arrays and escapes the values.
read_actions()  : mixed
Read actions from the database.
save_actions()  : bool|void
Save actions to the database.

Constants

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

Method to create a new note in the database.

public create(Note &$note) : mixed
Parameters
$note : Note

Admin note.

Return values
mixed

delete()

Deletes a note from the database.

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

Admin note.

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

Array of args to pass to the delete method (not used).

Return values
boolresult

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

Find the ids of all notes with a given type.

public get_note_ids_by_type(string $note_type) : array<string|int, mixed>
Parameters
$note_type : string

Type to search for.

Return values
array<string|int, mixed>An array of matching note ids.

get_notes()

Return an ordered list of notes.

public get_notes([array<string|int, mixed> $args = array() ][, string $context = self::WC_ADMIN_NOTE_OPER_GLOBAL ]) : array<string|int, mixed>
Parameters
$args : array<string|int, mixed> = array()

Query arguments.

$context : string = self::WC_ADMIN_NOTE_OPER_GLOBAL

Optional argument that the woocommerce_note_where_clauses filter can use to determine whether to apply extra conditions. Extensions should define their own contexts and use them to avoid adding to notes where clauses when not needed.

Return values
array<string|int, mixed>An array of objects containing a note id.

get_notes_count()

Return a count of notes.

public get_notes_count([string $type = array() ][, string $status = array() ][, string $context = self::WC_ADMIN_NOTE_OPER_GLOBAL ]) : string
Parameters
$type : string = array()

Comma separated list of note types.

$status : string = array()

Comma separated list of statuses.

$context : string = self::WC_ADMIN_NOTE_OPER_GLOBAL

Optional argument that the woocommerce_note_where_clauses filter can use to determine whether to apply extra conditions. Extensions should define their own contexts and use them to avoid adding to notes where clauses when not needed.

Return values
stringCount of objects with given type, status and context.

get_notes_where_clauses()

Return where clauses for getting notes by status and type. For use in both the count and listing queries.

public get_notes_where_clauses([array<string|int, mixed> $args = array() ][, string $context = self::WC_ADMIN_NOTE_OPER_GLOBAL ]) : string

Applies woocommerce_note_where_clauses filter.

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

Array of args to pass.

$context : string = self::WC_ADMIN_NOTE_OPER_GLOBAL

Optional argument that the woocommerce_note_where_clauses filter can use to determine whether to apply extra conditions. Extensions should define their own contexts and use them to avoid adding to notes where clauses when not needed.

Tags
uses
args_to_where_clauses
Return values
stringWhere clauses for the query.

get_notes_with_name()

Find all the notes with a given name.

public get_notes_with_name(string $name) : array<string|int, mixed>
Parameters
$name : string

Name to search for.

Return values
array<string|int, mixed>An array of matching note ids.

lookup_notes()

Return an ordered list of notes, without paging or applying the 'woocommerce_note_where_clauses' filter.

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

INTERNAL: This method is not intended to be used by external code, and may change without notice.

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

Query arguments.

Return values
array<string|int, mixed>An array of database records.

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

read()

Method to read a note.

public read(Note &$note) : mixed
Parameters
$note : Note

Admin note.

Tags
throws
Exception

Throws exception when invalid data is found.

Return values
mixed

args_to_where_clauses()

Return where clauses for notes queries without applying woocommerce_note_where_clauses filter.

protected args_to_where_clauses([array<string|int, mixed> $args = array() ]) : string

INTERNAL: This method is not intended to be used by external code, and may change without notice.

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

Array of arguments for query conditionals.

Return values
stringWhere clauses.

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_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

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.

get_escaped_arguments_array_by_key()

Parses the query arguments passed in as arrays and escapes the values.

private get_escaped_arguments_array_by_key([array<string|int, mixed> $args = array() ][, string $key = '' ][, array<string|int, mixed>|null $allowed_types = null ]) : array<string|int, mixed>
Parameters
$args : array<string|int, mixed> = array()

the query arguments.

$key : string = ''

the key of the specific argument.

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

optional allowed_types if only a specific set is allowed.

Return values
array<string|int, mixed>the escaped array of argument values.

read_actions()

Read actions from the database.

private read_actions(Note &$note) : mixed
Parameters
$note : Note

Admin note.

Return values
mixed

save_actions()

Save actions to the database.

private save_actions(Note &$note) : bool|void

This function clears old actions, then re-inserts new if any changes are found.

Parameters
$note : Note

Note object.

Return values
bool|void