AnalyticsImports.php
<?php
/**
* REST API Analytics Imports Controller
*
* Handles requests to get batch import status and trigger manual imports.
*/
declare( strict_types = 1 );
namespace Automattic\WooCommerce\Admin\API;
use WP_Error;
use Automattic\WooCommerce\Internal\Admin\Schedulers\OrdersScheduler;
defined( 'ABSPATH' ) || exit;
/**
* REST API Analytics Imports Controller.
*
* @internal
*/
class AnalyticsImports extends \WC_REST_Data_Controller {
/**
* Endpoint namespace.
*
* @var string
*/
protected $namespace = 'wc-analytics';
/**
* Route base.
*
* @var string
*/
protected $rest_base = 'imports';
/**
* Register routes.
*
* @return void
*/
public function register_routes(): void {
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/status',
array(
array(
'methods' => \WP_REST_Server::READABLE,
'callback' => array( $this, 'get_status' ),
'permission_callback' => array( $this, 'permissions_check' ),
),
'schema' => array( $this, 'get_status_schema' ),
)
);
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/trigger',
array(
array(
'methods' => \WP_REST_Server::CREATABLE,
'callback' => array( $this, 'trigger_import' ),
'permission_callback' => array( $this, 'permissions_check' ),
),
'schema' => array( $this, 'get_trigger_schema' ),
)
);
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/retry-failed',
array(
array(
'methods' => \WP_REST_Server::CREATABLE,
'callback' => array( $this, 'retry_failed_imports' ),
'permission_callback' => array( $this, 'permissions_check' ),
),
'schema' => array( $this, 'get_retry_failed_schema' ),
)
);
}
/**
* Check if a given request has access to analytics imports.
*
* @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
* @return WP_Error|boolean
*/
public function permissions_check( $request ) {
if ( ! current_user_can( 'manage_woocommerce' ) ) {
return new WP_Error(
'woocommerce_rest_cannot_access',
__( 'Sorry, you cannot access analytics imports.', 'woocommerce' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Get the current import status.
*
* @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
* @return \WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function get_status( $request ) {
$is_scheduled_mode = $this->is_scheduled_import_enabled();
$mode = $is_scheduled_mode ? 'scheduled' : 'immediate';
$failed_imports = OrdersScheduler::get_failed_order_imports();
$response = array(
'mode' => $mode,
'last_processed_date' => null,
'next_scheduled' => null,
'import_in_progress_or_due' => null,
'failed_count' => count( $failed_imports['ids'] ),
'failed_overflow_count' => $failed_imports['overflow'],
);
// For scheduled mode, populate additional fields.
if ( $is_scheduled_mode ) {
$last_processed_gmt = get_option( OrdersScheduler::LAST_PROCESSED_ORDER_DATE_OPTION, null );
$response['last_processed_date'] = ( is_string( $last_processed_gmt ) && $last_processed_gmt ) ? get_date_from_gmt( $last_processed_gmt, 'Y-m-d H:i:s' ) : null;
$response['next_scheduled'] = $this->get_next_scheduled_time();
$response['import_in_progress_or_due'] = $this->is_import_in_progress_or_due();
}
return rest_ensure_response( $response );
}
/**
* Trigger a manual import.
*
* @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
* @return \WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function trigger_import( $request ) {
$is_scheduled_mode = $this->is_scheduled_import_enabled();
// Return error if in immediate mode.
if ( ! $is_scheduled_mode ) {
return new WP_Error(
'woocommerce_rest_analytics_import_immediate_mode',
__( 'Manual import is not available in immediate mode. Imports happen automatically.', 'woocommerce' ),
array( 'status' => 400 )
);
}
// Check if an import is already in progress or due to run soon.
if ( $this->is_import_in_progress_or_due() ) {
return new WP_Error(
'woocommerce_rest_analytics_import_in_progress',
__( 'A batch import is already in progress or scheduled to run soon. Please wait for it to complete before triggering a new import.', 'woocommerce' ),
array( 'status' => 400 )
);
}
// Trigger the batch import immediately by rescheduling the recurring processor.
// This unschedules the current recurring action and reschedules it to run now.
$action_hook = OrdersScheduler::get_action( OrdersScheduler::PROCESS_PENDING_ORDERS_BATCH_ACTION );
if ( ! is_string( $action_hook ) ) {
return new WP_Error(
'woocommerce_rest_analytics_import_invalid_action',
__( 'Invalid action hook for batch import.', 'woocommerce' ),
array( 'status' => 500 )
);
}
WC()->queue()->cancel_all( $action_hook, array(), (string) OrdersScheduler::$group );
OrdersScheduler::schedule_recurring_batch_processor();
return rest_ensure_response(
array(
'success' => true,
'message' => __( 'Batch import triggered successfully.', 'woocommerce' ),
)
);
}
/**
* Re-schedule imports for orders that previously failed.
*
* Order IDs whose orders no longer exist are pruned (they can never import
* successfully). Orders with an import already pending are skipped and
* reported separately, so repeated requests don't claim to schedule new
* work. The remaining IDs stay recorded until their import succeeds, so a
* retry that fails again remains visible.
*
* @param \WP_REST_Request<array<string, mixed>> $request Full details about the request.
* @return \WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function retry_failed_imports( $request ) {
$failed = OrdersScheduler::get_failed_order_imports();
if ( empty( $failed['ids'] ) ) {
return new WP_Error(
'woocommerce_rest_analytics_no_failed_imports',
__( 'There are no failed order imports to retry.', 'woocommerce' ),
array( 'status' => 400 )
);
}
$retried_count = 0;
$pruned_count = 0;
$already_scheduled_count = 0;
$error_count = 0;
foreach ( $failed['ids'] as $order_id ) {
if ( ! wc_get_order( $order_id ) ) {
OrdersScheduler::clear_failed_order_import( $order_id );
++$pruned_count;
continue;
}
// schedule_action() silently no-ops when the same import is
// already pending, so check first to report an accurate count.
if ( OrdersScheduler::has_existing_jobs( 'import', array( $order_id ) ) ) {
++$already_scheduled_count;
continue;
}
try {
OrdersScheduler::schedule_action( 'import', array( $order_id ) );
++$retried_count;
} catch ( \Throwable $e ) {
// schedule_action() may run the import synchronously (e.g. when
// Action Scheduler is unavailable); a failing order must not
// abort the whole retry request.
++$error_count;
wc_get_logger()->error(
sprintf( 'Failed to schedule analytics re-import for order %d: %s', $order_id, $e->getMessage() ),
array( 'source' => 'wc-analytics-order-import' )
);
}
}
// Nothing was scheduled and nothing is pending: surface the failure
// instead of reporting success for work that didn't happen.
if ( 0 === $retried_count && 0 === $already_scheduled_count && $error_count > 0 ) {
return new WP_Error(
'woocommerce_rest_analytics_retry_failed',
__( 'The failed orders could not be scheduled for re-import. Check the order import log for details.', 'woocommerce' ),
array( 'status' => 500 )
);
}
if ( $retried_count > 0 ) {
$message = sprintf(
/* translators: %d: number of orders scheduled for re-import */
_n( 'Re-import scheduled for %d order.', 'Re-import scheduled for %d orders.', $retried_count, 'woocommerce' ),
$retried_count
);
} elseif ( $already_scheduled_count > 0 ) {
$message = __( 'Re-import is already scheduled for the previously failed orders.', 'woocommerce' );
} else {
$message = __( 'No orders were scheduled for re-import. The previously failed orders no longer exist.', 'woocommerce' );
}
if ( $error_count > 0 ) {
$message .= ' ' . sprintf(
/* translators: %d: number of orders that could not be scheduled for re-import */
_n( '%d order could not be scheduled. Check the order import log for details.', '%d orders could not be scheduled. Check the order import log for details.', $error_count, 'woocommerce' ),
$error_count
);
}
return rest_ensure_response(
array(
'success' => true,
'message' => $message,
'retried_count' => $retried_count,
'pruned_count' => $pruned_count,
'already_scheduled_count' => $already_scheduled_count,
'error_count' => $error_count,
)
);
}
/**
* Get the schema for the retry-failed endpoint, conforming to JSON Schema.
*
* @return array
*/
public function get_retry_failed_schema() {
$schema = array(
'$schema' => 'https://json-schema.org/draft-04/schema#',
'title' => 'analytics_import_retry_failed',
'type' => 'object',
'properties' => array(
'success' => array(
'type' => 'boolean',
'description' => __( 'Whether the retry was scheduled successfully.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'message' => array(
'type' => 'string',
'description' => __( 'Result message.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'retried_count' => array(
'type' => 'integer',
'description' => __( 'Number of orders scheduled for re-import.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'pruned_count' => array(
'type' => 'integer',
'description' => __( 'Number of failed records removed because their orders no longer exist.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'already_scheduled_count' => array(
'type' => 'integer',
'description' => __( 'Number of orders skipped because their re-import is already pending.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'error_count' => array(
'type' => 'integer',
'description' => __( 'Number of orders that could not be scheduled for re-import.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
),
);
return $this->add_additional_fields_schema( $schema );
}
/**
* Check if scheduled import is enabled.
*
* Delegates to OrdersScheduler so the API reflects the same mode the
* scheduler actually runs in (feature flag check + legacy option fallback).
*
* @return bool
*/
private function is_scheduled_import_enabled() {
return OrdersScheduler::is_scheduled_import_enabled();
}
/**
* Get the next scheduled time for the batch processor.
*
* @return string|null Datetime string in site timezone or null if not scheduled.
*/
private function get_next_scheduled_time() {
$action_hook = OrdersScheduler::get_action( OrdersScheduler::PROCESS_PENDING_ORDERS_BATCH_ACTION );
if ( ! is_string( $action_hook ) ) {
return null;
}
$next_time = WC()->queue()->get_next( $action_hook, array(), (string) OrdersScheduler::$group );
if ( ! $next_time ) {
return null;
}
// Convert UTC timestamp to site timezone.
return get_date_from_gmt( $next_time->format( 'Y-m-d H:i:s' ), 'Y-m-d H:i:s' );
}
/**
* Get the schema for the status endpoint, conforming to JSON Schema.
*
* @return array
*/
public function get_status_schema() {
$schema = array(
'$schema' => 'https://json-schema.org/draft-04/schema#',
'title' => 'analytics_import_status',
'type' => 'object',
'properties' => array(
'mode' => array(
'type' => 'string',
'enum' => array( 'scheduled', 'immediate' ),
'description' => __( 'Current import mode.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'last_processed_date' => array(
'type' => array( 'string', 'null' ),
'description' => __( 'Last processed order date (null in immediate mode).', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'next_scheduled' => array(
'type' => array( 'string', 'null' ),
'description' => __( 'Next scheduled import time (null in immediate mode).', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'import_in_progress_or_due' => array(
'type' => array( 'boolean', 'null' ),
'description' => __( 'Whether a batch import is currently running or scheduled to run within the next minute (null in immediate mode).', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'failed_count' => array(
'type' => 'integer',
'description' => __( 'Number of orders that failed analytics import and are pending retry.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'failed_overflow_count' => array(
'type' => 'integer',
'description' => __( 'Number of failed order IDs dropped because the stored list reached its limit.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
),
);
return $this->add_additional_fields_schema( $schema );
}
/**
* Get the schema for the trigger endpoint, conforming to JSON Schema.
*
* @return array
*/
public function get_trigger_schema() {
$schema = array(
'$schema' => 'https://json-schema.org/draft-04/schema#',
'title' => 'analytics_import_trigger',
'type' => 'object',
'properties' => array(
'success' => array(
'type' => 'boolean',
'description' => __( 'Whether the trigger was successful.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
'message' => array(
'type' => 'string',
'description' => __( 'Result message.', 'woocommerce' ),
'context' => array( 'view' ),
'readonly' => true,
),
),
);
return $this->add_additional_fields_schema( $schema );
}
/**
* Check if a batch import is currently in progress or due to run soon.
*
* @return bool True if a batch import is in progress or scheduled to run within the next minute, false otherwise.
*/
private function is_import_in_progress_or_due() {
$hook = OrdersScheduler::get_action( OrdersScheduler::PROCESS_PENDING_ORDERS_BATCH_ACTION );
if ( ! is_string( $hook ) ) {
return false;
}
// Check for actions with 'in-progress' status.
$in_progress_actions = WC()->queue()->search(
array(
'hook' => $hook,
'status' => 'in-progress',
'per_page' => 1,
),
'ids'
);
if ( ! empty( $in_progress_actions ) ) {
return true;
}
// Check if the next scheduled import is due within 1 minute.
$next_scheduled = WC()->queue()->get_next( $hook, array(), (string) OrdersScheduler::$group );
if ( $next_scheduled ) {
$time_until_next = $next_scheduled->getTimestamp() - time();
// Consider it "due" if it's scheduled to run within the next 60 seconds.
if ( $time_until_next <= MINUTE_IN_SECONDS ) {
return true;
}
}
return false;
}
}
