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

概要

woocommerce_trash_failed_orders_query_args は、WooCommerce プラグインにおけるフィルターフックの一つであり、失敗した注文をゴミ箱に移す際のクエリ引数を変更するために使用されます。このフィルタは、すでに失敗した注文だけを対象にクエリをカスタマイズし、不要なデータを除外するのに役立ちます。

このフィルタの主な用途は以下の通りです：

失敗した注文の取得におけるパフォーマンス向上。
管理画面で表示される失敗した注文の条件をカスタマイズ。
特定の条件に対して失敗した注文をフィルタリング。
メタデータに基づいて失敗した注文のクエリを調整。
プラグインとの互換性向上のためにクエリを拡張。
ユーザーインターフェースの整理のために情報を制限。

フィルタの構文

add_filter( 'woocommerce_trash_failed_orders_query_args', 'custom_modify_failed_orders_query_args' );

パラメータ

woocommerce_trash_failed_orders_query_args フィルタは、以下のパラメータを受け取ります：

$query_args (array): 失敗した注文をゴミ箱に移すための WP_Query 引数の配列。

戻り値

このフィルタは、変更後のクエリ引数の配列を返します。

使用可能なバージョン

WooCommerce バージョン: 3.0 以降
WordPress バージョン: 4.7 以降

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

アクション名	使用例
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_trash_failed_orders_query_args', 'limit_failed_orders_trash' );
function limit_failed_orders_trash( $query_args ) {
    $query_args['posts_per_page'] = 10; // 最大10件をゴミ箱に移動
    return $query_args;
}

このコードは、ゴミ箱に移動する失敗した注文の件数を最大 10 件に制限します。

サンプルコード 2: 特定のステータスの失敗した注文をフィルタリング

add_filter( 'woocommerce_trash_failed_orders_query_args', 'filter_failed_orders_by_status' );
function filter_failed_orders_by_status( $query_args ) {
    $query_args['post_status'] = 'wc-failed'; // wc-failed ステータスの注文のみ
    return $query_args;
}

このコードは、失敗した注文の中から、特定のステータス（wc-failed）の注文のみをゴミ箱に移動します。

サンプルコード 3: メタデータに基づくフィルタリング

add_filter( 'woocommerce_trash_failed_orders_query_args', 'meta_filter_failed_orders' );
function meta_filter_failed_orders( $query_args ) {
    $query_args['meta_query'] = [
        [
            'key'     => '_order_total',
            'value'   => 100,
            'compare' => '>',
        ],
    ];
    return $query_args;
}

このコードは、注文総額が 100 を超える失敗した注文のみをゴミ箱に移動します。

サンプルコード 4: カスタム投稿タイプの除外

add_filter( 'woocommerce_trash_failed_orders_query_args', 'exclude_custom_post_type' );
function exclude_custom_post_type( $query_args ) {
    $query_args['post_type'] = 'shop_order'; // shop_order のみを対象
    return $query_args;
}

このコードは、カスタム投稿タイプを除外し、shop_order の失敗した注文のみをゴミ箱に移動します。

サンプルコード 5: タイムスタンプによるフィルタリング

add_filter( 'woocommerce_trash_failed_orders_query_args', 'time_based_filtering' );
function time_based_filtering( $query_args ) {
    $query_args['date_query'] = [
        [
            'column' => 'post_date',
            'after'  => '30 days ago', // 30日より前の注文を除外
        ],
    ];
    return $query_args;
}

このコードは、30 日以上前の失敗した注文をゴミ箱に移動しないようにします。

各サンプルコードは、異なるユースケースを考慮した条件でwoocommerce_trash_failed_orders_query_args フィルターを適用しています。

概要