WooCommerce Code Reference

GenericController extends WC_REST_Reports_Controller
in package

{@see WC_REST_Reports_Controller WC REST API Reports Controller} extended to be shared as a generic base for all Analytics reports controllers.

Handles pagination HTTP headers and links, basic, conventional params. Does all the REST API plumbing as WC_REST_Controller.

Minimalistic example:

class MyController extends GenericController {
    /** Route of your new REST endpoint. */
    protected $rest_base = 'reports/my-thing';
    /**
     * Provide JSON schema for the response item.
     * @override WC_REST_Reports_Controller::get_item_schema()
     */
    public function get_item_schema() {
        $schema = array(
            '$schema'    => 'http://json-schema.org/draft-04/schema#',
            'title'      => 'report_my_thing',
            'type'       => 'object',
            'properties' => array(
                'product_id' => array(
                    'type'        => 'integer',
                    'readonly'    => true,
                    'context'     => array( 'view', 'edit' ),
                'description' => __( 'Product ID.', 'my_extension' ),
                ),
            ),
        );
        // Add additional fields from `get_additional_fields` method and apply `woocommerce_rest_' . $schema['title'] . '_schema` filter.
        return $this->add_additional_fields_schema( $schema );
    }
}

The above Controller will get the data from a {@see data store} registered as $rest_base (reports/my-thing). (To change this behavior, override the get_datastore_data() method).

To use the controller, please register it with the filter woocommerce_admin_rest_controllers filter.

Tags
extends

WC_REST_Reports_Controller

Table of Contents

$namespace  : string
Endpoint namespace.
$rest_base  : string
Route base.
$_fields  : null|array<string|int, mixed>
Used to cache computed return fields.
$_request  : null|WP_REST_Request
Used to verify if cached fields are for correct request object.
add_pagination_headers()  : WP_REST_Response
Add pagination headers and links.
batch_items()  : array<string|int, mixed>
Bulk create, update and delete items.
get_collection_params()  : array<string|int, mixed>
Get the query params definition for collections.
get_endpoint_args_for_item_schema()  : array<string|int, mixed>
Compatibility functions for WP 5.5, since custom types are not supported anymore.
get_fields_for_response()  : array<string|int, mixed>
Gets an array of fields to be included on the response.
get_item_schema()  : array<string|int, mixed>
Get the Report's schema, conforming to JSON Schema.
get_items()  : WP_Error|WP_REST_Response
Get the report data.
get_items_permissions_check()  : WP_Error|bool
Check whether a given request has permission to read reports.
get_public_batch_schema()  : array<string|int, mixed>
Get the batch schema, conforming to JSON Schema.
prepare_item_for_response()  : WP_REST_Response
Prepare a report data item for serialization.
register_routes()  : mixed
Register the routes for reports.
validate_setting_checkbox_field()  : string|WP_Error
Validate checkbox based settings.
validate_setting_image_width_field()  : string|WP_Error
Validate image_width based settings.
validate_setting_multiselect_field()  : array<string|int, mixed>|WP_Error
Validate multiselect based settings.
validate_setting_radio_field()  : string|WP_Error
Validate radio based settings.
validate_setting_select_field()  : string|WP_Error
Validate select based settings.
validate_setting_text_field()  : string
Validate a text value for a text based setting.
validate_setting_textarea_field()  : string
Validate textarea based settings.
add_additional_fields_schema()  : array<string|int, mixed>
Add the schema from additional fields to an schema array.
add_meta_query()  : array<string|int, mixed>
Add meta query.
adjust_wp_5_5_datatype_compatibility()  : mixed
Change datatypes `date-time` to string, and `mixed` to composite of all built in types. This is required for maintaining forward compatibility with WP 5.5 since custom post types are not supported anymore.
apply_custom_orderby_filters()  : array<string|int, mixed>
Apply a filter for custom orderby enum.
check_batch_limit()  : bool|WP_Error
Check batch limit.
get_datastore_data()  : mixed
Get data from `{$this->rest_base}` store, based on the given query vars.
get_meta_data_for_response()  : array<string|int, mixed>
Limit the contents of the meta_data property based on certain request parameters.
get_normalized_rest_base()  : string
Get normalized rest base.
get_reports()  : array<string|int, mixed>
Get reports list.
prepare_reports_query()  : array<string|int, mixed>
Maps query arguments from the REST request, to be used to query the datastore.

Properties

Methods

add_pagination_headers()

Add pagination headers and links.

public add_pagination_headers(WP_REST_Request $request, WP_REST_Response|array<string|int, mixed> $response, int $total, int $page, int $max_pages) : WP_REST_Response
Parameters
$request : WP_REST_Request

Request data.

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

Response data.

$total : int

Total results.

$page : int

Current page.

$max_pages : int

Total amount of pages.

Return values
WP_REST_Response —

batch_items()

Bulk create, update and delete items.

public batch_items(WP_REST_Request $request) : array<string|int, mixed>
Parameters
$request : WP_REST_Request

Full details about the request.

Return values
array<string|int, mixed> — Of WP_Error or WP_REST_Response.

get_collection_params()

Get the query params definition for collections.

public get_collection_params() : array<string|int, mixed>
Return values
array<string|int, mixed> —

get_endpoint_args_for_item_schema()

Compatibility functions for WP 5.5, since custom types are not supported anymore.

public get_endpoint_args_for_item_schema([string $method = WP_REST_Server::CREATABLE ]) : array<string|int, mixed>

See @link https://core.trac.wordpress.org/changeset/48306

Parameters
$method : string = WP_REST_Server::CREATABLE

Optional. HTTP method of the request.

Return values
array<string|int, mixed> — Endpoint arguments.

get_fields_for_response()

Gets an array of fields to be included on the response.

public get_fields_for_response(WP_REST_Request $request) : array<string|int, mixed>

Included fields are based on item schema and _fields= request argument. Updated from WordPress 5.3, included into this class to support old versions.

Parameters
$request : WP_REST_Request

Full details about the request.

Tags
since
3.5.0
Return values
array<string|int, mixed> — Fields to be included in the response.

get_items()

Get the report data.

public get_items(WP_REST_Request $request) : WP_Error|WP_REST_Response

Prepares query params, fetches the report data from the data store, prepares it for the response, and packs it into the convention-conforming response object.

Parameters
$request : WP_REST_Request

Request data.

Tags
throws
WP_Error

When the queried data is invalid.

Return values
WP_Error|WP_REST_Response —

prepare_item_for_response()

Prepare a report data item for serialization.

public prepare_item_for_response(mixed $report_item, WP_REST_Request $request) : WP_REST_Response

This method is called by get_items to prepare a single report data item for serialization. Calls add_additional_fields_to_object and filter_response_by_context, then wpraps the data with rest_ensure_response.

You can extend it to add or filter some fields.

Parameters
$report_item : mixed

Report data item as returned from Data Store.

$request : WP_REST_Request

Request object.

Tags
override

WP_REST_Posts_Controller::prepare_item_for_response()

Return values
WP_REST_Response —

validate_setting_checkbox_field()

Validate checkbox based settings.

public validate_setting_checkbox_field(string $value, array<string|int, mixed> $setting) : string|WP_Error
Parameters
$value : string

Value.

$setting : array<string|int, mixed>

Setting.

Tags
since
3.0.0
Return values
string|WP_Error —

validate_setting_image_width_field()

Validate image_width based settings.

public validate_setting_image_width_field(array<string|int, mixed> $values, array<string|int, mixed> $setting) : string|WP_Error
Parameters
$values : array<string|int, mixed>

Values.

$setting : array<string|int, mixed>

Setting.

Tags
since
3.0.0
Return values
string|WP_Error —

validate_setting_multiselect_field()

Validate multiselect based settings.

public validate_setting_multiselect_field(array<string|int, mixed> $values, array<string|int, mixed> $setting) : array<string|int, mixed>|WP_Error
Parameters
$values : array<string|int, mixed>

Values.

$setting : array<string|int, mixed>

Setting.

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

validate_setting_radio_field()

Validate radio based settings.

public validate_setting_radio_field(string $value, array<string|int, mixed> $setting) : string|WP_Error
Parameters
$value : string

Value.

$setting : array<string|int, mixed>

Setting.

Tags
since
3.0.0
Return values
string|WP_Error —

validate_setting_select_field()

Validate select based settings.

public validate_setting_select_field(string $value, array<string|int, mixed> $setting) : string|WP_Error
Parameters
$value : string

Value.

$setting : array<string|int, mixed>

Setting.

Tags
since
3.0.0
Return values
string|WP_Error —

validate_setting_text_field()

Validate a text value for a text based setting.

public validate_setting_text_field(string $value, array<string|int, mixed> $setting) : string
Parameters
$value : string

Value.

$setting : array<string|int, mixed>

Setting.

Tags
since
3.0.0
Return values
string —

validate_setting_textarea_field()

Validate textarea based settings.

public validate_setting_textarea_field(string $value, array<string|int, mixed> $setting) : string
Parameters
$value : string

Value.

$setting : array<string|int, mixed>

Setting.

Tags
since
3.0.0
since
9.0.0

No longer allows storing IFRAME, which was allowed for "ShareThis" integration no longer found in core.

Return values
string —

add_additional_fields_schema()

Add the schema from additional fields to an schema array.

protected add_additional_fields_schema(array<string|int, mixed> $schema) : array<string|int, mixed>

The type of object is inferred from the passed schema.

Parameters
$schema : array<string|int, mixed>

Schema array.

Return values
array<string|int, mixed> —

add_meta_query()

Add meta query.

protected add_meta_query(array<string|int, mixed> $args, array<string|int, mixed> $meta_query) : array<string|int, mixed>
Parameters
$args : array<string|int, mixed>

Query args.

$meta_query : array<string|int, mixed>

Meta query.

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

adjust_wp_5_5_datatype_compatibility()

Change datatypes `date-time` to string, and `mixed` to composite of all built in types. This is required for maintaining forward compatibility with WP 5.5 since custom post types are not supported anymore.

protected adjust_wp_5_5_datatype_compatibility(array<string|int, mixed> $endpoint_args) : mixed

See @link https://core.trac.wordpress.org/changeset/48306

We still use the 'mixed' type, since if we convert to composite type everywhere, it won't work in 5.4 anymore because they require to define the full schema.

Parameters
$endpoint_args : array<string|int, mixed>

Schema with datatypes to convert.

Return values
mixed — Schema with converted datatype.

apply_custom_orderby_filters()

Apply a filter for custom orderby enum.

protected apply_custom_orderby_filters(array<string|int, mixed> $orderby_enum) : array<string|int, mixed>
Parameters
$orderby_enum : array<string|int, mixed>

An array of orderby enum options.

Tags
since
9.4.0
Return values
array<string|int, mixed> — An array of filtered orderby enum options.

get_datastore_data()

Get data from `{$this->rest_base}` store, based on the given query vars.

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

Query arguments.

Tags
throws
Exception

When the data store is not found {@see WC_Data_Store}.

Return values
mixed — Results from the data store.

get_meta_data_for_response()

Limit the contents of the meta_data property based on certain request parameters.

protected get_meta_data_for_response(WP_REST_Request $request, array<string|int, mixed> $meta_data) : array<string|int, mixed>

Note that if both include_meta and exclude_meta are present in the request, include_meta will take precedence.

Parameters
$request : WP_REST_Request

The request.

$meta_data : array<string|int, mixed>

All of the meta data for an object.

Return values
array<string|int, mixed> —

prepare_reports_query()

Maps query arguments from the REST request, to be used to query the datastore.

protected prepare_reports_query(WP_REST_Request $request) : array<string|int, mixed>

WP_REST_Request does not expose a method to return all params covering defaults, as it does for $request['param'] accessor. Therefore, we re-implement defaults resolution.

Parameters
$request : WP_REST_Request

Full request object.

Return values
array<string|int, mixed> — Simplified array of params.