<?php
/**
* Orders query ability definition file.
*/
declare( strict_types=1 );
namespace Automattic\WooCommerce\Internal\Abilities\Domain;
use Automattic\WooCommerce\Abilities\AbilityDefinition;
use Automattic\WooCommerce\Abilities\ExtensibleAbilities;
use Automattic\WooCommerce\Internal\Abilities\AbilitiesLoader;
use Automattic\WooCommerce\Internal\Abilities\Domain\Traits\OrderAbilityTrait;
use Automattic\WooCommerce\Utilities\OrderUtil;
defined( 'ABSPATH' ) || exit;
/**
* Registers the WooCommerce orders query ability.
*/
class OrdersQuery extends AbstractDomainAbility implements AbilityDefinition {
use OrderAbilityTrait;
/**
* Get the ability name.
*
* @return string
*
* @since 10.9.0
*/
public static function get_name(): string {
return 'woocommerce/orders-query';
}
/**
* Get the ability registration arguments.
*
* @return array
*
* @since 10.9.0
*/
public static function get_registration_args(): array {
return array(
'label' => __( 'Query orders', 'woocommerce' ),
'description' => __(
'Find orders by ID or common order filters.',
'woocommerce'
),
'category' => 'woocommerce',
'input_schema' => self::get_input_schema(),
'output_schema' => self::get_collection_output_schema( 'orders', self::get_order_output_schema() ),
'execute_callback' => array( __CLASS__, 'execute' ),
'permission_callback' => array( __CLASS__, 'can_query_orders' ),
'meta' => array(
'show_in_rest' => true,
'mcp' => array(
'public' => true,
'type' => 'tool',
),
'annotations' => array(
'readonly' => true,
'idempotent' => true,
'destructive' => false,
),
),
);
}
/**
* Query orders.
*
* @param array $input Ability input.
* @return array|\WP_Error
*
* @since 10.9.0
*/
public static function execute( array $input ) {
$include_line_items = (bool) ( $input['include_line_items'] ?? false );
if ( ! empty( $input['id'] ) && ! empty( $input['filters'] ) ) {
return new \WP_Error(
'woocommerce_ability_filters_with_id',
__( 'Send either an id or filters, not both.', 'woocommerce' ),
array( 'status' => 400 )
);
}
if ( ! empty( $input['id'] ) ) {
$order = self::get_order_from_input( $input );
if ( is_wp_error( $order ) ) {
return $order;
}
return array(
'orders' => array( self::format_order_for_response( $order, $include_line_items ) ),
'total_pages' => 1,
'page' => 1,
'per_page' => 1,
);
}
$page = (int) ( $input['page'] ?? 1 );
$per_page = (int) ( $input['per_page'] ?? 10 );
$args = array(
'limit' => $per_page,
'page' => $page,
'paginate' => true,
'return' => 'objects',
'type' => self::get_order_type_from_input( $input ),
);
foreach ( array( 'billing_email', 'order' ) as $field ) {
if ( ! empty( $input[ $field ] ) && is_scalar( $input[ $field ] ) ) {
$args[ $field ] = wc_clean( (string) $input[ $field ] );
}
}
$status = $input['status'] ?? array();
if ( is_string( $status ) && '' !== $status ) {
$args['status'] = array( wc_clean( $status ) );
} elseif ( is_array( $status ) && ! empty( $status ) ) {
$args['status'] = array_map( 'wc_clean', array_filter( array_map( 'strval', $status ), static fn ( string $slug ): bool => '' !== $slug ) );
}
if ( empty( $args['status'] ) ) {
$args['status'] = 'shop_order' === $args['type'] ? self::get_allowed_order_status_slugs() : self::get_query_order_status_slugs();
}
$args['status'] = array_map( array( __CLASS__, 'prepare_status_arg' ), (array) $args['status'] );
if ( ! empty( $input['orderby'] ) && is_scalar( $input['orderby'] ) ) {
$orderby = sanitize_text_field( (string) $input['orderby'] );
$args['orderby'] = self::prepare_orderby_arg( $orderby );
}
foreach ( array( 'customer_id', 'parent' ) as $field ) {
if ( isset( $input[ $field ] ) ) {
$args[ $field ] = (int) $input[ $field ];
}
}
if ( ! empty( $input['exclude'] ) && is_array( $input['exclude'] ) ) {
$args['exclude'] = array_map( 'intval', $input['exclude'] );
}
foreach ( array( 'date_after', 'date_before' ) as $field ) {
if ( ! empty( $input[ $field ] ) ) {
$args[ $field ] = wc_clean( $input[ $field ] );
}
}
$modified_date_query = self::build_modified_date_query_arg( $input );
if ( null !== $modified_date_query ) {
$args['date_query'][] = $modified_date_query;
}
$extension_args = ExtensibleAbilities::get_query_args( 'order', $input );
if ( is_wp_error( $extension_args ) ) {
return $extension_args;
}
if ( isset( $extension_args['post__not_in'] ) ) {
$args['exclude'] = array_merge( (array) ( $args['exclude'] ?? array() ), $extension_args['post__not_in'] );
unset( $extension_args['post__not_in'] );
}
if ( isset( $extension_args['post__in'] ) && ! empty( $args['exclude'] ) ) {
$include = array_values( array_diff( $extension_args['post__in'], (array) $args['exclude'] ) );
$extension_args['post__in'] = empty( $include ) ? array( 0 ) : $include;
}
if ( OrderUtil::custom_orders_table_usage_is_enabled() ) {
$args = array_merge_recursive( $args, $extension_args );
} else {
$args[ AbilitiesLoader::EXTENSION_QUERY_VAR ] = $extension_args;
}
$results = wc_get_orders( $args );
$orders = is_object( $results ) && isset( $results->orders ) ? $results->orders : array();
$orders = array_values(
array_filter(
$orders,
static function ( $order ): bool {
return $order instanceof \WC_Order;
}
)
);
$pages = is_object( $results ) && isset( $results->max_num_pages ) ? (int) $results->max_num_pages : ( count( $orders ) > 0 ? 1 : 0 );
return array(
'orders' => array_map(
static function ( $order ) use ( $include_line_items ) {
return self::format_order_for_response( $order, $include_line_items );
},
$orders
),
'total_pages' => $pages,
'page' => $page,
'per_page' => $per_page,
);
}
/**
* Check order read access.
*
* @param mixed $input Ability input.
* @return bool
*
* @since 10.9.0
*/
public static function can_query_orders( $input = array() ): bool {
$order_id = self::get_id_from_input( $input );
if ( $order_id > 0 ) {
return self::check_order_permission( $order_id, 'read' );
}
$type = is_array( $input ) ? self::get_order_type_from_input( $input ) : 'shop_order';
return wc_rest_check_post_permissions( $type, 'read' );
}
/**
* Order type from the input, or `shop_order` when the input has no known type.
*
* @param array $input Ability input.
* @return string
*/
private static function get_order_type_from_input( array $input ): string {
$type = $input['type'] ?? 'shop_order';
return is_string( $type ) && in_array( $type, self::get_order_type_slugs(), true ) ? $type : 'shop_order';
}
/**
* Get the ability input schema.
*
* @return array
*/
private static function get_input_schema(): array {
$schema = array(
'type' => 'object',
'properties' => array(
'id' => array(
'type' => 'integer',
'minimum' => 1,
),
'type' => array(
'type' => 'string',
'description' => __( 'Order type to list. Extensions can register more order types. Defaults to shop_order.', 'woocommerce' ),
'enum' => self::get_order_type_slugs(),
'default' => 'shop_order',
),
'status' => array(
'description' => __( 'Filter by one order status slug, or a list of slugs, without the wc- prefix. Custom order types may add their own statuses.', 'woocommerce' ),
'anyOf' => array(
array(
'type' => 'string',
'enum' => self::get_query_order_status_slugs(),
),
array(
'type' => 'array',
'items' => array(
'type' => 'string',
'enum' => self::get_query_order_status_slugs(),
),
),
),
),
'customer_id' => array(
'type' => 'integer',
'description' => __( 'Filter by customer ID. Use 0 to filter guest orders.', 'woocommerce' ),
'minimum' => 0,
),
'billing_email' => array(
'type' => 'string',
'format' => 'email',
),
'parent' => array(
'type' => 'integer',
'description' => __( 'Filter by parent order ID.', 'woocommerce' ),
'minimum' => 1,
),
'exclude' => array(
'type' => 'array',
'description' => __( 'Order IDs to exclude from the results.', 'woocommerce' ),
'items' => array(
'type' => 'integer',
'minimum' => 1,
),
),
'date_after' => array(
'type' => 'string',
'description' => __( 'Filter orders created after this date/time.', 'woocommerce' ),
'format' => 'date-time',
),
'date_before' => array(
'type' => 'string',
'description' => __( 'Filter orders created before this date/time.', 'woocommerce' ),
'format' => 'date-time',
),
'modified_after' => array(
'type' => 'string',
'description' => __( 'Filter orders modified after this date/time.', 'woocommerce' ),
'format' => 'date-time',
),
'modified_before' => array(
'type' => 'string',
'description' => __( 'Filter orders modified before this date/time.', 'woocommerce' ),
'format' => 'date-time',
),
'orderby' => array(
'type' => 'string',
'enum' => array( 'id', 'date', 'date_modified', 'total' ),
),
'order' => array(
'type' => 'string',
'enum' => array( 'asc', 'desc' ),
),
'include_line_items' => array(
'type' => 'boolean',
'description' => __(
'Whether to include order line items in each returned order. Defaults to false.',
'woocommerce'
),
'default' => false,
),
'page' => array(
'type' => 'integer',
'default' => 1,
'minimum' => 1,
),
'per_page' => array(
'type' => 'integer',
'default' => 10,
'minimum' => 1,
'maximum' => 100,
),
),
'additionalProperties' => false,
'default' => array(),
);
return ExtensibleAbilities::add_query_filters_schema( $schema, 'order' );
}
/**
* Build a modified-date query arg from modified_after/modified_before input.
*
* @param array $input Ability input.
* @return array|null
*/
private static function build_modified_date_query_arg( array $input ): ?array {
$after = isset( $input['modified_after'] ) && is_string( $input['modified_after'] ) ? sanitize_text_field( $input['modified_after'] ) : '';
$before = isset( $input['modified_before'] ) && is_string( $input['modified_before'] ) ? sanitize_text_field( $input['modified_before'] ) : '';
if ( '' === $after && '' === $before ) {
return null;
}
$after_timestamp = '' !== $after ? self::prepare_date_time_for_query( $after ) : null;
$before_timestamp = '' !== $before ? self::prepare_date_time_for_query( $before ) : null;
if (
( '' !== $after && null === $after_timestamp )
|| ( '' !== $before && null === $before_timestamp )
) {
return null;
}
$date_query = array(
'column' => 'post_modified_gmt',
'inclusive' => false,
);
if ( null !== $after_timestamp ) {
$date_query['after'] = self::format_timestamp_for_date_query( $after_timestamp );
}
if ( null !== $before_timestamp ) {
$date_query['before'] = self::format_timestamp_for_date_query( $before_timestamp );
}
return $date_query;
}
/**
* Prepare a date-time string as a timestamp for second-precision order queries.
*
* @param string $date_time Date-time string.
* @return int|null
*/
private static function prepare_date_time_for_query( string $date_time ): ?int {
try {
return wc_string_to_datetime( $date_time )->getTimestamp();
} catch ( \Exception $exception ) {
return null;
}
}
/**
* Format a timestamp for a GMT date query.
*
* @param int $timestamp Timestamp.
* @return string
*/
private static function format_timestamp_for_date_query( int $timestamp ): string {
return gmdate( 'Y-m-d H:i:s', $timestamp );
}
/**
* Add the `wc-` prefix to a status of another order type that is registered
* with it. The order query adds the prefix to order statuses itself, so those
* stay without it, as `woocommerce_order_query_args` callbacks expect.
*
* @param string $status Status slug without the `wc-` prefix.
* @return string
*/
private static function prepare_status_arg( string $status ): string {
$prefixed = 'wc-' . $status;
return ! wc_is_order_status( $prefixed ) && in_array( $prefixed, get_post_stati(), true ) ? $prefixed : $status;
}
/**
* Prepare orderby values for wc_get_orders across HPOS and legacy storage.
*
* Values not present in the map are already accepted by wc_get_orders for
* both storage engines and pass through unchanged.
*
* @param string $orderby Input orderby value.
* @return string
*/
private static function prepare_orderby_arg( string $orderby ): string {
$orderby_map = array(
'id' => 'ID',
);
if ( 'date_modified' === $orderby ) {
return OrderUtil::custom_orders_table_usage_is_enabled() ? 'date_modified' : 'post_modified';
}
return $orderby_map[ $orderby ] ?? $orderby;
}
}