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

概要

woocommerce_valid_order_statuses_for_payment_complete フィルタは、WooCommerceプラグインにおいて、特定の注文ステータスを支払い完了として有効にするためのフックです。このフィルタを使用することで、デフォルトでは支払い完了と見なされない注文ステータスを、プラグイン開発者やサイト管理者が指定可能になります。

このフィルタは、以下のような機能を実装する際によく使われます。

特定のカスタム注文ステータスを支払い完了に持ち込む
新しい支払い方法が注文のステータスを変更できるようにする
条件に応じて複数の支払い完了ステータスを設定する
外部システムとの統合時に、特定の状態を完了として扱うよう設定する
テスト環境で独自の状態を支払い完了とする
管理者が容易にトラブルシューティングできるように、特定のステータスを設定する

構文

apply_filters( 'woocommerce_valid_order_statuses_for_payment_complete', $valid_order_statuses, $order );

パラメータ

$valid_order_statuses: 有効な注文ステータスの配列
$order: 現在の注文オブジェクト

戻り値

フィルタによって変更された有効な注文ステータスの配列

バージョン

WooCommerceバージョン: 3.0.0以上
WordPressバージョン: 4.0以上

サンプルコード

サンプルコード1

add_filter( 'woocommerce_valid_order_statuses_for_payment_complete', 'custom_valid_order_statuses' );

function custom_valid_order_statuses( $statuses ) {
    $statuses[] = 'on-hold';
    return $statuses;
}

このコードでは、on-hold ステータスを支払い完了として有効にします。

サンプルコード2

add_filter( 'woocommerce_valid_order_statuses_for_payment_complete', 'add_custom_order_status', 10, 2 );

function add_custom_order_status( $statuses, $order ) {
    if ( $order->get_payment_method() === 'custom_gateway' ) {
        $statuses[] = 'custom-status';
    }
    return $statuses;
}

このコードは、特定の支払い方法（custom_gateway）を選んだ場合に、custom-status を有効にします。

サンプルコード3

add_filter( 'woocommerce_valid_order_statuses_for_payment_complete', 'set_custom_status_for_testing', 20 );

function set_custom_status_for_testing( $statuses ) {
    $statuses[] = 'test-completed';
    return $statuses;
}

このコードでは、テスト環境において test-completed ステータスを支払い完了として認めます。

サンプルコード4

add_filter( 'woocommerce_valid_order_statuses_for_payment_complete', 'manage_subscription_order_status', 15, 2 );

function manage_subscription_order_status( $statuses, $order ) {
    if ( $order->get_type() === 'subscription' ) {
        $statuses[] = 'active';
    }
    return $statuses;
}

このコードは、サブスクリプションタイプの注文に対して、active ステータスを支払い完了ステータスに追加します。

サンプルコード5

add_filter( 'woocommerce_valid_order_statuses_for_payment_complete', 'guest_checkout_order_status', 10 );

function guest_checkout_order_status( $statuses ) {
    if ( isset( $_SESSION['guest_checkout'] ) && $_SESSION['guest_checkout'] ) {
        $statuses[] = 'guest-complete';
    }
    return $statuses;
}

このコードでは、ゲストチェックアウトを使用している場合、guest-complete ステータスを支払い完了として扱えるようにしています。

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

アクション	使用例
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

概要

構文