WooCommerce Code Reference

DataStore extends WC_Data_Store_WP
in package

WooCommerce

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

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.

WC_ADMIN_NOTE_OPER_GLOBAL


    public
    mixed
    WC_ADMIN_NOTE_OPER_GLOBAL
    = 'global'

$internal_meta_keys

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


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

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

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

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

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

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

string — Count 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.

Return values

string — Where 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.

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.

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 note in the database.


    public
                update(Note &$note) : mixed

Parameters

$note : Note: Admin note.

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 —

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

string — Where 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.

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.

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 —

WooCommerce Code Reference

DataStore extends WC_Data_Store_WP in package WooCommerce implements WC_Object_Data_Store_Interface

Interfaces, Classes and Traits

Table of Contents

Constants

WC_ADMIN_NOTE_OPER_GLOBAL

Properties

$internal_meta_keys

Tags

$meta_type

$must_exist_meta_keys

Tags

$object_id_field_for_meta

Methods

add_meta()

Parameters

Tags

Return values

create()

Parameters

Return values

delete()

Parameters

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

Tags

Return values

get_note_ids_by_type()

Parameters

Return values

get_notes()

Parameters

Return values

get_notes_count()

Parameters

Return values

get_notes_where_clauses()

Parameters

Tags

Return values

get_notes_with_name()

Parameters

Return values

lookup_notes()

Parameters

Return values

parse_date_for_wp_query()

Parameters

Tags

Return values

read()

Parameters

Tags

Return values

read_meta()

Parameters

Tags

Return values

update()

Parameters

Return values

update_meta()

Parameters

Tags

Return values

args_to_where_clauses()

Parameters

Return values

DataStore extends WC_Data_Store_WP
in package

WooCommerce

implements WC_Object_Data_Store_Interface