2019-01-18 21:35:43 +00:00
< ? php
/**
* REST API Reports customers stats controller
*
* Handles requests to the / reports / customers / stats endpoint .
*
* @ package WooCommerce Admin / API
*/
defined ( 'ABSPATH' ) || exit ;
/**
* REST API Reports customers stats controller class .
*
* @ package WooCommerce / API
* @ extends WC_REST_Reports_Controller
*/
class WC_Admin_REST_Reports_Customers_Stats_Controller extends WC_REST_Reports_Controller {
/**
* Endpoint namespace .
*
* @ var string
*/
protected $namespace = 'wc/v4' ;
/**
* Route base .
*
* @ var string
*/
protected $rest_base = 'reports/customers/stats' ;
/**
* Maps query arguments from the REST request .
*
* @ param array $request Request array .
* @ return array
*/
protected function prepare_reports_query ( $request ) {
$args = array ();
$args [ 'registered_before' ] = $request [ 'registered_before' ];
$args [ 'registered_after' ] = $request [ 'registered_after' ];
$args [ 'match' ] = $request [ 'match' ];
2019-02-12 19:06:22 +00:00
$args [ 'search' ] = $request [ 'search' ];
2019-03-19 04:45:08 +00:00
$args [ 'name_includes' ] = $request [ 'name_includes' ];
$args [ 'name_excludes' ] = $request [ 'name_excludes' ];
$args [ 'username_includes' ] = $request [ 'username_includes' ];
$args [ 'username_excludes' ] = $request [ 'username_excludes' ];
$args [ 'email_includes' ] = $request [ 'email_includes' ];
$args [ 'email_excludes' ] = $request [ 'email_excludes' ];
$args [ 'country_includes' ] = $request [ 'country_includes' ];
$args [ 'country_excludes' ] = $request [ 'country_excludes' ];
2019-01-18 21:35:43 +00:00
$args [ 'last_active_before' ] = $request [ 'last_active_before' ];
$args [ 'last_active_after' ] = $request [ 'last_active_after' ];
$args [ 'orders_count_min' ] = $request [ 'orders_count_min' ];
$args [ 'orders_count_max' ] = $request [ 'orders_count_max' ];
$args [ 'total_spend_min' ] = $request [ 'total_spend_min' ];
$args [ 'total_spend_max' ] = $request [ 'total_spend_max' ];
$args [ 'avg_order_value_min' ] = $request [ 'avg_order_value_min' ];
$args [ 'avg_order_value_max' ] = $request [ 'avg_order_value_max' ];
$args [ 'last_order_before' ] = $request [ 'last_order_before' ];
$args [ 'last_order_after' ] = $request [ 'last_order_after' ];
2019-02-12 19:08:33 +00:00
$args [ 'customers' ] = $request [ 'customers' ];
2019-01-18 21:35:43 +00:00
2019-01-28 22:48:40 +00:00
$between_params_numeric = array ( 'orders_count' , 'total_spend' , 'avg_order_value' );
2019-01-28 23:08:44 +00:00
$normalized_params_numeric = WC_Admin_Reports_Interval :: normalize_between_params ( $request , $between_params_numeric , false );
2019-01-28 22:48:40 +00:00
$between_params_date = array ( 'last_active' , 'registered' );
2019-01-28 23:08:44 +00:00
$normalized_params_date = WC_Admin_Reports_Interval :: normalize_between_params ( $request , $between_params_date , true );
$args = array_merge ( $args , $normalized_params_numeric , $normalized_params_date );
2019-01-18 21:35:43 +00:00
return $args ;
}
/**
* Get all reports .
*
* @ param WP_REST_Request $request Request data .
* @ return array | WP_Error
*/
public function get_items ( $request ) {
$query_args = $this -> prepare_reports_query ( $request );
$customers_query = new WC_Admin_Reports_Customers_Stats_Query ( $query_args );
$report_data = $customers_query -> get_data ();
$out_data = array (
2019-03-13 17:14:02 +00:00
'totals' => $report_data ,
2019-01-18 21:35:43 +00:00
);
return rest_ensure_response ( $out_data );
}
/**
* Prepare a report object for serialization .
*
* @ param Array $report Report data .
* @ param WP_REST_Request $request Request object .
* @ return WP_REST_Response
*/
public function prepare_item_for_response ( $report , $request ) {
$data = $report ;
$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.
$response = rest_ensure_response ( $data );
/**
* Filter a report returned from the API .
*
* Allows modification of the report data right before it is returned .
*
* @ param WP_REST_Response $response The response object .
* @ param object $report The original report object .
* @ param WP_REST_Request $request Request used to generate the response .
*/
return apply_filters ( 'woocommerce_rest_prepare_report_customers_stats' , $response , $report , $request );
}
/**
* Get the Report ' s schema , conforming to JSON Schema .
*
* @ return array
*/
public function get_item_schema () {
2019-02-06 06:41:53 +00:00
// @todo Should any of these be 'indicator's?
2019-01-18 21:35:43 +00:00
$totals = array (
2019-01-28 19:58:07 +00:00
'customers_count' => array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Number of customers.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'integer' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'avg_orders_count' => array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Average number of orders.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'integer' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
2019-01-28 19:58:07 +00:00
'avg_total_spend' => array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Average total spend per customer.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'number' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
'format' => 'currency' ,
),
'avg_avg_order_value' => array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Average AOV per customer.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'number' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
'format' => 'currency' ,
),
);
$schema = array (
'$schema' => 'http://json-schema.org/draft-04/schema#' ,
'title' => 'report_customers_stats' ,
'type' => 'object' ,
'properties' => array (
2019-03-13 17:14:02 +00:00
'totals' => array (
'description' => __ ( 'Totals data.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'object' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
'properties' => $totals ,
),
),
);
return $this -> add_additional_fields_schema ( $schema );
}
/**
* Get the query params for collections .
*
* @ return array
*/
public function get_collection_params () {
$params = array ();
$params [ 'context' ] = $this -> get_context_param ( array ( 'default' => 'view' ) );
$params [ 'registered_before' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects registered before (or at) a given ISO8601 compliant datetime.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'registered_after' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects registered after (or at) a given ISO8601 compliant datetime.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-01-28 19:58:07 +00:00
$params [ 'match' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Indicates whether all the conditions should be true for the resulting set, or if any one of them is sufficient. Match affects the following parameters: status_is, status_is_not, product_includes, product_excludes, coupon_includes, coupon_excludes, customer, categories' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'default' => 'all' ,
'enum' => array (
'all' ,
'any' ,
),
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-02-12 19:06:22 +00:00
$params [ 'search' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with a customer field containing the search term. Searches the field provided by `searchby`.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-03-13 17:14:02 +00:00
$params [ 'searchby' ] = array (
'description' => 'Limit results with `search` and `searchby` to specific fields containing the search term.' ,
'type' => 'string' ,
'default' => 'name' ,
'enum' => array (
2019-02-19 19:35:29 +00:00
'name' ,
'username' ,
'email' ,
),
);
2019-04-10 08:49:00 +00:00
$params [ 'name_includes' ] = array (
2019-03-19 04:45:08 +00:00
'description' => __ ( 'Limit response to objects with specfic names.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-04-10 08:49:00 +00:00
$params [ 'name_excludes' ] = array (
2019-03-19 04:45:08 +00:00
'description' => __ ( 'Limit response to objects excluding specfic names.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-04-10 08:49:00 +00:00
$params [ 'username_includes' ] = array (
2019-03-19 04:45:08 +00:00
'description' => __ ( 'Limit response to objects with specfic usernames.' , 'woocommerce-admin' ),
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-04-10 08:49:00 +00:00
$params [ 'username_excludes' ] = array (
2019-03-19 04:45:08 +00:00
'description' => __ ( 'Limit response to objects excluding specfic usernames.' , 'woocommerce-admin' ),
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-04-10 08:49:00 +00:00
$params [ 'email_includes' ] = array (
2019-03-19 04:45:08 +00:00
'description' => __ ( 'Limit response to objects including emails.' , 'woocommerce-admin' ),
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-04-10 08:49:00 +00:00
$params [ 'email_excludes' ] = array (
2019-03-19 04:45:08 +00:00
'description' => __ ( 'Limit response to objects excluding emails.' , 'woocommerce-admin' ),
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'country_includes' ] = array (
'description' => __ ( 'Limit response to objects with specfic countries.' , 'woocommerce-admin' ),
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'country_excludes' ] = array (
'description' => __ ( 'Limit response to objects excluding specfic countries.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
' type ' => ' string ' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'last_active_before' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects last active before (or at) a given ISO8601 compliant datetime.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'last_active_after' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects last active after (or at) a given ISO8601 compliant datetime.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-01-28 21:53:56 +00:00
$params [ 'last_active_between' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects last active between two given ISO8601 compliant datetime.' , 'woocommerce-admin' ),
2019-01-28 21:53:56 +00:00
'type' => 'array' ,
'validate_callback' => array ( 'WC_Admin_Reports_Interval' , 'rest_validate_between_date_arg' ),
);
2019-01-28 19:58:07 +00:00
$params [ 'registered_before' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects registered before (or at) a given ISO8601 compliant datetime.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-01-28 19:58:07 +00:00
$params [ 'registered_after' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects registered after (or at) a given ISO8601 compliant datetime.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-01-28 22:48:40 +00:00
$params [ 'registered_between' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects last active between two given ISO8601 compliant datetime.' , 'woocommerce-admin' ),
2019-01-28 22:05:27 +00:00
'type' => 'array' ,
'validate_callback' => array ( 'WC_Admin_Reports_Interval' , 'rest_validate_between_date_arg' ),
);
2019-01-28 19:58:07 +00:00
$params [ 'orders_count_min' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with an order count greater than or equal to given integer.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'integer' ,
'sanitize_callback' => 'absint' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-01-28 19:58:07 +00:00
$params [ 'orders_count_max' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with an order count less than or equal to given integer.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'integer' ,
'sanitize_callback' => 'absint' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-01-28 19:58:07 +00:00
$params [ 'orders_count_between' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with an order count between two given integers.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'array' ,
2019-01-28 19:58:07 +00:00
'validate_callback' => array ( 'WC_Admin_Reports_Interval' , 'rest_validate_between_numeric_arg' ),
2019-01-18 21:35:43 +00:00
);
$params [ 'total_spend_min' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with a total order spend greater than or equal to given number.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'number' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'total_spend_max' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with a total order spend less than or equal to given number.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'number' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'total_spend_between' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with a total order spend between two given numbers.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'array' ,
2019-01-28 19:58:07 +00:00
'validate_callback' => array ( 'WC_Admin_Reports_Interval' , 'rest_validate_between_numeric_arg' ),
2019-01-18 21:35:43 +00:00
);
$params [ 'avg_order_value_min' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with an average order spend greater than or equal to given number.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'number' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'avg_order_value_max' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with an average order spend less than or equal to given number.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'number' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'avg_order_value_between' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with an average order spend between two given numbers.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'array' ,
2019-01-28 19:58:07 +00:00
'validate_callback' => array ( 'WC_Admin_Reports_Interval' , 'rest_validate_between_numeric_arg' ),
2019-01-18 21:35:43 +00:00
);
$params [ 'last_order_before' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with last order before (or at) a given ISO8601 compliant datetime.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'last_order_after' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit response to objects with last order after (or at) a given ISO8601 compliant datetime.' , 'woocommerce-admin' ),
2019-01-18 21:35:43 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2019-02-19 19:35:29 +00:00
$params [ 'customers' ] = array (
2019-03-13 17:14:02 +00:00
'description' => __ ( 'Limit result to items with specified customer ids.' , 'woocommerce-admin' ),
2019-02-12 19:08:33 +00:00
'type' => 'array' ,
'sanitize_callback' => 'wp_parse_id_list' ,
'validate_callback' => 'rest_validate_request_arg' ,
'items' => array (
'type' => 'integer' ,
),
);
2019-01-18 21:35:43 +00:00
return $params ;
}
}
