Как использовать хук WooCommerce 'woocommerce_product_query' для кастомизации списка товаров

Что делает хук 'woocommerce_product_query' и зачем он нужен?

Хук woocommerce_product_query позволяет вмешаться в основной WP_Query, который формирует список товаров на страницах архива WooCommerce, таких как каталог, категории или поиск. С его помощью можно тонко настроить выборку товаров: изменить сортировку, отфильтровать по метаданным, ограничить по таксономиям и прочее.

Диагностика: когда использовать 'woocommerce_product_query'?

Если стандартные фильтры WooCommerce или параметры запроса не позволяют добиться нужной выборки товаров, например:

• нужно исключить определённые товары по мета-данным;
• отфильтровать товары по пользовательским условиям;
• изменить сортировку с учётом кастомных полей;
• добавить сложные условия выборки, не затрагивая другие запросы.

— тогда woocommerce_product_query станет правильным инструментом.

Пошаговое решение: пример настройки кастомной выборки товаров

Допустим, нужно исключить из каталога товары с мета-полем _exclude_from_catalog равным yes.

Шаг 1: Подключаем хук в functions.php или в плагине

add_action('woocommerce_product_query', 'custom_exclude_products_from_catalog');
function custom_exclude_products_from_catalog(\WC_Product_Query $query) {
    $meta_query = $query->get('meta_query');
    if (!is_array($meta_query)) {
        $meta_query = [];
    }
    $meta_query[] = [
        'key' => '_exclude_from_catalog',
        'value' => 'yes',
        'compare' => '!='
    ];
    $query->set('meta_query', $meta_query);
}

Шаг 2: Проверяем, что фильтрация сработала

Перейдите на страницу каталога товаров и убедитесь, что товары с _exclude_from_catalog = yes не отображаются. Для теста можно временно вывести ID товаров в цикле или использовать var_dump внутри функции.

Проверка результата после внедрения

• Откройте страницу архива товаров;
• Проверьте, что товары с указанным мета-полем исключены;
• Если есть кэш, очистите его, чтобы изменения отобразились;
• Используйте var_dump($query->query_vars) для отладки параметров запроса;
• Проверьте, что другие страницы и запросы WooCommerce не ломаются.

Частые ошибки и как их исправить

• Использование хука 'pre_get_posts' вместо 'woocommerce_product_query': приводит к нежелательному изменению всех запросов — используйте специализированный хук.
• Перезапись meta_query без слияния: в примере мы сначала получаем текущий meta_query и добавляем к нему новый, чтобы не потерять другие условия.
• Неправильный ключ мета-поля: всегда проверяйте правильное написание ключа и наличие значения в базе.
• Изменения в админке: хук влияет только на фронтенд-запросы WooCommerce, для админки нужны другие подходы.

Практические советы по безопасности и производительности

• Не используйте тяжелые запросы внутри хука, чтобы не замедлить загрузку страниц.
• Кэшируйте результаты, если фильтрация сложная и ресурсоёмкая.
• Тестируйте на staging-среде, чтобы избежать ошибок на живом сайте.
• Используйте WC_Product_Query вместо прямого WP_Query для совместимости с WooCommerce.

Сравнение подходов кастомизации выборки товаров