• File: OrdersQuery.php
  • Full Path: /home/slvgwrnz/public_html/wp-content/plugins/woocommerce/src/Internal/Abilities/Domain/OrdersQuery.php
  • Date Modified: 10/26/2026 10:38 AM
  • File size: 13.28 KB
  • MIME-type: text/x-php
  • Charset: utf-8
<?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;
	}
}