`wc_get_orders()` 和订单查询

wc_get_orders() 和 WC_Order_Query 提供了从数据库检索订单的标准方法，类似于 WordPress 的 get_posts() 和 WP_Query，但专门用于订单。

插件和主题的开发者应避免编写自定义的 WordPress 查询或直接的 SQL 语句，因为 WordPress 或 WooCommerce 数据库的更改可能会导致问题。 这些 API 提供了最佳实践，并且是获取 WooCommerce 中订单的未来兼容方式。

基本用法

示例

以下是一些示例：

// 获取名为 John 且于 2016 年付款的订单。
$orders = wc_get_orders(
    array(
        'billing_first_name' => 'John',
        'date_paid'          => '2016-01-01...2016-12-31',
    )
);

// 获取 10 个最近的订单 ID。
$query = new WC_Order_Query(
    array(
        'limit'   => 10,
        'orderby' => 'date',
        'order'   => 'DESC',
        'return'  => 'ids',
    )
);
$orders = $query->get_orders();

// 获取电子邮件为 'woocommerce@woocommerce.com' 的客户的订单。
$query = new WC_Order_Query();
$query->set( 'customer', 'woocommerce@woocommerce.com' );
$orders = $query->get_orders();

请注意，wc_get_orders() 主要是 WC_Order_Query::get_orders() 的一个快捷方式。

最佳实践

• 避免直接的数据库查询，而应使用 wc_get_orders()。
• 如果您的代码需要支持旧版本，请在启用和禁用 HPOS 时进行彻底测试。
• 使用特定的参数来限制结果并提高性能。
• 对于大型结果集，请考虑使用 limit 和 offset 进行分页。
• 在适当的情况下缓存结果。
• 对于复杂的过滤要求，请利用自 8.2 起在运行 HPOS 的站点上提供的新的查询参数 meta_query、field_query 和 date_query。

API 参考

以下是可与这些函数一起使用的查询参数/参数。

查询参数参考

General

示例

// 获取最近修改的订单。
$args = array(
    'orderby' => 'modified',
    'order' => 'DESC',
);
$orders = wc_get_orders( $args );

// 获取一些随机订单。
$orders = wc_get_orders( array( 'orderby' => 'rand' ) );

// 仅返回订单 ID。
$orders = wc_get_orders( array( 'return' => 'ids' ) );

// 获取处理中和待处理的订单。
$args = array(
    'status' => array( 'wc-processing', 'wc-on-hold' ),
);
$orders = wc_get_orders( $args );

// 获取过去 24 小时的退款订单。
$args = array(
    'type'         => 'shop_order_refund',
    'date_created' => '>' . ( time() - DAY_IN_SECONDS ),
);
$orders = wc_get_orders( $args );

// 获取在 WooCommerce 2.6.14 版本创建并通过网站结账的订单。
$args = array(
    'version'     => '2.6.14',
    'created_via' => 'checkout',
);
$orders = wc_get_orders( $args );

// 获取父帖子 ID 为 20 且不是订单 12 的订单。
$args = array(
    'parent'  => 20,
    'exclude' => array( 12 ),
);
$orders = wc_get_orders( $args );

分页

示例

// 获取最新的 3 个订单。
$orders = wc_get_orders( array( 'limit' => 3 ) );

// 前 3 个订单。
$args = array(
    'limit' => 3,
    'paged' => 1,
);
$page_1_orders = wc_get_orders( $args );

// 后 3 个订单。
$args = array(
    'limit' => 3,
    'paged' => 2,
);
$page_2_orders = wc_get_orders( $args );

// 获取包含关于结果的额外信息的订单。
$results = wc_get_orders( array( 'paginate' => true ) );
echo $results->total . " 个订单已找到\n";
echo '第 1 页，共 ' . $results->max_num_pages . " 页\n";
echo '第一个订单 ID 是: ' . $results->orders[0]->get_id() . "\n";

支付和金额

示例

// 获取使用 USD 支付的订单。
$orders = wc_get_orders( array( 'currency' => 'USD' ) );

// 获取使用支票支付的订单。
$orders = wc_get_orders( array( 'payment_method' => 'cheque' ) );

// 获取折扣总额为 20.00 的订单。
$orders = wc_get_orders( array( 'discount_total' => 20.00 ) );

客户

示例

// 获取客户电子邮件为 'woocommerce@woocommerce.com' 的订单。
$orders = wc_get_orders( array( 'customer' => 'woocommerce@woocommerce.com' ) );

// 获取客户 ID 为 12 的订单。
$orders = wc_get_orders( array( 'customer_id' => 12 ) );

账单和配送

示例

// 获取来自美国的订单。
$orders = wc_get_orders( array( 'billing_country' => 'US' ) );

// 获取名为 Bill Evans 的用户的订单。
$args = array(
    'billing_first_name' => 'Bill',
    'billing_last_name'  => 'Evans',
);
$orders = wc_get_orders( $args );

日期

日期参数接收以下标准格式的值，允许更灵活的查询。

标准格式

• YYYY-MM-DD - 匹配该站点时区内某一天内的订单。
• >YYYY-MM-DD - 匹配该站点时区内该一天之后的订单。
• >=YYYY-MM-DD - 匹配该站点时区内该一天及其之后的所有订单。
• <YYYY-MM-DD - 匹配该站点时区内该一天之前的订单。
• <=YYYY-MM-DD - 匹配该站点时区内该一天及其之前的订单。
• YYYY-MM-DD...YYYY-MM-DD - 匹配该站点时区内某一天及其之间所有订单。
• TIMESTAMP - 匹配 UTC 时区内某一个秒的订单。
• >TIMESTAMP - 匹配 UTC 时区内该一个秒之后的订单。
• >=TIMESTAMP - 匹配 UTC 时区内该一个秒及其之后的所有订单。
• <TIMESTAMP - 匹配 UTC 时区内该一个秒之前的订单。
• <=TIMESTAMP - 匹配 UTC 时区内该一个秒及其之前的订单。
• TIMESTAMP...TIMESTAMP - 匹配 UTC 时区内某一个秒及其之间所有订单。

示例

// 获取 2016 年 2 月 12 日已支付的订单。
$orders = wc_get_orders( array( 'date_paid' => '2016-02-12' ) );

// 获取创建于过去一小时内的订单。
$args = array(
    'date_created' => '<' . ( time() - HOUR_IN_SECONDS ),
);
$orders = wc_get_orders( $args );

// 获取 2017 年 5 月 16 日 21:46:17 UTC 到 2017 年 5 月 17 日 12:46:17 UTC 之间的已完成订单。
$args = array(
    'date_completed' => '1494938777...1494971177',
);
$orders = wc_get_orders( $args );

元数据

有关更多详细信息和示例，请参阅 HPOS 订单查询 指南。

:::警告

只有当 HPOS 是配置的订单数据存储时（自 WooCommerce 8.2 以来为默认设置），才支持 meta_query。

在使用之前，请使用 OrderUtil::custom_orders_table_usage_is_enabled() 检查是否已启用。 :::

示例

// 具有元数据 'custom_field' 设置为 'some_value' 且元数据 'weight' 大于 '50' 的订单。
$orders = wc_get_orders(
    array(
        'meta_query' => array(
            array(
                'key'     => 'custom_field',
                'value'   => 'some_value',
                'compare' => '='
            ),
            array(
                'key'     => 'weight',
                'value'   => '50',
                'compare' => '>='
            ),
            'relation' => 'AND'
        )
    )
);

订单字段

有关更多详情和示例，请参考 HPOS 订单查询 指南。

:::警告

field_query 的支持仅在 HPOS 作为配置的订单数据存储时可用（自 WooCommerce 8.2 以来为默认设置）。

在使用前，请使用 OrderUtil::custom_orders_table_usage_is_enabled() 检查是否已启用。 :::

示例

// 获取总额大于 100 或来自纽约市的订单。
$orders = wc_get_orders(
    array(
        'field_query' => array(
            array(
                'field' => 'total',
                'value' => 100,
                'compare' => '>'
            ),
            array(
                'field' => 'billing_city',
                'value' => 'New York',
                'compare' => '='
            ),
            'relation' => 'OR'
        )
    )
);

高级日期查询

有关更多详情和示例，请参考 HPOS 订单查询 指南。

:::警告

date_query 的支持仅在 HPOS 作为配置的订单数据存储时可用（自 WooCommerce 8.2 以来为默认设置）。

在使用前，请使用 OrderUtil::custom_orders_table_usage_is_enabled() 检查是否已启用。 :::

示例

// 示例：获取过去一个月内已支付且创建时间在中午之前的订单。

$orders = wc_get_orders(
    array(
        'date_query' => array(
            'relation' => 'AND',
            array(
                'column'  => 'date_created_gmt',
                'hour'    => 12,
                'compare' => '<'
            ),
            array(
                'column'  => 'date_paid_gmt',
                'after'   => '1 month ago',
            ),
        ),
    )
);

添加对自定义参数的支持

开发者可以通过过滤生成的查询，为 wc_get_orders() 和 WC_Order_Query 添加对自定义参数的支持，从而扩展查询功能。

WooCommerce 当前支持两种订单存储机制：HPOS（默认）和旧版（使用 WordPress 帖子和元数据），每种机制都有自己的钩子，用于过滤生成的查询：

• (HPOS) woocommerce_order_query_args 用于将参数转换为现有参数，或者 woocommerce_orders_table_query_clauses 用于编写自己的 SQL。
• (旧版) woocommerce_order_data_store_cpt_get_orders_query 用于将参数转换为 WP_Query 参数。

/**
 * 示例：处理自定义 'customvar' 查询变量，以获取具有 'customvar' 元数据的订单。
 */
use Automattic\WooCommerce\Utilities\OrderUtil;

// HPOS 版本。
function handle_custom_query_var_hpos( $query_args ) {
    if ( ! empty( $query_args['customvar'] ) ) {
        if ( ! isset( $query_args['meta_query'] ) ) {
            $query_args['meta_query'] = array();
        }

		$query_args['meta_query'][] = array(
			'key'   => 'customvar',
			'value' => esc_attr( $query_args['customvar'] ),
		);

        unset( $query_args['customvar'] );
    }


    return $query_args;
}

// 旧版版本。
function handle_custom_query_var_legacy( $query, $query_vars ) {
	if ( ! empty( $query_vars['customvar'] ) ) {
		$query['meta_query'][] = array(
			'key'   => 'customvar',
			'value' => esc_attr( $query_vars['customvar'] ),
		);
	}

	return $query;
}

if ( OrderUtil::custom_orders_table_usage_is_enabled() ) {
    // HPOS。
    add_filter(
        'woocommerce_order_query_args',
        'handle_custom_query_var_hpos'
    );
} else {
    // 旧版支持。
    add_filter(
        'woocommerce_order_data_store_cpt_get_orders_query',
        'handle_custom_query_var_legacy',
        10,
        2
    );
}

用法：

$orders = wc_get_orders( array( 'customvar' => 'somevalue' ) );