namespace Automattic\WooCommerce\Admin\API\Reports;
defined( 'ABSPATH' ) || exit;
* {@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`.
* <pre><code class="language-php">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' => 'http://json-schema.org/draft-04/schema#',
* 'title' => 'report_my_thing',
* '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 DataStore 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.
* @extends WC_REST_Reports_Controller
abstract class GenericController extends \WC_REST_Reports_Controller {
protected $namespace = 'wc-analytics';
* Add pagination headers and links.
* @param \WP_REST_Request $request Request data.
* @param \WP_REST_Response|array $response Response data.
* @param int $total Total results.
* @param int $page Current page.
* @param int $max_pages Total amount of pages.
* @return \WP_REST_Response
public function add_pagination_headers( $request, $response, int $total, int $page, int $max_pages ) {
$response = rest_ensure_response( $response );
$response->header( 'X-WP-Total', $total );
$response->header( 'X-WP-TotalPages', $max_pages );
$request->get_query_params(),
rest_url( sprintf( '/%s/%s', $this->namespace, $this->rest_base ) )
if ( $prev_page > $max_pages ) {
$prev_link = add_query_arg( 'page', $prev_page, $base );
$response->link_header( 'prev', $prev_link );
if ( $max_pages > $page ) {
$next_link = add_query_arg( 'page', $next_page, $base );
$response->link_header( 'next', $next_link );
* Get data from `{$this->rest_base}` store, based on the given query vars.
* @throws Exception When the data store is not found {@see WC_Data_Store WC_Data_Store}.
* @param array $query_args Query arguments.
* @return mixed Results from the data store.
protected function get_datastore_data( $query_args = array() ) {
$data_store = \WC_Data_Store::load( $this->rest_base );
return $data_store->get_data( $query_args );
* Get the query params definition for collections.
public function get_collection_params() {
$params['context'] = $this->get_context_param( array( 'default' => 'view' ) );
'description' => __( 'Current page of the collection.', 'woocommerce' ),
'sanitize_callback' => 'absint',
'validate_callback' => 'rest_validate_request_arg',
$params['per_page'] = array(
'description' => __( 'Maximum number of items to be returned in result set.', 'woocommerce' ),
'sanitize_callback' => 'absint',
'validate_callback' => 'rest_validate_request_arg',
$params['after'] = array(
'description' => __( 'Limit response to resources published after a given ISO8601 compliant date.', 'woocommerce' ),
'validate_callback' => 'rest_validate_request_arg',
$params['before'] = array(
'description' => __( 'Limit response to resources published before a given ISO8601 compliant date.', 'woocommerce' ),
'validate_callback' => 'rest_validate_request_arg',
$params['order'] = array(
'description' => __( 'Order sort attribute ascending or descending.', 'woocommerce' ),
'enum' => array( 'asc', 'desc' ),
'validate_callback' => 'rest_validate_request_arg',
$params['orderby'] = array(
'description' => __( 'Sort collection by object attribute.', 'woocommerce' ),
'validate_callback' => 'rest_validate_request_arg',
$params['force_cache_refresh'] = array(
'description' => __( 'Force retrieval of fresh data instead of from the cache.', 'woocommerce' ),
'sanitize_callback' => 'wp_validate_boolean',
'validate_callback' => 'rest_validate_request_arg',
* 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.
* @throws \WP_Error When the queried data is invalid.
* @param \WP_REST_Request $request Request data.
* @return \WP_Error|\WP_REST_Response
public function get_items( $request ) {
$query_args = $this->prepare_reports_query( $request );
$report_data = $this->get_datastore_data( $query_args );
if ( is_wp_error( $report_data ) ) {
if ( ! isset( $report_data->data ) || ! isset( $report_data->page_no ) || ! isset( $report_data->pages ) ) {
return new \WP_Error( 'woocommerce_rest_reports_invalid_response', __( 'Invalid response from data store.', 'woocommerce' ), array( 'status' => 500 ) );
foreach ( $report_data->data as $datum ) {
$item = $this->prepare_item_for_response( $datum, $request );
$out_data[] = $this->prepare_response_for_collection( $item );
return $this->add_pagination_headers(
(int) $report_data->total,
(int) $report_data->page_no,
(int) $report_data->pages
* Prepare a report data item for serialization.
* 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.
* @override WP_REST_Posts_Controller::prepare_item_for_response()
* @param mixed $report_item Report data item as returned from Data Store.
* @param WP_REST_Request $request Request object.
* @return WP_REST_Response
public function prepare_item_for_response( $report_item, $request ) {
$context = ! empty( $request['context'] ) ? $request['context'] : 'view';
$data = $this->add_additional_fields_to_object( $data, $request );
$data = $this->filter_response_by_context( $data, $context );
// Wrap the data in a response object.
return rest_ensure_response( $data );
* Maps query arguments from the REST request, to be used to query the datastore.
* `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.
* @param \WP_REST_Request $request Full request object.
* @return array Simplified array of params.
protected function prepare_reports_query( $request ) {
$request->get_query_params(),
$this->get_collection_params()
$request->get_default_params()
* Apply a filter for custom orderby enum.
* @param array $orderby_enum An array of orderby enum options.
* @return array An array of filtered orderby enum options.
protected function apply_custom_orderby_filters( $orderby_enum ) {
* Filter orderby query parameter enum.
* There was an initial concern about potential SQL injection with the custom orderby.
* However, testing shows it is safely blocked by validation in the controller,
* which results in an "Invalid parameter(s): orderby" error.
* Additionally, it's the responsibility of the merchant/developer to ensure the custom orderby is valid,
* or a WordPress database error will occur for unknown columns.
* @param array $orderby_enum The orderby query parameter enum.
return apply_filters( "woocommerce_analytics_orderby_enum_{$this->rest_base}", $orderby_enum );
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
