2018-09-17 14:32:03 +00:00
< ? php
/**
* REST API Reports customers controller
*
* Handles requests to the / reports / customers endpoint .
*
2018-09-17 19:13:19 +00:00
* @ package WooCommerce Admin / API
2018-09-17 14:32:03 +00:00
*/
defined ( 'ABSPATH' ) || exit ;
/**
* REST API Reports customers controller class .
*
* @ package WooCommerce / API
* @ extends WC_REST_Reports_Controller
*/
2018-09-17 19:13:19 +00:00
class WC_Admin_REST_Reports_Customers_Controller extends WC_REST_Reports_Controller {
2018-09-17 14:32:03 +00:00
/**
* Endpoint namespace .
*
* @ var string
*/
2019-01-18 02:52:58 +00:00
protected $namespace = 'wc/v4' ;
2018-09-17 14:32:03 +00:00
/**
* Route base .
*
* @ var string
*/
protected $rest_base = 'reports/customers' ;
2018-09-18 11:20:42 +00:00
/**
* Maps query arguments from the REST request .
*
* @ param array $request Request array .
* @ return array
*/
protected function prepare_reports_query ( $request ) {
2019-01-09 00:41:48 +00:00
$args = array ();
$args [ 'registered_before' ] = $request [ 'registered_before' ];
$args [ 'registered_after' ] = $request [ 'registered_after' ];
$args [ 'page' ] = $request [ 'page' ];
$args [ 'per_page' ] = $request [ 'per_page' ];
$args [ 'order' ] = $request [ 'order' ];
$args [ 'orderby' ] = $request [ 'orderby' ];
$args [ 'match' ] = $request [ 'match' ];
$args [ 'name' ] = $request [ 'name' ];
$args [ 'username' ] = $request [ 'username' ];
$args [ 'email' ] = $request [ 'email' ];
$args [ 'country' ] = $request [ 'country' ];
$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' ];
$between_params = array ( 'orders_count' , 'total_spend' , 'avg_order_value' );
$normalized = WC_Admin_Reports_Interval :: normalize_between_params ( $request , $between_params );
$args = array_merge ( $args , $normalized );
2018-09-18 11:20:42 +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 );
2018-12-20 01:22:39 +00:00
$customers_query = new WC_Admin_Reports_Customers_Query ( $query_args );
2018-09-18 11:20:42 +00:00
$report_data = $customers_query -> get_data ();
2018-12-20 01:22:39 +00:00
$data = array ();
foreach ( $report_data -> data as $customer_data ) {
$item = $this -> prepare_item_for_response ( $customer_data , $request );
$data [] = $this -> prepare_response_for_collection ( $item );
2018-09-18 11:20:42 +00:00
}
2018-12-20 01:22:39 +00:00
$response = rest_ensure_response ( $data );
2018-09-18 11:20:42 +00:00
$response -> header ( 'X-WP-Total' , ( int ) $report_data -> total );
$response -> header ( 'X-WP-TotalPages' , ( int ) $report_data -> pages );
2018-12-20 01:22:39 +00:00
2018-09-18 11:20:42 +00:00
$page = $report_data -> page_no ;
$max_pages = $report_data -> pages ;
$base = add_query_arg ( $request -> get_query_params (), rest_url ( sprintf ( '/%s/%s' , $this -> namespace , $this -> rest_base ) ) );
if ( $page > 1 ) {
$prev_page = $page - 1 ;
if ( $prev_page > $max_pages ) {
$prev_page = $max_pages ;
}
$prev_link = add_query_arg ( 'page' , $prev_page , $base );
$response -> link_header ( 'prev' , $prev_link );
}
if ( $max_pages > $page ) {
$next_page = $page + 1 ;
$next_link = add_query_arg ( 'page' , $next_page , $base );
$response -> link_header ( 'next' , $next_link );
}
2018-12-20 01:22:39 +00:00
2018-09-18 11:20:42 +00:00
return $response ;
}
/**
* Prepare a report object for serialization .
*
2018-12-20 01:22:39 +00:00
* @ param array $report Report data .
2018-09-18 11:20:42 +00:00
* @ param WP_REST_Request $request Request object .
* @ return WP_REST_Response
*/
public function prepare_item_for_response ( $report , $request ) {
2018-12-20 23:19:40 +00:00
$context = ! empty ( $request [ 'context' ] ) ? $request [ 'context' ] : 'view' ;
$data = $this -> add_additional_fields_to_object ( $report , $request );
$data [ 'date_registered_gmt' ] = wc_rest_prepare_date_response ( $data [ 'date_registered' ] );
$data [ 'date_registered' ] = wc_rest_prepare_date_response ( $data [ 'date_registered' ], false );
$data [ 'date_last_active_gmt' ] = wc_rest_prepare_date_response ( $data [ 'date_last_active' ] );
$data [ 'date_last_active' ] = wc_rest_prepare_date_response ( $data [ 'date_last_active' ], false );
$data = $this -> filter_response_by_context ( $data , $context );
2018-09-18 11:20:42 +00:00
// Wrap the data in a response object.
$response = rest_ensure_response ( $data );
$response -> add_links ( $this -> prepare_links ( $report ) );
/**
* 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' , $response , $report , $request );
}
/**
* Prepare links for the request .
*
2018-12-20 01:22:39 +00:00
* @ param array $object Object data .
2018-09-18 11:20:42 +00:00
* @ return array
*/
protected function prepare_links ( $object ) {
2018-12-20 16:46:29 +00:00
if ( empty ( $object [ 'user_id' ] ) ) {
return array ();
}
return array (
2018-09-18 11:20:42 +00:00
'customer' => array (
2018-12-20 16:46:29 +00:00
'href' => rest_url ( sprintf ( '/%s/customers/%d' , $this -> namespace , $object [ 'user_id' ] ) ),
2018-09-18 11:20:42 +00:00
),
);
}
/**
* Get the Report ' s schema , conforming to JSON Schema .
*
* @ return array
*/
public function get_item_schema () {
$schema = array (
'$schema' => 'http://json-schema.org/draft-04/schema#' ,
'title' => 'report_customers' ,
'type' => 'object' ,
'properties' => array (
2018-12-19 17:14:55 +00:00
'customer_id' => array (
'description' => __ ( 'Customer ID.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'integer' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
2018-12-19 17:14:55 +00:00
'user_id' => array (
'description' => __ ( 'User ID.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'integer' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
2018-12-19 17:14:55 +00:00
'name' => array (
'description' => __ ( 'Name.' , 'wc-admin' ),
'type' => 'string' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'username' => array (
'description' => __ ( 'Username.' , 'wc-admin' ),
'type' => 'string' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'country' => array (
'description' => __ ( 'Country.' , 'wc-admin' ),
'type' => 'string' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'city' => array (
'description' => __ ( 'City.' , 'wc-admin' ),
'type' => 'string' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'postcode' => array (
'description' => __ ( 'Postal code.' , 'wc-admin' ),
'type' => 'string' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'date_registered' => array (
'description' => __ ( 'Date registered.' , 'wc-admin' ),
'type' => 'date-time' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'date_registered_gmt' => array (
'description' => __ ( 'Date registered GMT.' , 'wc-admin' ),
'type' => 'date-time' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
2018-09-18 11:20:42 +00:00
'date_last_active' => array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Date last active.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'date-time' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'date_last_active_gmt' => array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Date last active GMT.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'date-time' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'orders_count' => array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Order count.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'integer' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'total_spend' => array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Total spend.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'number' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
'avg_order_value' => array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Avg order value.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'number' ,
'context' => array ( 'view' , 'edit' ),
'readonly' => true ,
),
),
);
return $this -> add_additional_fields_schema ( $schema );
}
/**
* Get the query params for collections .
*
* @ return array
*/
public function get_collection_params () {
2018-12-21 04:07:54 +00:00
$params = array ();
$params [ 'context' ] = $this -> get_context_param ( array ( 'default' => 'view' ) );
2018-12-19 17:14:17 +00:00
$params [ 'registered_before' ] = array (
'description' => __ ( 'Limit response to objects registered before (or at) a given ISO8601 compliant datetime.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-19 17:14:17 +00:00
$params [ 'registered_after' ] = array (
'description' => __ ( 'Limit response to objects registered after (or at) a given ISO8601 compliant datetime.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-21 04:07:54 +00:00
$params [ 'page' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Current page of the collection.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'integer' ,
'default' => 1 ,
'sanitize_callback' => 'absint' ,
'validate_callback' => 'rest_validate_request_arg' ,
'minimum' => 1 ,
);
2018-12-21 04:07:54 +00:00
$params [ 'per_page' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Maximum number of items to be returned in result set.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'integer' ,
'default' => 10 ,
'minimum' => 1 ,
'maximum' => 100 ,
'sanitize_callback' => 'absint' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-20 01:20:27 +00:00
$params [ 'order' ] = array (
'description' => __ ( 'Order sort attribute ascending or descending.' , 'wc-admin' ),
'type' => 'string' ,
'default' => 'desc' ,
'enum' => array ( 'asc' , 'desc' ),
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'orderby' ] = array (
'description' => __ ( 'Sort collection by object attribute.' , 'wc-admin' ),
'type' => 'string' ,
'default' => 'date_registered' ,
'enum' => array (
'username' ,
'name' ,
'country' ,
'city' ,
'postcode' ,
'date_registered' ,
'date_last_active' ,
'orders_count' ,
'total_spend' ,
'avg_order_value' ,
),
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'match' ] = array (
'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' , 'wc-admin' ),
'type' => 'string' ,
'default' => 'all' ,
'enum' => array (
'all' ,
'any' ,
),
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'name' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects with a specfic customer name.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-21 04:07:54 +00:00
$params [ 'username' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects with a specfic username.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-21 04:07:54 +00:00
$params [ 'email' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects equal to an email.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-21 04:07:54 +00:00
$params [ 'country' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects with a specfic country.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'string' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-21 04:07:54 +00:00
$params [ 'last_active_before' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects last active before (or at) a given ISO8601 compliant datetime.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-21 04:07:54 +00:00
$params [ 'last_active_after' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects last active after (or at) a given ISO8601 compliant datetime.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-20 01:20:27 +00:00
$params [ 'registered_before' ] = array (
'description' => __ ( 'Limit response to objects registered before (or at) a given ISO8601 compliant datetime.' , 'wc-admin' ),
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'registered_after' ] = array (
'description' => __ ( 'Limit response to objects registered after (or at) a given ISO8601 compliant datetime.' , 'wc-admin' ),
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'orders_count_min' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects with an order count greater than or equal to given integer.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'integer' ,
'sanitize_callback' => 'absint' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-20 01:20:27 +00:00
$params [ 'orders_count_max' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects with an order count less than or equal to given integer.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'integer' ,
'sanitize_callback' => 'absint' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-20 01:20:27 +00:00
$params [ 'orders_count_between' ] = array (
2018-12-21 04:07:54 +00:00
'description' => __ ( 'Limit response to objects with an order count between two given integers.' , 'wc-admin' ),
2019-01-09 21:19:37 +00:00
'type' => 'array' ,
'validate_callback' => array ( 'WC_Admin_Reports_Interval' , 'rest_validate_between_arg' ),
2018-12-21 04:07:54 +00:00
);
$params [ 'total_spend_min' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects with a total order spend greater than or equal to given number.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'number' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-21 04:07:54 +00:00
$params [ 'total_spend_max' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects with a total order spend less than or equal to given number.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'number' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-21 04:07:54 +00:00
$params [ 'total_spend_between' ] = array (
'description' => __ ( 'Limit response to objects with a total order spend between two given numbers.' , 'wc-admin' ),
2019-01-09 21:19:37 +00:00
'type' => 'array' ,
'validate_callback' => array ( 'WC_Admin_Reports_Interval' , 'rest_validate_between_arg' ),
2018-12-21 04:07:54 +00:00
);
$params [ 'avg_order_value_min' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects with an average order spend greater than or equal to given number.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'number' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-21 04:07:54 +00:00
$params [ 'avg_order_value_max' ] = array (
2018-09-28 15:34:33 +00:00
'description' => __ ( 'Limit response to objects with an average order spend less than or equal to given number.' , 'wc-admin' ),
2018-09-18 11:20:42 +00:00
'type' => 'number' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-12-21 04:07:54 +00:00
$params [ 'avg_order_value_between' ] = array (
'description' => __ ( 'Limit response to objects with an average order spend between two given numbers.' , 'wc-admin' ),
2019-01-09 21:19:37 +00:00
'type' => 'array' ,
'validate_callback' => array ( 'WC_Admin_Reports_Interval' , 'rest_validate_between_arg' ),
2018-12-21 04:07:54 +00:00
);
2018-12-19 17:14:17 +00:00
$params [ 'last_order_before' ] = array (
'description' => __ ( 'Limit response to objects with last order before (or at) a given ISO8601 compliant datetime.' , 'wc-admin' ),
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
$params [ 'last_order_after' ] = array (
'description' => __ ( 'Limit response to objects with last order after (or at) a given ISO8601 compliant datetime.' , 'wc-admin' ),
'type' => 'string' ,
'format' => 'date-time' ,
'validate_callback' => 'rest_validate_request_arg' ,
);
2018-09-18 11:20:42 +00:00
return $params ;
}
2018-09-17 14:32:03 +00:00
}
