API для запросов заказов (HPOS)

С появлением HPOS в WooCommerce возможности работы с запросами стали шире. Теперь, помимо привычных API, появились новые функции, которые позволяют проще создавать сложные выборки заказов, включая работу с пользовательскими метаданными.

Все новые типы запросов реализованы как дополнительные аргументы функции wc_get_orders(). Они во многом повторяют подход WP_Query из WordPress. Их можно комбинировать с другими параметрами, чтобы создавать сложные запросы без написания SQL.

Новые типы запросов

Запросы по метаданным (meta_query)

В HPOS часть данных заказов была вынесена из метаданных в отдельные таблицы. Но оставшиеся метаданные (например, добавленные плагинами или вручную) по-прежнему можно использовать в запросах через параметр meta_query.

По сути, meta_query — это массив условий. Каждое условие может содержать:

• key — ключ метаданных
• value — значение
• compare — оператор сравнения (например: LIKE, BETWEEN и т.д.)
• type — тип данных для SQL

Можно объединять несколько условий через relation (AND или OR), чтобы строить более сложные запросы. Синтаксис такой же, как в WP_Query.

// Пример: получить все заказы, у которых есть мета-поле "color" (любое значение)
// и мета-поле "size", содержащее "small" (подойдут и "extra-small", и "small")

$orders = wc_get_orders(
    array(
        'meta_query' => array(
            array(
                'key' => 'color',
            ),
            array(
                'key'     => 'size',
                'value'   => 'small',
                'compare' => 'LIKE'
            ),
        ),
    )
);

Запросы по полям заказа (field_query)

Этот тип запроса похож на meta_query, но вместо key используется field.

Поле field — это любое свойство заказа, например: billing_first_name, total, order_key и другие.

Главное отличие от обычных параметров в том, что field_query позволяет использовать операторы сравнения и комбинировать условия.

// Пример. Для простых запросов лучше использовать параметры напрямую.

$orders = wc_get_orders(
    array(
        'billing_first_name' => 'Lauren',
        'order_key'          => 'my_order_key',
    )
);

$orders = wc_get_orders(
    array(
        'field_query' => array(
            array(
                'field' => 'billing_first_name',
                'value' => 'Lauren'
            ),
            array(
                'field' => 'order_key',
                'value' => 'my_order_key',
            )
        )
    )
);

Основное преимущество field_query проявляется в более сложных сценариях:

// Пример: получить все заказы, у которых сумма заказа или стоимость доставки меньше 5.0

$orders = wc_get_orders(
    array(
        'field_query' => array(
            'relation' => 'OR',
            array(
                'field'   => 'total',
                'value'   => '5.0',
                'compare' => '<',
            ),
            array(
                'field'   => 'shipping_total',
                'value'   => '5.0',
                'compare' => '<',
            ),
        )
    )
);

Запросы по дате (date_query)

Параметр date_query позволяет получать заказы, фильтруя их по связанным датам (date_completed, date_created, date_updated, date_paid) разными способами.

Синтаксис date_query полностью совместим с параметром date_query в WP_Query. Поэтому для примеров и подробностей можно использовать документацию WP_Query.

// Пример. Получить все заказы, оплаченные за последний месяц,
// которые были созданы до полудня (в любой день).

$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',
            ),
        ),
    )
);

Продвинутые примеры

// Получить заказы со статусом "Ожидает оплаты" или "На удержании",
// у которых мета-данные `weight` >= 50 и при этом задано `color` или `size`.

$query_args = array(
    'status' => array( 'pending', 'on-hold' ),
    'meta_query' => array(
        array(
            'key'     => 'weight',
            'value'   => '50',
            'compare' => '>=',
        ),
        array(
            'relation' => 'OR',
            array(
                'key'     => 'color',
                'compare' => 'EXISTS',
            ),
            array(
                'key'     => 'size',
                'compare' => 'EXISTS',
            )
        ),
    )
);

$orders = wc_get_orders( $query_args );

// Получить заказы, где имя в платёжных данных содержит "laur"
// (например, "lauren" или "laura"),
// а также где сумма заказа меньше 10.0 и сумма скидки >= 5.0.

$orders = wc_get_orders(
    array(
        'field_query' => array(
            array(
                'field'   => 'billing_first_name',
                'value'   => 'laur',
                'compare' => 'LIKE',
            ),
            array(
                'relation' => 'AND',
                array(
                    'field'   => 'total',
                    'value'   => '10.0',
                    'compare' => '<',
                    'type'    => 'NUMERIC',
                ),
                array(
                    'field'   => 'discount_total',
                    'value'   => '5.0',
                    'compare' => '>=',
                    'type'    => 'NUMERIC',
                )
            )
        ),
    )
);