プラグインWooCommerceのwoocommerce_shortcode_products_queryフィルタの使用方法・解説

概要

woocommerce_shortcode_products_queryフィルタは、WooCommerceのショートコードによって生成された製品クエリを変更するために使用されます。このフィルタは、特定の条件や要件に応じて製品の取得方法をカスタマイズする際に非常に便利です。以下のような機能を実装する際によく使われます。

1. 特定のカテゴリーやタグを持つ製品の表示
2. 製品の価格帯によるフィルタリング
3. 製品の評価によるソート
4. 製品の在庫状況に基づく製品の除外
5. 製品のカスタムメタデータによるフィルタリング
6. 特定の製品属性による結果の絞り込み

構文

add_filter('woocommerce_shortcode_products_query', 'custom_function', 10, 3);

パラメータ

• $query_args (array): デフォルトのクエリ引数
• $atts (array): ショートコードの属性
• $shortcode (string): 使用されているショートコード名

戻り値

このフィルタは修正されたクエリ引数を返します。これにより、ショートコードで生成された製品リストの内容が変更されます。

使用可能なバージョン

• WooCommerceバージョン: 2.1以降
• WordPressバージョン: 4.0以降

この関数のアクションでの使用可能性

アクション	使用例
mu_plugin_loaded
registered_post_type
plugins_loaded
wp_roles_init
setup_theme
after_setup_theme
set_current_user
init
register_sidebar
wp_loaded
send_headers
parse_query
pre_get_posts
wp
template_redirect
get_header
wp_head

サンプルコード

サンプルコード1: カテゴリーをフィルタリングする

このサンプルコードは、特定のカテゴリー（例: “特別オファー”）に含まれる製品のみを取得するようにクエリを調整します。

add_filter('woocommerce_shortcode_products_query', 'filter_by_category', 10, 3);
function filter_by_category($query_args, $atts, $shortcode) {
    $query_args['tax_query'][] = array(
        'taxonomy' => 'product_cat',
        'field'    => 'slug',
        'terms'    => 'special-offers',
    );
    return $query_args;
}

（引用元: WooCommerce公式ドキュメント）

サンプルコード2: 製品の価格帯を指定する

このコードは、指定した価格帯の製品のみを表示します。

add_filter('woocommerce_shortcode_products_query', 'filter_by_price_range', 10, 3);
function filter_by_price_range($query_args, $atts, $shortcode) {
    $query_args['meta_query'][] = array(
        'key' => '_price',
        'value' => array(50, 100),
        'compare' => 'BETWEEN',
        'type' => 'NUMERIC'
    );
    return $query_args;
}

（引用元: WooCommerce公式ドキュメント）

サンプルコード3: 人気の製品をソートする

このサンプルコードは、人気のある製品（売上数が多い）を上位に表示します。

add_filter('woocommerce_shortcode_products_query', 'sort_by_popularity', 10, 3);
function sort_by_popularity($query_args, $atts, $shortcode) {
    $query_args['meta_key'] = 'total_sales';
    $query_args['orderby'] = 'meta_value_num';
    $query_args['order'] = 'DESC';
    return $query_args;
}

（引用元: WooCommerce公式ドキュメント）

サンプルコード4: カスタムメタデータでフィルタリングする

このコードは、特定のカスタムメタデータに基づいて製品をフィルタリングします。

add_filter('woocommerce_shortcode_products_query', 'filter_by_custom_meta', 10, 3);
function filter_by_custom_meta($query_args, $atts, $shortcode) {
    $query_args['meta_query'][] = array(
        'key' => 'custom_meta_key',
        'value' => 'custom_value',
        'compare' => '='
    );
    return $query_args;
}

（引用元: WooCommerce公式ドキュメント）

サンプルコード5: 在庫のない製品を除外する

このサンプルコードは、在庫がある製品のみを表示するフィルタリングを行います。

add_filter('woocommerce_shortcode_products_query', 'exclude_out_of_stock_products', 10, 3);
function exclude_out_of_stock_products($query_args, $atts, $shortcode) {
    $query_args['tax_query'][] = array(
        'taxonomy' => 'product_visibility',
        'field'    => 'name',
        'terms'    => 'outofstock',
        'operator' => 'NOT IN',
    );
    return $query_args;
}

（引用元: WooCommerce公式ドキュメント）