JezK
Edit File: Leaderboards.php
<?php /** * REST API Leaderboards Controller * * Handles requests to /leaderboards */ namespace Automattic\WooCommerce\Admin\API; defined( 'ABSPATH' ) || exit; use Automattic\WooCommerce\Admin\API\Reports\Categories\DataStore as CategoriesDataStore; use Automattic\WooCommerce\Admin\API\Reports\Coupons\DataStore as CouponsDataStore; use Automattic\WooCommerce\Admin\API\Reports\Customers\DataStore as CustomersDataStore; use Automattic\WooCommerce\Admin\API\Reports\Products\DataStore as ProductsDataStore; /** * Leaderboards controller. * * @internal * @extends WC_REST_Data_Controller */ class Leaderboards extends \WC_REST_Data_Controller { /** * Endpoint namespace. * * @var string */ protected $namespace = 'wc-analytics'; /** * Route base. * * @var string */ protected $rest_base = 'leaderboards'; /** * Register routes. */ public function register_routes() { register_rest_route( $this->namespace, '/' . $this->rest_base, array( array( 'methods' => \WP_REST_Server::READABLE, 'callback' => array( $this, 'get_items' ), 'permission_callback' => array( $this, 'get_items_permissions_check' ), 'args' => $this->get_collection_params(), ), 'schema' => array( $this, 'get_public_item_schema' ), ) ); register_rest_route( $this->namespace, '/' . $this->rest_base . '/allowed', array( array( 'methods' => \WP_REST_Server::READABLE, 'callback' => array( $this, 'get_allowed_items' ), 'permission_callback' => array( $this, 'get_items_permissions_check' ), ), 'schema' => array( $this, 'get_public_allowed_item_schema' ), ) ); register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P<leaderboard>\w+)', array( 'args' => array( 'leaderboard' => array( 'type' => 'string', 'enum' => array( 'customers', 'coupons', 'categories', 'products' ), ), ), array( 'methods' => \WP_REST_Server::READABLE, 'callback' => array( $this, 'get_items' ), 'permission_callback' => array( $this, 'get_items_permissions_check' ), 'args' => $this->get_collection_params(), ), 'schema' => array( $this, 'get_public_item_schema' ), ) ); } /** * Check whether a given request has permission to read leaderboards. * * Leaderboards expose analytics report data, so allow users with the * `view_woocommerce_reports` capability to access the endpoint (matching * other Analytics report endpoints). The `manage_woocommerce` check is * preserved for backwards compatibility with the previous behavior * inherited from `\WC_REST_Data_Controller`, so users granted only the * broader manage capability are not regressed. * * @param \WP_REST_Request<array<string, mixed>> $request Full details about the request. * @return \WP_Error|boolean */ public function get_items_permissions_check( $request ) { if ( ! wc_rest_check_manager_permissions( 'reports', 'read' ) && ! wc_rest_check_manager_permissions( 'settings', 'read' ) ) { return new \WP_Error( 'woocommerce_rest_cannot_view', __( 'Sorry, you cannot list resources.', 'woocommerce' ), array( 'status' => rest_authorization_required_code() ) ); } return true; } /** * Get the data for the coupons leaderboard. * * @param int $per_page Number of rows. * @param string $after Items after date. * @param string $before Items before date. * @param string $persisted_query URL query string. */ protected function get_coupons_leaderboard( $per_page, $after, $before, $persisted_query ) { $coupons_data_store = new CouponsDataStore(); $coupons_data = $per_page > 0 ? $coupons_data_store->get_data( apply_filters( 'woocommerce_analytics_coupons_query_args', array( 'orderby' => 'orders_count', 'order' => 'desc', 'after' => $after, 'before' => $before, 'per_page' => $per_page, 'extended_info' => true, ) ) )->data : array(); $rows = array(); foreach ( $coupons_data as $coupon ) { $url_query = wp_parse_args( array( 'filter' => 'single_coupon', 'coupons' => $coupon['coupon_id'], ), $persisted_query ); $coupon_url = wc_admin_url( '/analytics/coupons', $url_query ); $coupon_code = isset( $coupon['extended_info'] ) && isset( $coupon['extended_info']['code'] ) ? $coupon['extended_info']['code'] : ''; $rows[] = array( array( 'display' => "<a href='{$coupon_url}'>{$coupon_code}</a>", 'value' => $coupon_code, ), array( 'display' => wc_admin_number_format( $coupon['orders_count'] ), 'value' => $coupon['orders_count'], 'format' => 'number', ), array( 'display' => wc_price( $coupon['amount'] ), 'value' => $coupon['amount'], 'format' => 'currency', ), ); } return array( 'id' => 'coupons', 'label' => __( 'Top Coupons - Number of Orders', 'woocommerce' ), 'headers' => array( array( 'label' => __( 'Coupon code', 'woocommerce' ), ), array( 'label' => __( 'Orders', 'woocommerce' ), ), array( 'label' => __( 'Amount discounted', 'woocommerce' ), ), ), 'rows' => $rows, ); } /** * Get the data for the categories leaderboard. * * @param int $per_page Number of rows. * @param string $after Items after date. * @param string $before Items before date. * @param string $persisted_query URL query string. */ protected function get_categories_leaderboard( $per_page, $after, $before, $persisted_query ) { $categories_data_store = new CategoriesDataStore(); $categories_data = $per_page > 0 ? $categories_data_store->get_data( apply_filters( 'woocommerce_analytics_categories_query_args', array( 'orderby' => 'items_sold', 'order' => 'desc', 'after' => $after, 'before' => $before, 'per_page' => $per_page, 'extended_info' => true, ) ) )->data : array(); $rows = array(); foreach ( $categories_data as $category ) { $url_query = wp_parse_args( array( 'filter' => 'single_category', 'categories' => $category['category_id'], ), $persisted_query ); $category_url = wc_admin_url( '/analytics/categories', $url_query ); $category_name = isset( $category['extended_info'] ) && isset( $category['extended_info']['name'] ) ? $category['extended_info']['name'] : ''; $rows[] = array( array( 'display' => "<a href='{$category_url}'>{$category_name}</a>", 'value' => $category_name, ), array( 'display' => wc_admin_number_format( $category['items_sold'] ), 'value' => $category['items_sold'], 'format' => 'number', ), array( 'display' => wc_price( $category['net_revenue'] ), 'value' => $category['net_revenue'], 'format' => 'currency', ), ); } return array( 'id' => 'categories', 'label' => __( 'Top categories - Items sold', 'woocommerce' ), 'headers' => array( array( 'label' => __( 'Category', 'woocommerce' ), ), array( 'label' => __( 'Items sold', 'woocommerce' ), ), array( 'label' => __( 'Net sales', 'woocommerce' ), ), ), 'rows' => $rows, ); } /** * Get the data for the customers leaderboard. * * @param int $per_page Number of rows. * @param string $after Items after date. * @param string $before Items before date. * @param string $persisted_query URL query string. */ protected function get_customers_leaderboard( $per_page, $after, $before, $persisted_query ) { $customers_data_store = new CustomersDataStore(); $customers_data = $per_page > 0 ? $customers_data_store->get_data( apply_filters( 'woocommerce_analytics_customers_query_args', array( 'orderby' => 'total_spend', 'order' => 'desc', 'order_after' => $after, 'order_before' => $before, 'per_page' => $per_page, ) ) )->data : array(); $rows = array(); foreach ( $customers_data as $customer ) { $url_query = wp_parse_args( array( 'filter' => 'single_customer', 'customers' => $customer['id'], ), $persisted_query ); $customer_url = wc_admin_url( '/analytics/customers', $url_query ); $rows[] = array( array( 'display' => "<a href='{$customer_url}'>{$customer['name']}</a>", 'value' => $customer['name'], ), array( 'display' => wc_admin_number_format( $customer['orders_count'] ), 'value' => $customer['orders_count'], 'format' => 'number', ), array( 'display' => wc_price( $customer['total_spend'] ), 'value' => $customer['total_spend'], 'format' => 'currency', ), ); } return array( 'id' => 'customers', 'label' => __( 'Top Customers - Total Spend', 'woocommerce' ), 'headers' => array( array( 'label' => __( 'Customer Name', 'woocommerce' ), ), array( 'label' => __( 'Orders', 'woocommerce' ), ), array( 'label' => __( 'Total Spend', 'woocommerce' ), ), ), 'rows' => $rows, ); } /** * Get the data for the products leaderboard. * * @param int $per_page Number of rows. * @param string $after Items after date. * @param string $before Items before date. * @param string $persisted_query URL query string. */ protected function get_products_leaderboard( $per_page, $after, $before, $persisted_query ) { $products_data_store = new ProductsDataStore(); $products_data = $per_page > 0 ? $products_data_store->get_data( apply_filters( 'woocommerce_analytics_products_query_args', array( 'orderby' => 'items_sold', 'order' => 'desc', 'after' => $after, 'before' => $before, 'per_page' => $per_page, 'extended_info' => true, ) ) )->data : array(); $rows = array(); foreach ( $products_data as $product ) { $url_query = wp_parse_args( array( 'filter' => 'single_product', 'products' => $product['product_id'], ), $persisted_query ); $product_url = wc_admin_url( '/analytics/products', $url_query ); $product_name = isset( $product['extended_info'] ) && isset( $product['extended_info']['name'] ) ? $product['extended_info']['name'] : ''; $rows[] = array( array( 'display' => "<a href='{$product_url}'>{$product_name}</a>", 'value' => $product_name, ), array( 'display' => wc_admin_number_format( $product['items_sold'] ), 'value' => $product['items_sold'], 'format' => 'number', ), array( 'display' => wc_price( $product['net_revenue'] ), 'value' => $product['net_revenue'], 'format' => 'currency', ), ); } return array( 'id' => 'products', 'label' => __( 'Top products - Items sold', 'woocommerce' ), 'headers' => array( array( 'label' => __( 'Product', 'woocommerce' ), ), array( 'label' => __( 'Items sold', 'woocommerce' ), ), array( 'label' => __( 'Net sales', 'woocommerce' ), ), ), 'rows' => $rows, ); } /** * Get an array of all leaderboards. * * @param int $per_page Number of rows. * @param string $after Items after date. * @param string $before Items before date. * @param string $persisted_query URL query string. * @return array */ public function get_leaderboards( $per_page, $after, $before, $persisted_query ) { $leaderboards = array( $this->get_customers_leaderboard( $per_page, $after, $before, $persisted_query ), $this->get_coupons_leaderboard( $per_page, $after, $before, $persisted_query ), $this->get_categories_leaderboard( $per_page, $after, $before, $persisted_query ), $this->get_products_leaderboard( $per_page, $after, $before, $persisted_query ), ); return apply_filters( 'woocommerce_leaderboards', $leaderboards, $per_page, $after, $before, $persisted_query ); } /** * Return all leaderboards. * * @param WP_REST_Request $request Request data. * @return WP_Error|WP_REST_Response */ public function get_items( $request ) { $persisted_query = json_decode( $request['persisted_query'], true ); switch ( $request['leaderboard'] ) { case 'customers': $leaderboards = array( $this->get_customers_leaderboard( $request['per_page'], $request['after'], $request['before'], $persisted_query ) ); break; case 'coupons': $leaderboards = array( $this->get_coupons_leaderboard( $request['per_page'], $request['after'], $request['before'], $persisted_query ) ); break; case 'categories': $leaderboards = array( $this->get_categories_leaderboard( $request['per_page'], $request['after'], $request['before'], $persisted_query ) ); break; case 'products': $leaderboards = array( $this->get_products_leaderboard( $request['per_page'], $request['after'], $request['before'], $persisted_query ) ); break; default: $leaderboards = $this->get_leaderboards( $request['per_page'], $request['after'], $request['before'], $persisted_query ); break; } $data = array(); if ( ! empty( $leaderboards ) ) { foreach ( $leaderboards as $leaderboard ) { $response = $this->prepare_item_for_response( $leaderboard, $request ); $data[] = $this->prepare_response_for_collection( $response ); } } return rest_ensure_response( $data ); } /** * Returns a list of allowed leaderboards. * * @param WP_REST_Request $request Request data. * @return array|WP_Error */ public function get_allowed_items( $request ) { $leaderboards = $this->get_leaderboards( 0, null, null, null ); $data = array(); foreach ( $leaderboards as $leaderboard ) { $data[] = (object) array( 'id' => $leaderboard['id'], 'label' => $leaderboard['label'], 'headers' => $leaderboard['headers'], ); } $objects = array(); foreach ( $data as $item ) { $prepared = $this->prepare_item_for_response( $item, $request ); $objects[] = $this->prepare_response_for_collection( $prepared ); } $response = rest_ensure_response( $objects ); $response->header( 'X-WP-Total', count( $data ) ); $response->header( 'X-WP-TotalPages', 1 ); return $response; } /** * Prepare the data object for response. * * @param object $item Data object. * @param WP_REST_Request $request Request object. * @return WP_REST_Response $response Response data. */ public function prepare_item_for_response( $item, $request ) { $data = $this->add_additional_fields_to_object( $item, $request ); $data = $this->filter_response_by_context( $data, 'view' ); $response = rest_ensure_response( $data ); /** * Filter the list returned from the API. * * @param WP_REST_Response $response The response object. * @param array $item The original item. * @param WP_REST_Request $request Request used to generate the response. */ return apply_filters( 'woocommerce_rest_prepare_leaderboard', $response, $item, $request ); } /** * Get the query params for collections. * * @return array */ public function get_collection_params() { $params = array(); $params['page'] = array( 'description' => __( 'Current page of the collection.', 'woocommerce' ), 'type' => 'integer', 'default' => 1, 'sanitize_callback' => 'absint', 'validate_callback' => 'rest_validate_request_arg', 'minimum' => 1, ); $params['per_page'] = array( 'description' => __( 'Maximum number of items to be returned in result set.', 'woocommerce' ), 'type' => 'integer', 'default' => 5, 'minimum' => 1, 'maximum' => 20, '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' ), 'type' => 'string', 'format' => 'date-time', 'validate_callback' => 'rest_validate_request_arg', ); $params['before'] = array( 'description' => __( 'Limit response to resources published before a given ISO8601 compliant date.', 'woocommerce' ), 'type' => 'string', 'format' => 'date-time', 'validate_callback' => 'rest_validate_request_arg', ); $params['persisted_query'] = array( 'description' => __( 'URL query to persist across links.', 'woocommerce' ), 'type' => 'string', 'validate_callback' => 'rest_validate_request_arg', ); return $params; } /** * Get the schema, conforming to JSON Schema. * * @return array */ public function get_item_schema() { $schema = array( '$schema' => 'http://json-schema.org/draft-04/schema#', 'title' => 'leaderboard', 'type' => 'object', 'properties' => array( 'id' => array( 'type' => 'string', 'description' => __( 'Leaderboard ID.', 'woocommerce' ), 'context' => array( 'view' ), 'readonly' => true, ), 'label' => array( 'type' => 'string', 'description' => __( 'Displayed title for the leaderboard.', 'woocommerce' ), 'context' => array( 'view' ), 'readonly' => true, ), 'headers' => array( 'type' => 'array', 'description' => __( 'Table headers.', 'woocommerce' ), 'context' => array( 'view' ), 'readonly' => true, 'items' => array( 'type' => 'array', 'properties' => array( 'label' => array( 'description' => __( 'Table column header.', 'woocommerce' ), 'type' => 'string', 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ), ), 'rows' => array( 'type' => 'array', 'description' => __( 'Table rows.', 'woocommerce' ), 'context' => array( 'view' ), 'readonly' => true, 'items' => array( 'type' => 'array', 'properties' => array( 'display' => array( 'description' => __( 'Table cell display.', 'woocommerce' ), 'type' => 'string', 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'value' => array( 'description' => __( 'Table cell value.', 'woocommerce' ), 'type' => 'string', 'context' => array( 'view', 'edit' ), 'readonly' => true, ), 'format' => array( 'description' => __( 'Table cell format.', 'woocommerce' ), 'type' => 'string', 'context' => array( 'view' ), 'enum' => array( 'currency', 'number' ), 'readonly' => true, 'required' => false, ), ), ), ), ), ); return $this->add_additional_fields_schema( $schema ); } /** * Get schema for the list of allowed leaderboards. * * @return array $schema */ public function get_public_allowed_item_schema() { $schema = $this->get_public_item_schema(); unset( $schema['properties']['rows'] ); return $schema; } }