WooCommerce Code Reference

DataStore extends DataStore
in package

WooCommerce

implements DataStoreInterface

API\Reports\Customers\Stats\DataStore.

Interfaces, Classes and Traits

DataStoreInterface: WooCommerce Reports data store interface.

$cache_group : string: Cache group for the reports.
$cache_key : string: Cache identifier.
$cache_timeout : int: Time out for the cache.
$column_types : array<string|int, mixed>: Mapping columns to data type to return correct response types.
$context : string: Data store context used to pass to filters.
$date_column_name : string: Date field name.
$debug_cache : bool: Include debugging information in the returned data when true.
$debug_cache_data : array<string|int, mixed>: Debugging information to include in the returned data.
$force_cache_refresh : bool: Refresh the cache for the current query when true.
$interval_query : SqlQuery: Intervals query object.
$report_columns : array<string|int, mixed>: SQL columns to select in the db query.
$subquery : SqlQuery: Subquery object for query nesting.
$table_name : string: Table used as a data store for this report.
$total_query : SqlQuery: Totals query object.
$limit_parameters : array<string|int, mixed>: Query limit parameters.
$order : string: Order property, used in the cmp function.
$order_by : string: Order by property, used in the cmp function.
$sql_clauses : array<string|int, mixed>: List of SQL clauses.
$sql_filters : array<string|int, mixed>: SQL clause merge filters.
__construct() : mixed: Constructor.
add_debug_cache_to_envelope() : array<string|int, mixed>: Add cache debugging information to an enveloped API response.
add_sql_clause() : mixed: Add a SQL clause to be included when get_data is called.
clear_all_clauses() : mixed: Reinitialize the clause array.
delete_customer() : mixed: Delete a customer lookup row.
delete_customer_by_user_id() : mixed: Delete a customer lookup row by WordPress User ID.
get_customer_id_by_email() : false|int: Retrieve a customer ID by email address, regardless of user registration status.
get_customer_id_by_user_id() : false|int: Retrieve a registered customer row id by user_id.
get_customer_order_data_and_format() : array<string|int, mixed>: Returns a data object and format object of the customers data coming from the order.
get_data() : stdClass|WP_Error: Get the data based on args.
get_db_table_name() : mixed: Get table name from database class.
get_default_query_vars() : array<string|int, mixed>: Get the default query arguments to be used by get_data().
get_existing_customer_id_from_order() : int|bool: Returns an existing customer ID for an order if one exists.
get_guest_id_by_email() : false|array<string|int, mixed>: Retrieve a guest ID (when user_id is null) by email.
get_last_order() : object: Retrieve the last order made by a customer.
get_noncached_data() : stdClass|WP_Error: Returns the report data based on normalized parameters.
get_oldest_orders() : array<string|int, mixed>: Retrieve the oldest orders made by a customer.
get_or_create_customer_from_order() : int|bool: Get or create a customer from a given order.
get_order_count() : int|null: Retrieve the amount of orders made by a customer.
get_query_statement() : string: Get the full SQL statement.
init() : mixed: Set up all the hooks for maintaining and populating table data.
merge_guest_customer_on_delayed_account_creation() : void: When a customer registers via delayed account creation (order confirmation page), merge the existing guest lookup row instead of creating a duplicate.
sync_on_order_delete() : mixed: Sync customers data after an order was deleted.
sync_order_customer() : true|-1: Sync customers data after an order was updated.
update_registered_customer() : int|bool|null: Update the database with customer data.
update_registered_customer_via_last_active() : mixed: Update the database if the "last active" meta value was changed.
add_intervals_sql_params() : mixed: Fills FROM and WHERE clauses of SQL request for 'Intervals' section of data response based on user supplied parameters.
add_order_by_clause() : string: Add order by SQL clause if included in query.
add_order_by_sql_params() : mixed: Fills ORDER BY clause of SQL request based on user supplied parameters.
add_order_status_clause() : mixed: Add order status SQL clauses if included in query.
add_orderby_order_clause() : mixed: Add order by order SQL clause.
add_sql_query_params() : mixed: Updates the database query with parameters used for Customers report: categories and order status.
add_time_period_sql_params() : mixed: Fills WHERE clause of SQL request with date-related constraints.
assign_report_columns() : mixed: Assign report columns once full table name has been assigned.
build_location_filter_clause() : string: Build location filter SQL clause for includes or excludes.
cast_numbers() : array<string|int, mixed>|WP_Error: Casts strings returned from the database to appropriate data types for output.
clear_sql_clause() : mixed: Clear SQL clauses by type.
create_interval_subtotals() : mixed: Change structure of intervals to form a correct response.
expected_intervals_on_page() : float|int: Returns expected number of items on the page in case of date ordering.
fill_in_missing_intervals() : stdClass: Fills in interval gaps from DB with 0-filled objects.
format_join_selections() : string: Returns a comma separated list of the field names prepared to be used for a selection after a join with `default_results`.
get_attribute_subqueries() : array<string|int, mixed>: Returns product attribute subquery elements used in JOIN and WHERE clauses, based on query arguments from the user.
get_cache_key() : string: Returns string to be used as cache key for the data.
get_cached_data() : mixed: Wrapper around Cache::get().
get_countable_customer_order_predicate() : string: Get the SQL predicate that includes orders while excluding refund rows.
get_customer_subquery() : string: Returns customer subquery to be used in WHERE SQL query, based on query arguments from the user.
get_excluded_coupons() : string: Returns comma separated ids of excluded coupons, based on query arguments from the user.
get_excluded_orders() : string: Returns comma separated ids of excluded orders, based on query arguments from the user.
get_excluded_products() : string: Returns comma separated ids of excluded products, based on query arguments from the user.
get_excluded_products_array() : array<string|int, mixed>: Returns an array of ids of disallowed products, based on query arguments from the user.
get_excluded_report_order_statuses() : array<string|int, mixed>: Get the excluded order statuses used when calculating reports.
get_excluded_users() : string: Returns comma separated ids of excluded users, based on query arguments from the user.
get_excluded_variations() : string: Returns comma separated ids of excluded variations, based on query arguments from the user.
get_fields() : array<string|int, mixed>: Returns a comma separated list of the fields in the `query_args`, if there aren't, returns `report_columns` keys.
get_filtered_ids() : string: Returns filtered comma separated ids, based on query arguments from the user.
get_ids_table() : string: Generates a virtual table given a list of IDs.
get_included_categories() : string: Returns comma separated ids of included categories, based on query arguments from the user.
get_included_coupons() : string: Returns comma separated ids of included coupons, based on query arguments from the user.
get_included_orders() : string: Returns comma separated ids of included orders, based on query arguments from the user.
get_included_products() : string: Returns comma separated ids of allowed products, based on query arguments from the user.
get_included_products_array() : array<string|int, mixed>: Returns an array of ids of allowed products, based on query arguments from the user.
get_included_users() : string: Returns comma separated ids of included users, based on query arguments from the user.
get_included_variations() : string: Returns comma separated ids of allowed variations, based on query arguments from the user.
get_limit_params() : array<string|int, mixed>: Fills LIMIT parameters of SQL request based on user supplied parameters.
get_limit_sql_params() : array<string|int, mixed>: Fills LIMIT clause of SQL request based on user supplied parameters.
get_match_operator() : string: Returns logic operator for WHERE subclause based on 'match' query argument.
get_object_where_filter() : string: Get WHERE filter by object ids subquery.
get_products_by_cat_ids() : array<string|int, mixed>|stdClass: Returns an array of products belonging to given categories.
get_refund_subquery() : array<string|int, mixed>: Get join and where clauses for refunds based on user supplied parameters.
get_sql_clause() : string: Get SQL clause by type.
get_status_subquery() : string: Returns order status subquery to be used in WHERE SQL query, based on query arguments from the user.
initialize_queries() : mixed: Initialize query objects.
intervals_missing() : bool: Returns true if there are any intervals that need to be filled in the response.
is_valid_customer() : bool: Check if a user ID is a valid customer or other user role with past orders.
normalize_order_by() : string: Normalizes order_by clause to match to SQL query.
normalize_order_by_clause() : string: Maps ordering specified by the user to columns in the database/fields in the data.
normalize_order_status() : string: Maps order status provided by the user to the one used in the database.
normalize_timezones() : mixed: Converts input datetime parameters to local timezone. If there are no inputs from the user in query_args, uses default from $defaults.
prime_object_caches() : void: Batch-prime post + meta caches for a list of IDs, plus their `_thumbnail_id` attachments.
remove_extra_records() : mixed: Removes extra records from intervals so that only requested number of records get returned.
sanitize_date_column_name() : string: Allow-list a date column name before it is interpolated into SQL.
selected_columns() : string: Returns a list of columns selected by the query_args formatted as a comma separated string.
set_cached_data() : bool: Wrapper around Cache::set().
set_db_table_name() : mixed: Set table name from database class.
should_use_cache() : bool: Whether or not the report should use the caching layer.
sort_array() : mixed: Sorts array of arrays based on subarray key $sort_by.
sort_intervals() : mixed: Sorts intervals according to user's request.
str_replace_clause() : mixed: Replace strings within SQL clauses by type.
update_interval_boundary_dates() : mixed: Updates start and end dates for intervals so that they represent intervals' borders, not times when data in db were recorded.
update_intervals_sql_params() : mixed: Updates the LIMIT query part for Intervals query of the report.
interval_cmp() : string: Compares two report data objects by pre-defined object property and ASC/DESC ordering.

$cache_group

Cache group for the reports.


    protected
        string
    $cache_group
     = 'reports'

$cache_key

Cache identifier.


    protected
        string
    $cache_key
     = 'customers_stats'

$cache_timeout

Time out for the cache.


    protected
        int
    $cache_timeout
     = 3600

$column_types

Mapping columns to data type to return correct response types.


    protected
        array<string|int, mixed>
    $column_types
     = array('customers_count' => 'intval', 'avg_orders_count' => 'floatval', 'avg_total_spend' => 'floatval', 'avg_avg_order_value' => 'floatval')

$context

Data store context used to pass to filters.


    protected
        string
    $context
     = 'customers_stats'

$date_column_name

Date field name.


    protected
        string
    $date_column_name
     = 'date_created'

$debug_cache

Include debugging information in the returned data when true.


    protected
        bool
    $debug_cache
     = true

$debug_cache_data

Debugging information to include in the returned data.


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

$force_cache_refresh

Refresh the cache for the current query when true.


    protected
        bool
    $force_cache_refresh
     = false

$interval_query

Intervals query object.


    protected
        SqlQuery
    $interval_query

$report_columns

SQL columns to select in the db query.


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

$subquery

Subquery object for query nesting.


    protected
        SqlQuery
    $subquery

$table_name

Table used as a data store for this report.


    protected
    static    string
    $table_name
     = ''

$total_query

Totals query object.


    protected
        SqlQuery
    $total_query

$limit_parameters

Query limit parameters.


    private
        array<string|int, mixed>
    $limit_parameters
     = array()

$order

Order property, used in the cmp function.


    private
        string
    $order
     = ''

$order_by

Order by property, used in the cmp function.


    private
        string
    $order_by
     = ''

$sql_clauses

List of SQL clauses.


    private
        array<string|int, mixed>
    $sql_clauses
     = array('select' => array(), 'from' => array(), 'left_join' => array(), 'join' => array(), 'right_join' => array(), 'where' => array(), 'where_time' => array(), 'group_by' => array(), 'having' => array(), 'limit' => array(), 'order_by' => array(), 'union' => array())

$sql_filters

SQL clause merge filters.


    private
        array<string|int, mixed>
    $sql_filters
     = array('where' => array('where', 'where_time'), 'join' => array('right_join', 'join', 'left_join'))

__construct()

Constructor.


    public
                __construct([string $context = '' ]) : mixed

Parameters

$context : string = '': Optional context passed to filters. Default empty string.

Return values

mixed —

add_debug_cache_to_envelope()

Add cache debugging information to an enveloped API response.


    public
                add_debug_cache_to_envelope(array<string|int, mixed> $envelope, WP_REST_Response $response) : array<string|int, mixed>

Parameters

$envelope : array<string|int, mixed>
$response : WP_REST_Response

Return values

array<string|int, mixed> —

add_sql_clause()

Add a SQL clause to be included when get_data is called.


    public
                add_sql_clause(string $type, string $clause) : mixed

Parameters

$type : string: Clause type.
$clause : string: SQL clause.

Return values

mixed —

clear_all_clauses()

Reinitialize the clause array.


    public
                clear_all_clauses() : mixed

Return values

mixed —

delete_customer()

Delete a customer lookup row.


    public
            static    delete_customer(int $customer_id) : mixed

Parameters

$customer_id : int: Customer ID.

Return values

mixed —

delete_customer_by_user_id()

Delete a customer lookup row by WordPress User ID.


    public
            static    delete_customer_by_user_id(int $user_id) : mixed

Parameters

$user_id : int: WordPress User ID.

Return values

mixed —

get_customer_id_by_email()

Retrieve a customer ID by email address, regardless of user registration status.


    public
            static    get_customer_id_by_email(string $email) : false|int

Prioritizes registered customers over guest customers when both exist.

Parameters

$email : string: Email address.

Return values

false|int — Customer ID if found, boolean false if not.

get_customer_id_by_user_id()

Retrieve a registered customer row id by user_id.


    public
            static    get_customer_id_by_user_id(string|int $user_id) : false|int

Parameters

$user_id : string|int: User ID.

Return values

false|int — Customer ID if found, boolean false if not.

get_customer_order_data_and_format()

Returns a data object and format object of the customers data coming from the order.


    public
            static    get_customer_order_data_and_format(WC_Order $order[, WC_Customer|null $customer_user = null ]) : array<string|int, mixed>

A plain WC_Order will be converted to an Overrides\Order internally to ensure consistent name resolution (user meta → billing → shipping fallback).

Parameters

$order : WC_Order: WC_Order where we get customer info from.
$customer_user : WC_Customer|null = null: WC_Customer registered customer WP user.

Return values

array<string|int, mixed> — ($data, $format)

get_data()

Get the data based on args.


    public
                get_data(array<string|int, mixed> $query_args) : stdClass|WP_Error

Returns the report data based on parameters supplied by the user. Fetches it from cache or returns get_noncached_data result.

Parameters

$query_args : array<string|int, mixed>: Query parameters.

Return values

stdClass|WP_Error —

get_db_table_name()

Get table name from database class.


    public
            static    get_db_table_name() : mixed

Return values

mixed —

get_default_query_vars()

Get the default query arguments to be used by get_data().


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

These defaults are only partially applied when used via REST API, as that has its own defaults.

Return values

array<string|int, mixed> — Query parameters.

get_existing_customer_id_from_order()

Returns an existing customer ID for an order if one exists.


    public
            static    get_existing_customer_id_from_order(object $order) : int|bool

Parameters

$order : object: WC Order.

Return values

int|bool —

get_guest_id_by_email()

Retrieve a guest ID (when user_id is null) by email.


    public
            static    get_guest_id_by_email(string $email) : false|array<string|int, mixed>

Parameters

$email : string: Email address.

Return values

false|array<string|int, mixed> — Customer array if found, boolean false if not.

get_last_order()

Retrieve the last order made by a customer.


    public
            static    get_last_order(int $customer_id) : object

Parameters

$customer_id : int: Customer ID.

Return values

object — WC_Order|false.

get_noncached_data()

Returns the report data based on normalized parameters.


    public
                get_noncached_data(array<string|int, mixed> $query_args) : stdClass|WP_Error

Will be called by get_data if there is no data in cache.

Parameters

$query_args : array<string|int, mixed>: Query parameters.

Return values

stdClass|WP_Error — Data object `{ totals: *, intervals: array, total: int, pages: int, page_no: int }`, or error.

get_oldest_orders()

Retrieve the oldest orders made by a customer.


    public
            static    get_oldest_orders(int $customer_id) : array<string|int, mixed>

Refunds share the customer of the order they refund, but they are not orders of that customer and must not be returned here. Parented rows use the authoritative order type so that legacy refund stats remain excluded while an order given a parent through set_parent_id() keeps counting as one of the customer's orders.

Parameters

$customer_id : int: Customer ID.

Return values

array<string|int, mixed> — Orders.

get_or_create_customer_from_order()

Get or create a customer from a given order.


    public
            static    get_or_create_customer_from_order(WC_Order $order) : int|bool

A plain WC_Order will be converted to an Overrides\Order internally to ensure consistent name resolution (user meta → billing → shipping fallback).

Parameters

$order : WC_Order: WC Order.

Return values

int|bool —

get_order_count()

Retrieve the amount of orders made by a customer.


    public
            static    get_order_count(int $customer_id) : int|null

Parameters

$customer_id : int: Customer ID.

Return values

int|null — Amount of orders for customer or null on failure.

get_query_statement()

Get the full SQL statement.


    public
                get_query_statement() : string

Return values

string —

init()

Set up all the hooks for maintaining and populating table data.


    public
            static    init() : mixed

Return values

mixed —

merge_guest_customer_on_delayed_account_creation()

When a customer registers via delayed account creation (order confirmation page), merge the existing guest lookup row instead of creating a duplicate.


    public
            static    merge_guest_customer_on_delayed_account_creation(int $customer_id, array<string|int, mixed> $new_customer_data) : void

This runs on woocommerce_created_customer at priority 5, before the analytics hooks (woocommerce_new_customer) that call update_registered_customer(). It updates the guest row's user_id so that update_registered_customer() finds it via get_customer_id_by_user_id() and updates in place rather than inserting a new row.

Parameters

$customer_id : int: New WP user ID.
$new_customer_data : array<string|int, mixed>: Customer data including 'source'.

Return values

void —

sync_on_order_delete()

Sync customers data after an order was deleted.


    public
            static    sync_on_order_delete(int $order_id, int $customer_id) : mixed

When an order is deleted, the customer record is deleted from the table if the customer has no other orders.

Parameters

$order_id : int: Order ID.
$customer_id : int: Customer ID.

Return values

mixed —

sync_order_customer()

Sync customers data after an order was updated.


    public
            static    sync_order_customer(int $post_id) : true|-1

Only updates customer if it is the customers last order.

Parameters

$post_id : int: of order.

Return values

true|-1 —

update_registered_customer()

Update the database with customer data.


    public
            static    update_registered_customer(int $user_id) : int|bool|null

Parameters

$user_id : int: WP User ID to update customer data for.

Return values

int|bool|null — Number or rows modified or false on failure.

update_registered_customer_via_last_active()

Update the database if the "last active" meta value was changed.


    public
            static    update_registered_customer_via_last_active(int $meta_id, int $user_id, string $meta_key) : mixed

Function expects to be hooked into the added_user_meta and updated_user_meta actions.

Parameters

$meta_id : int: ID of updated metadata entry.
$user_id : int: ID of the user being updated.
$meta_key : string: Meta key being updated.

Return values

mixed —

add_intervals_sql_params()

Fills FROM and WHERE clauses of SQL request for 'Intervals' section of data response based on user supplied parameters.


    protected
                add_intervals_sql_params(array<string|int, mixed> $query_args, string $table_name) : mixed

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.
$table_name : string: Name of the db table relevant for the date constraint.

Return values

mixed —

add_order_by_clause()

Add order by SQL clause if included in query.


    protected
                add_order_by_clause(array<string|int, mixed> $query_args, SqlQuery &$sql_query) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.
$sql_query : SqlQuery: Query object.

Return values

string — Order by clause.

add_order_by_sql_params()

Fills ORDER BY clause of SQL request based on user supplied parameters.


    protected
                add_order_by_sql_params(array<string|int, mixed> $query_args) : mixed

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

mixed —

add_order_status_clause()

Add order status SQL clauses if included in query.


    protected
                add_order_status_clause(array<string|int, mixed> $query_args, string $table_name, SqlQuery &$sql_query) : mixed

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.
$table_name : string: Database table name.
$sql_query : SqlQuery: Query object.

Return values

mixed —

add_orderby_order_clause()

Add order by order SQL clause.


    protected
                add_orderby_order_clause(array<string|int, mixed> $query_args, SqlQuery &$sql_query) : mixed

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.
$sql_query : SqlQuery: Query object.

Return values

mixed —

add_sql_query_params()

Updates the database query with parameters used for Customers report: categories and order status.


    protected
                add_sql_query_params(array<string|int, mixed> $query_args) : mixed

Parameters

$query_args : array<string|int, mixed>: Query arguments supplied by the user.

Return values

mixed —

add_time_period_sql_params()

Fills WHERE clause of SQL request with date-related constraints.


    protected
                add_time_period_sql_params(array<string|int, mixed> $query_args, string $table_name) : mixed

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.
$table_name : string: Name of the db table relevant for the date constraint.

Return values

mixed —

assign_report_columns()

Assign report columns once full table name has been assigned.


    protected
                assign_report_columns() : mixed

Return values

mixed —

build_location_filter_clause()

Build location filter SQL clause for includes or excludes.


    protected
                build_location_filter_clause(string $locations_string[, bool $is_include = true ]) : string

Parameters

$locations_string : string: Comma-separated list of locations (e.g., "US:CA,US:NY,GB").
$is_include : bool = true: True for IN clause, false for NOT IN clause.

Return values

string — SQL WHERE clause condition.

cast_numbers()

Casts strings returned from the database to appropriate data types for output.


    protected
                cast_numbers(array<string|int, mixed> $array) : array<string|int, mixed>|WP_Error

Parameters

$array : array<string|int, mixed>: Associative array of values extracted from the database.

Return values

array<string|int, mixed>|WP_Error —

clear_sql_clause()

Clear SQL clauses by type.


    protected
                clear_sql_clause(string|array<string|int, mixed> $types) : mixed

Parameters

$types : string|array<string|int, mixed>: Clause type.

Return values

mixed —

create_interval_subtotals()

Change structure of intervals to form a correct response.


    protected
                create_interval_subtotals(array<string|int, mixed> &$intervals) : mixed

Also converts local datetimes to GMT and adds them to the intervals.

Parameters

$intervals : array<string|int, mixed>: Time interval, e.g. day, week, month.

Return values

mixed —

expected_intervals_on_page()

Returns expected number of items on the page in case of date ordering.


    protected
                expected_intervals_on_page(int $expected_interval_count, int $items_per_page, int $page_no) : float|int

Parameters

$expected_interval_count : int: Expected number of intervals in total.
$items_per_page : int: Number of items per page.
$page_no : int: Page number.

Return values

float|int —

fill_in_missing_intervals()

Fills in interval gaps from DB with 0-filled objects.


    protected
                fill_in_missing_intervals(array<string|int, mixed> $db_intervals, DateTime $start_datetime, DateTime $end_datetime, string $time_interval, stdClass &$data) : stdClass

Parameters

$db_intervals : array<string|int, mixed>: Array of all intervals present in the db.
$start_datetime : DateTime: Start date.
$end_datetime : DateTime: End date.
$time_interval : string: Time interval, e.g. day, week, month.
$data : stdClass: Data with SQL extracted intervals.

Return values

stdClass —

format_join_selections()

Returns a comma separated list of the field names prepared to be used for a selection after a join with `default_results`.


    protected
                format_join_selections(array<string|int, mixed> $fields, array<string|int, mixed> $default_results_fields[, array<string|int, mixed> $outer_selections = array() ]) : string

Parameters

$fields : array<string|int, mixed>: Array of fields name.
$default_results_fields : array<string|int, mixed>: Fields to load from default_results table.
$outer_selections : array<string|int, mixed> = array(): Array of fields that are not selected in the inner query.

Return values

string —

get_attribute_subqueries()

Returns product attribute subquery elements used in JOIN and WHERE clauses, based on query arguments from the user.


    protected
                get_attribute_subqueries(array<string|int, mixed> $query_args) : array<string|int, mixed>

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

array<string|int, mixed> —

get_cache_key()

Returns string to be used as cache key for the data.


    protected
                get_cache_key(array<string|int, mixed> $params) : string

Parameters

$params : array<string|int, mixed>: Query parameters.

Return values

string —

get_cached_data()

Wrapper around Cache::get().


    protected
                get_cached_data(string $cache_key) : mixed

Parameters

$cache_key : string: Cache key.

Return values

mixed —

get_countable_customer_order_predicate()

Get the SQL predicate that includes orders while excluding refund rows.


    protected
            static    get_countable_customer_order_predicate(string $order_stats_table) : string

Parented rows use the authoritative order type because legacy refund stats can have a non-null returning_customer value.

Parameters

$order_stats_table : string: Fully qualified order stats table name.

Return values

string —

get_customer_subquery()

Returns customer subquery to be used in WHERE SQL query, based on query arguments from the user.


    protected
                get_customer_subquery(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_excluded_coupons()

Returns comma separated ids of excluded coupons, based on query arguments from the user.


    protected
                get_excluded_coupons(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_excluded_orders()

Returns comma separated ids of excluded orders, based on query arguments from the user.


    protected
                get_excluded_orders(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_excluded_products()

Returns comma separated ids of excluded products, based on query arguments from the user.


    protected
                get_excluded_products(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_excluded_products_array()

Returns an array of ids of disallowed products, based on query arguments from the user.


    protected
                get_excluded_products_array(array<string|int, mixed> $query_args) : array<string|int, mixed>

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

array<string|int, mixed> —

get_excluded_report_order_statuses()

Get the excluded order statuses used when calculating reports.


    protected
            static    get_excluded_report_order_statuses() : array<string|int, mixed>

Return values

array<string|int, mixed> —

get_excluded_users()

Returns comma separated ids of excluded users, based on query arguments from the user.


    protected
                get_excluded_users(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_excluded_variations()

Returns comma separated ids of excluded variations, based on query arguments from the user.


    protected
                get_excluded_variations(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_fields()

Returns a comma separated list of the fields in the `query_args`, if there aren't, returns `report_columns` keys.


    protected
                get_fields(array<string|int, mixed> $query_args) : array<string|int, mixed>

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

array<string|int, mixed> —

get_filtered_ids()

Returns filtered comma separated ids, based on query arguments from the user.


    protected
                get_filtered_ids(array<string|int, mixed> $query_args, string $field[, string $separator = ',' ]) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.
$field : string: Query field to filter.
$separator : string = ',': Field separator.

Return values

string —

get_ids_table()

Generates a virtual table given a list of IDs.


    protected
                get_ids_table(array<string|int, mixed> $ids, string $id_field[, array<string|int, mixed> $other_values = array() ]) : string

Parameters

$ids : array<string|int, mixed>: Array of IDs.
$id_field : string: Name of the ID field.
$other_values : array<string|int, mixed> = array(): Other values that must be contained in the virtual table.

Return values

string —

get_included_categories()

Returns comma separated ids of included categories, based on query arguments from the user.


    protected
                get_included_categories(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_included_coupons()

Returns comma separated ids of included coupons, based on query arguments from the user.


    protected
                get_included_coupons(array<string|int, mixed> $query_args[, string $field = 'coupon_includes' ]) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.
$field : string = 'coupon_includes': Field name in the parameter list.

Return values

string —

get_included_orders()

Returns comma separated ids of included orders, based on query arguments from the user.


    protected
                get_included_orders(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_included_products()

Returns comma separated ids of allowed products, based on query arguments from the user.


    protected
                get_included_products(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_included_products_array()

Returns an array of ids of allowed products, based on query arguments from the user.


    protected
                get_included_products_array(array<string|int, mixed> $query_args) : array<string|int, mixed>

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

array<string|int, mixed> —

get_included_users()

Returns comma separated ids of included users, based on query arguments from the user.


    protected
                get_included_users(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_included_variations()

Returns comma separated ids of allowed variations, based on query arguments from the user.


    protected
                get_included_variations(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_limit_params()

Fills LIMIT parameters of SQL request based on user supplied parameters.


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

Parameters

$query_args : array<string|int, mixed> = array(): Parameters supplied by the user.

Return values

array<string|int, mixed> —

get_limit_sql_params()

Fills LIMIT clause of SQL request based on user supplied parameters.


    protected
                get_limit_sql_params(array<string|int, mixed> $query_args) : array<string|int, mixed>

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

array<string|int, mixed> —

get_match_operator()

Returns logic operator for WHERE subclause based on 'match' query argument.


    protected
                get_match_operator(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

string —

get_object_where_filter()

Get WHERE filter by object ids subquery.


    protected
                get_object_where_filter(string $select_table, string $select_field, string $filter_table, string $filter_field, string $compare, string $id_list) : string

Parameters

$select_table : string: Select table name.
$select_field : string: Select table object ID field name.
$filter_table : string: Lookup table name.
$filter_field : string: Lookup table object ID field name.
$compare : string: Comparison string (IN|NOT IN).
$id_list : string: Comma separated ID list.

Return values

string —

get_products_by_cat_ids()

Returns an array of products belonging to given categories.


    protected
                get_products_by_cat_ids(array<string|int, mixed> $categories) : array<string|int, mixed>|stdClass

Parameters

$categories : array<string|int, mixed>: List of categories IDs.

Return values

array<string|int, mixed>|stdClass —

get_refund_subquery()

Get join and where clauses for refunds based on user supplied parameters.


    protected
                get_refund_subquery(array<string|int, mixed> $query_args) : array<string|int, mixed>

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.

Return values

array<string|int, mixed> —

get_sql_clause()

Get SQL clause by type.


    protected
                get_sql_clause(string $type[, string $handling = 'unfiltered' ]) : string

Parameters

$type : string: Clause type.
$handling : string = 'unfiltered': Whether to filter the return value (filtered|unfiltered). Default unfiltered.

Return values

string — SQL clause.

get_status_subquery()

Returns order status subquery to be used in WHERE SQL query, based on query arguments from the user.


    protected
                get_status_subquery(array<string|int, mixed> $query_args[, string $operator = 'AND' ]) : string

Parameters

$query_args : array<string|int, mixed>: Parameters supplied by the user.
$operator : string = 'AND': AND or OR, based on match query argument.

Return values

string —

initialize_queries()

Initialize query objects.


    protected
                initialize_queries() : mixed

Return values

mixed —

intervals_missing()

Returns true if there are any intervals that need to be filled in the response.


    protected
                intervals_missing(int $expected_interval_count, int $db_records, int $items_per_page, int $page_no, string $order, string $order_by, int $intervals_count) : bool

Parameters

$expected_interval_count : int: Expected number of intervals in total.
$db_records : int: Total number of records for given period in the database.
$items_per_page : int: Number of items per page.
$page_no : int: Page number.
$order : string: asc or desc.
$order_by : string: Column by which the result will be sorted.
$intervals_count : int: Number of records for given (possibly shortened) time interval.

Return values

bool —

is_valid_customer()

Check if a user ID is a valid customer or other user role with past orders.


    protected
            static    is_valid_customer(int $user_id) : bool

Parameters

$user_id : int: User ID.

Return values

bool —

normalize_order_by()

Normalizes order_by clause to match to SQL query.


    protected
                normalize_order_by(string $order_by) : string

Parameters

$order_by : string: Order by option requested by user.

Return values

string —

normalize_order_by_clause()

Maps ordering specified by the user to columns in the database/fields in the data.


    protected
                normalize_order_by_clause(string $order_by[, string $order = 'desc' ]) : string

Handles both order_by and direction.

Parameters

$order_by : string: Sorting criterion.
$order : string = 'desc': Order direction.

Return values

string —

normalize_order_status()

Maps order status provided by the user to the one used in the database.


    protected
            static    normalize_order_status(string $status) : string

Parameters

$status : string: Order status.

Return values

string —

normalize_timezones()

Converts input datetime parameters to local timezone. If there are no inputs from the user in query_args, uses default from $defaults.


    protected
                normalize_timezones(array<string|int, mixed> &$query_args, array<string|int, mixed> $defaults) : mixed

Parameters

$query_args : array<string|int, mixed>: Array of query arguments.
$defaults : array<string|int, mixed>: Array of default values.

Return values

mixed —

prime_object_caches()

Batch-prime post + meta caches for a list of IDs, plus their `_thumbnail_id` attachments.


    protected
            static    prime_object_caches(array<string|int, mixed> $ids) : void

Parameters

$ids : array<string|int, mixed>: Post IDs to prime.

Return values

void —

remove_extra_records()

Removes extra records from intervals so that only requested number of records get returned.


    protected
                remove_extra_records(stdClass &$data, int $page_no, int $items_per_page, int $db_interval_count, int $expected_interval_count, string $order_by, string $order) : mixed

Parameters

$data : stdClass: Data from whose intervals the records get removed.
$page_no : int: Offset requested by the user.
$items_per_page : int: Number of records requested by the user.
$db_interval_count : int: Database interval count.
$expected_interval_count : int: Expected interval count on the output.
$order_by : string: Order by field.
$order : string: ASC or DESC.

Return values

mixed —

sanitize_date_column_name()

Allow-list a date column name before it is interpolated into SQL.


    protected
                sanitize_date_column_name(string $column[, string $fallback = 'date_created' ]) : string

Parameters

$column : string: Requested date column name.
$fallback : string = 'date_created': Column to use when the requested one is not allowed.

Return values

string —

selected_columns()

Returns a list of columns selected by the query_args formatted as a comma separated string.


    protected
                selected_columns(array<string|int, mixed> $query_args) : string

Parameters

$query_args : array<string|int, mixed>: User-supplied options.

Return values

string —

set_cached_data()

Wrapper around Cache::set().


    protected
                set_cached_data(string $cache_key, mixed $value) : bool

Parameters

$cache_key : string: Cache key.
$value : mixed: New value.

Return values

bool —

set_db_table_name()

Set table name from database class.


    protected
            static    set_db_table_name() : mixed

Return values

mixed —

should_use_cache()

Whether or not the report should use the caching layer.


    protected
                should_use_cache() : bool

Provides an opportunity for plugins to prevent reports from using cache.

Return values

bool — Whether or not to utilize caching.

sort_array()

Sorts array of arrays based on subarray key $sort_by.


    protected
                sort_array(array<string|int, mixed> &$arr, string $sort_by, string $direction) : mixed

Parameters

$arr : array<string|int, mixed>: Array to sort.
$sort_by : string: Ordering property.
$direction : string: DESC/ASC.

Return values

mixed —

sort_intervals()

Sorts intervals according to user's request.


    protected
                sort_intervals(stdClass &$data, string $sort_by, string $direction) : mixed

They are pre-sorted in SQL, but after adding gaps, they need to be sorted including the added ones.

Parameters

$data : stdClass: Data object, must contain an array under $data->intervals.
$sort_by : string: Ordering property.
$direction : string: DESC/ASC.

Return values

mixed —

str_replace_clause()

Replace strings within SQL clauses by type.


    protected
                str_replace_clause(string $type, string $search, string $replace) : mixed

Parameters

$type : string: Clause type.
$search : string: String to search for.
$replace : string: Replacement string.

Return values

mixed —

update_interval_boundary_dates()

Updates start and end dates for intervals so that they represent intervals' borders, not times when data in db were recorded.


    protected
                update_interval_boundary_dates(DateTime $start_datetime, DateTime $end_datetime, string $time_interval, array<string|int, mixed> &$intervals) : mixed

E.g. if there are db records for only Tuesday and Thursday this week, the actual week interval is [Mon, Sun], not [Tue, Thu].

Parameters

$start_datetime : DateTime: Start date.
$end_datetime : DateTime: End date.
$time_interval : string: Time interval, e.g. day, week, month.
$intervals : array<string|int, mixed>: Array of intervals extracted from SQL db.

Return values

mixed —

update_intervals_sql_params()

Updates the LIMIT query part for Intervals query of the report.


    protected
                update_intervals_sql_params(array<string|int, mixed> &$query_args, int $db_interval_count, int $expected_interval_count, string $table_name) : mixed

If there are less records in the database than time intervals, then we need to remap offset in SQL query to fetch correct records.

Parameters

$query_args : array<string|int, mixed>: Query arguments.
$db_interval_count : int: Database interval count.
$expected_interval_count : int: Expected interval count on the output.
$table_name : string: Name of the db table relevant for the date constraint.

Return values

mixed —

interval_cmp()

Compares two report data objects by pre-defined object property and ASC/DESC ordering.


    private
                interval_cmp(stdClass $a, stdClass $b) : string

Parameters

$a : stdClass: Object a.
$b : stdClass: Object b.

Return values

string —

DataStore extends DataStore in package WooCommerce implements DataStoreInterface

Interfaces, Classes and Traits

Table of Contents

Properties

$cache_group

$cache_key

Tags

$cache_timeout

$column_types

Tags

$context

Tags

$date_column_name

$debug_cache

$debug_cache_data

$force_cache_refresh

$interval_query

$report_columns

$subquery

$table_name

$total_query

$limit_parameters

$order

$order_by

$sql_clauses

$sql_filters

Methods

__construct()

Parameters

Return values

add_debug_cache_to_envelope()

Parameters

Return values

add_sql_clause()

Parameters

Return values

clear_all_clauses()

Return values

delete_customer()

Parameters

Return values

delete_customer_by_user_id()

Parameters

Return values

get_customer_id_by_email()

Parameters

Return values

get_customer_id_by_user_id()

Parameters

Return values

get_customer_order_data_and_format()

Parameters

Return values

get_data()

Parameters

Return values

get_db_table_name()

Return values

get_default_query_vars()

Tags

Return values

get_existing_customer_id_from_order()

Parameters

Return values

get_guest_id_by_email()

Parameters

Return values

get_last_order()

Parameters

Return values

get_noncached_data()

Parameters

Tags

Return values

get_oldest_orders()

Parameters

Return values

get_or_create_customer_from_order()

Parameters

Return values

DataStore extends DataStore
in package

WooCommerce

implements DataStoreInterface