WooCommerce 開発レビュースキル

概要

WooCommerce 8.2+ から現在の 10.x に対応した体系的な WooCommerce 開発レビュー。コア原則: WooCommerce は根本的なアーキテクチャの転換を経ています。HPOS（High-Performance Order Storage）は WC 8.2（2023年10月）以降新規ストアではデフォルトになっており、すべての拡張機能は CRUD API のみを使用する必要があります。モダン WooCommerce インストールではオーダーへの直接ポストアクセスは機能しません。

拡張機能は WC_Data CRUD パターン（wc_get_order()、wc_get_orders()、WC_Order メソッド）、バックグラウンド処理用 Action Scheduler、メンテナンス性のためのテンプレートオーバーライドの代わりにフック使用が必須です。決済ゲートウェイは生のカードデータを保存・ログに記録してはいけません。カートフラグメントは条件付きで読み込む必要があります。テンプレートオーバーライドはすべてのアクションフックを保持する必要があります。

レビューは HPOS 互換性、決済ゲートウェイセキュリティ（コードレベルのみ、PCI 準拠監査ではない）、WooCommerce フック使用方法、テンプレートオーバーライド品質、パフォーマンスパターンを検証します。WooCommerce コンテキスト（拡張機能、テーマ統合、決済ゲートウェイ、配送方法、カスタム商品タイプ、WC Blocks 統合）を自動検出し、レビューガイダンスを調整します。ファイルごとに行番号とともに重大度ラベル（CRITICAL/WARNING/INFO）、BAD/GOOD コードペアでグループ化された結果をレポートします。

注: このスキルは前のすべてのスキルに触れます。セキュリティ（決済データ処理）、プラグインアーキテクチャ（WC を拡張機能として）、ブロック（WC Blocks）、テーマ（テンプレートオーバーライド）、パフォーマンス（カートフラグメント、クエリ）です。全体を通じて相互参照を提供します。

使用タイミング

次の場合に使用してください:

• WooCommerce 拡張機能アーキテクチャレビュー
• HPOS 互換性監査（declare_compatibility チェック、CRUD のみの検証）
• 決済ゲートウェイコードレビュー（WC_Payment_Gateway パターン、セキュリティアンチパターン）
• 配送方法レビュー（WC_Shipping_Method、calculate_shipping）
• カスタム商品タイプレビュー（WC_Product 拡張、データストア）
• WooCommerce フック使用方法分析（オーダーライフサイクル、商品データ、カート/チェックアウト）
• テンプレートオーバーライド評価（フック保持、バージョン追跡）
• カートフラグメントパフォーマンス分析（サイト全体の読み込み検出）
• Action Scheduler パターンレビュー（wp_cron アンチパターン対比）
• WooCommerce REST API 拡張機能レビュー
• WC Blocks 統合チェック（Store API、Additional Checkout Fields API）
• Webhook セキュリティレビュー（署名検証）

次の場合には使用しないでください:

• 汎用プラグインアーキテクチャ（wp-plugin-development を使用）
• セキュリティのみの監査（包括的分析は wp-security-review を使用）
• WC 外のブロック開発（wp-block-development を使用）
• WC 統合なしのテーマのみレビュー（wp-theme-development を使用）
• パフォーマンスのみレビュー（wp-performance-review を使用）
• PCI 準拠監査（スコープ外 - インフラレベル）
• ストア設定またはホスティング構成（スコープ外）

コードレビューワークフロー

体系的な WooCommerce レビューのため、この 8 ステップワークフローを遵守してください：

1. ファイル構造から WooCommerce コンテキストを検出

拡張機能/プラグイン:

• WC 依存チェック付きメインプラグインファイル（プラグインヘッダーに「WooCommerce」）
• before_woocommerce_init フックの HPOS 宣言
• 最も一般的なコンテキスト。完全 HPOS + CRUD + フック監査

テーマ統合:

• テーマ内の woocommerce/ ディレクトリとテンプレートオーバーライド
• テンプレートオーバーライドフォーカスでフック優先ガイダンス
• wp-theme-development でテーマパターンを相互参照

決済ゲートウェイ:

• WC_Payment_Gateway を拡張するクラス
• セキュリティレビューを強化（カードデータ保存禁止、HTTPS チェック）
• 該当する場合は Webhook 検証

配送方法:

• WC_Shipping_Method を拡張するクラス
• calculate_shipping() レビュー、ゾーンサポート、料金計算

カスタム商品タイプ:

• WC_Product を拡張するクラス
• データストアレビュー、商品タイプ登録、クラス階層

WC Blocks 統合:

• Store API 使用、チェックアウトブロック拡張ポイント
• Additional Checkout Fields API（WC 8.6+）
• サーフェスレベルレビュー、詳細ブロックパターンは wp-block-development を提案

2. HPOS 互換性をチェック（WOO-16）

不在の場合は CRITICAL:

• before_woocommerce_init フック内の declare_compatibility() 呼び出し
• 検索パターン: add_action( 'before_woocommerce_init', ... ) と FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true )

CRITICAL 違反:

• get_posts() または WP_Query に post_type='shop_order'
• オーダーデータ用の get_post_meta() / update_post_meta()
• オーダーの wp_posts / wp_postmeta に対する直接 $wpdb クエリ

WARNING 違反:

• WP_Query に post_type='product'（将来破損予定。カスタム商品テーブル予定中）

GOOD パターン:

• wc_get_order( $order_id )
• wc_get_orders( array( 'status' => 'completed', 'limit' => 10 ) )
• $order->get_meta( 'key' )、$order->update_meta_data( 'key', $value )、$order->save()

互換モード認識:

• コードは HPOS とレガシーモード両方で動作する必要があります
• CRUD API のみを排他的に使用。両方のストレージモードを処理します

3. データアクセスパターンをチェック（WOO-02、WOO-17）

商品アクセス:

• GOOD: wc_get_product( $id )、WC_Product_Query
• WARNING: WP_Query に post_type='product'（代わりに wc_get_products() を使用）
• CRITICAL: 商品テーブルに対する直接 $wpdb クエリ

オーダーアクセス:

• GOOD: wc_get_order( $id )、wc_get_orders()
• CRITICAL: get_posts() に post_type='shop_order'
• CRITICAL: オーダーデータの直接 $wpdb クエリ

WC_Data パターン:

• すべての WooCommerce CRUD オブジェクトの基本クラス
• データストアは永続性を処理（ポストベース対 HPOS テーブル）
• 常に修正後に ->save() を呼び出します

4. 決済ゲートウェイが検出される場合（WOO-03、WOO-19、WOO-20）

CRITICAL 違反:

• データベースまたはセッションへの生のカード番号/CVV 保存
• error_log() または debug.log へのカードデータログ
• HTTP（非SSL）での認証情報の送信

WARNING 違反:

• コード内のハードコード API 認証情報（設定を使用すべき）
• 決済処理前の is_ssl() チェック不足
• Webhook 署名検証不足

process_payment() 検証:

• 「result」と「redirect」キーを持つ配列を返す必要があります
• 手動ステータス変更ではなく $order->payment_complete( $transaction_id ) を使用
• トークン化を使用。生 $_POST カードデータにアクセスしません

相互参照:

• 一般的なセキュリティパターンは wp-security-review を参照
• このスキルは WC 固有の決済アンチパターンのみに焦点

5. WooCommerce フック使用方法をチェック（WOO-05、WOO-06、WOO-07、WOO-08）

ライフサイクルフック:

• woocommerce_before_cart、woocommerce_after_cart
• woocommerce_checkout_process、woocommerce_checkout_create_order
• woocommerce_thankyou
• woocommerce_order_status_changed

商品データフック:

• 管理フィールド用の woocommerce_product_options_*
• 保存用の woocommerce_process_product_meta

チェックアウトフィールドフック:

• フィールド追加用の woocommerce_checkout_fields
• 保存用の woocommerce_checkout_update_order_meta

カートフック:

• カスタムカートデータ用の woocommerce_add_cart_item_data
• 手数料用の woocommerce_cart_calculate_fees
• 検証用の woocommerce_check_cart_items

ステータス遷移をオーダーします:

• 特定ステータス変更用の woocommerce_order_status_{status}
• 直接ポストステータス変更ではなく $order->set_status() をメモ付きで使用

6. テンプレートオーバーライドをチェック（WOO-10、WOO-11、WOO-12、WOO-13）

CRITICAL 違反:

• 削除された do_action() フックを含むテンプレートオーバーライド
• プラグイン統合を損なわせます。他の拡張機能がフックできません

WARNING 違反:

• 古いテンプレートバージョン（@version コメント不一致）
• WC アップデートを見逃す可能性、表示問題を引き起こす可能性

INFO 提案:

• フックが存在する場所でテンプレートオーバーライド。フック使用を提案

フック優先哲学:

• 重要な教授ポイント: フックはテンプレートオーバーライドより強く推奨されます
• テンプレートオーバーライドは最後の手段であるべき
• 元のテンプレートからすべての do_action() 呼び出しを常に保持

相互参照:

• wp-theme-development で汎用テンプレートパターンを参照

7. パフォーマンスパターンをチェック（WOO-15、WOO-17、WOO-18）

カートフラグメント（wc-cart-fragments.js）:

• CRITICAL: 条件付きデキューなしでサイト全体に読み込み
• WARNING: WC ページ以外への読み込み（正当化なし）
• GOOD: カート/チェックアウト/商品ページのみへの条件付きデキュー
• BETTER: Mini-Cart Block への移行（組み込み最適化）

商品クエリ:

• CRITICAL: 商品の wp_posts に対する直接 SQL クエリ
• WARNING: WP_Query に post_type='product'
• INFO: 繰り返し商品読み込みのオブジェクトキャッシング不足

Action Scheduler:

• WARNING: 一括 WC 操作用の wp_cron()（信頼性低、トラフィック依存）
• GOOD: as_enqueue_async_action()、as_schedule_single_action()
• WooCommerce で提供。別途インストール不要

セッション処理:

• WARNING: 30 日キャップ超過のカスタムセッションフィルター（WC 10.1+）
• INFO: WC_Session_Handler をバイパスするカスタムセッション実装

相互参照:

• wp-performance-review で包括的パフォーマンス分析を参照

8. 下記の出力形式を使用してレポート

必要に応じてスキルの相互参照を提案:

• セキュリティ懸念 → /wp-sec-review
• プラグインアーキテクチャ → /wp-plugin-review
• ブロック問題 → /wp-block-review
• テーマ問題 → /wp-theme-review
• パフォーマンス問題 → /wp-perf-review

ファイルタイプ別チェック

HPOS 互換性（WOO-16）

互換性宣言（不在の場合は CRITICAL）:

// GOOD: HPOS 互換性を宣言
add_action( 'before_woocommerce_init', function() {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            __FILE__,
            true
        );
    }
} );

// BAD: 宣言が不在
// 拡張機能は HPOS 有効化ストアで無言で壊れます

直接ポストアクセス（CRITICAL）:

• post_type='shop_order' の get_posts()
• post_type='shop_order' の new WP_Query( array( ... ) )
• オーダーデータの get_post_meta( $order_id, ... )
• オーダーデータの update_post_meta( $order_id, ... )
• オーダーの wp_posts に対する直接 $wpdb->prepare()

CRUD パターン（GOOD）:

// GOOD: HPOS 互換オーダーアクセス
$order = wc_get_order( $order_id );
$order->update_meta_data( 'custom_field', $value );
$order->save();

// GOOD: クエリオーダー
$orders = wc_get_orders( array(
    'status' => 'completed',
    'limit' => 10,
    'date_created' => '>=' . strtotime( '-30 days' )
) );

// BAD: 直接ポストアクセス（HPOS を破損）
$orders = get_posts( array(
    'post_type' => 'shop_order',
    'post_status' => 'wc-completed'
) );
update_post_meta( $order_id, 'custom_field', $value );

WooCommerce CRUD パターン（WOO-02、WOO-07）

WC_Data 基本クラス:

• すべての WooCommerce オブジェクトが WC_Data を拡張
• データストアが永続性を処理（HPOS テーブル対ポストテーブル）
• すべての変更の後に ->save() を呼び出すまで変更をバッファリング

オーダー CRUD:

// GOOD: 完全オーダー操作
$order = wc_get_order( $order_id );
$order->set_status( 'processing', 'Payment received' );
$order->update_meta_data( 'gift_message', $message );
$order->add_order_note( 'Custom note' );
$order->save(); // すべての変更後の単一保存

// BAD: 手動ポストステータス変更
wp_update_post( array(
    'ID' => $order_id,
    'post_status' => 'wc-processing'
) );

商品 CRUD:

// GOOD: 商品リスト用 WC_Product_Query
$query = new WC_Product_Query( array(
    'status' => 'publish',
    'limit' => 10,
    'category' => array( 'clothing' ),
    'orderby' => 'date',
    'order' => 'DESC'
) );
$products = $query->get_products();

// WARNING: 商品用 WP_Query（将来破損）
$products = new WP_Query( array(
    'post_type' => 'product',
    'posts_per_page' => 10
) );

カスタムデータストア登録:

// GOOD: カスタムデータストアを登録
add_filter( 'woocommerce_data_stores', 'register_custom_data_store' );
function register_custom_data_store( $data_stores ) {
    $data_stores['custom-order-type'] = 'Custom_Order_Data_Store';
    return $data_stores;
}

決済ゲートウェイ開発（WOO-03、WOO-19）

WC_Payment_Gateway クラス構造:

// GOOD: 完全決済ゲートウェイ実装
class WC_Gateway_Custom extends WC_Payment_Gateway {

    public function __construct() {
        $this->id = 'custom_gateway';
        $this->has_fields = true;
        $this->method_title = __( 'Custom Gateway', 'text-domain' );
        $this->method_description = __( 'Description', 'text-domain' );

        $this->init_form_fields();
        $this->init_settings();

        add_action( 'woocommerce_update_options_payment_gateways_' . $this->id,
            array( $this, 'process_admin_options' ) );
    }

    public function process_payment( $order_id ) {
        $order = wc_get_order( $order_id );

        // CRITICAL: 本番環境で常に HTTPS をチェック
        if ( ! is_ssl() && 'yes' !== $this->get_option( 'testmode' ) ) {
            wc_add_notice( __( 'SSL required', 'text-domain' ), 'error' );
            return array( 'result' => 'failure' );
        }

        // GOOD: 手動ステータス変更ではなく payment_complete() を使用
        $order->payment_complete( $transaction_id );

        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    }
}

CRITICAL セキュリティアンチパターン:

// CRITICAL: 生のカードデータ保存禁止
// BAD:
update_post_meta( $order_id, 'card_number', $_POST['card_number'] );
$wpdb->insert( 'payment_tokens', array( 'card' => $_POST['card_number'] ) );

// CRITICAL: カードデータをログに記録禁止
// BAD:
error_log( 'Card: ' . $_POST['card_number'] );
wc_get_logger()->debug( 'CVV: ' . $_POST['cvv'] );

// GOOD: トークン化を使用
$token = new WC_Payment_Token_CC();
$token->set_token( $gateway_token );
$token->set_gateway_id( $this->id );
$token->set_last4( substr( $card_number, -4 ) );
$token->set_card_type( $card_type );
$token->save();

払い戻し処理:

// GOOD: 払い戻しサポートを実装
public function process_refund( $order_id, $amount = null, $reason = '' ) {
    $order = wc_get_order( $order_id );

    // API 経由で払い戻しを処理
    $result = $this->api_refund( $order, $amount );

    if ( $result->success ) {
        $order->add_order_note(
            sprintf( __( 'Refunded %s', 'text-domain' ), $amount )
        );
        return true;
    }

    return false;
}

相互参照:

• wp-security-review で包括的セキュリティパターンを参照
• これは WC 決済固有のアンチパターンのみに焦点

配送方法（WOO-04）

WC_Shipping_Method クラス構造:

// GOOD: 完全配送方法実装
class WC_Shipping_Custom extends WC_Shipping_Method {

    public function __construct( $instance_id = 0 ) {
        $this->id = 'custom_shipping';
        $this->instance_id = absint( $instance_id );
        $this->method_title = __( 'Custom Shipping', 'text-domain' );
        $this->method_description = __( 'Description', 'text-domain' );
        $this->supports = array( 'shipping-zones', 'instance-settings' );

        $this->init();
    }

    public function calculate_shipping( $package = array() ) {
        $rate = array(
            'id' => $this->id . $this->instance_id,
            'label' => $this->title,
            'cost' => 10.00,
            'calc_tax' => 'per_order'
        );

        $this->add_rate( $rate );
    }
}

カスタム商品タイプ（WOO-02）

商品タイプ登録:

// GOOD: カスタム商品タイプを登録
add_filter( 'product_type_selector', 'add_custom_product_type' );
function add_custom_product_type( $types ) {
    $types['custom-product'] = __( 'Custom Product', 'text-domain' );
    return $types;
}

// GOOD: WC_Product を拡張する商品クラス
class WC_Product_Custom extends WC_Product {

    public function __construct( $product = 0 ) {
        $this->product_type = 'custom-product';
        parent::__construct( $product );
    }

    public function get_type() {
        return 'custom-product';
    }
}

// GOOD: 商品クラスを登録
add_filter( 'woocommerce_product_class', 'load_custom_product_class', 10, 2 );
function load_custom_product_class( $classname, $product_type ) {
    if ( 'custom-product' === $product_type ) {
        $classname = 'WC_Product_Custom';
    }
    return $classname;
}

WooCommerce フックカタログ（WOO-05、WOO-06）

ライフサイクルフック:

// GOOD: オーダーライフサイクルフック
add_action( 'woocommerce_checkout_process', 'validate_custom_checkout_field' );
add_action( 'woocommerce_checkout_create_order', 'save_custom_order_data', 10, 2 );
add_action( 'woocommerce_thankyou', 'custom_thankyou_action' );
add_action( 'woocommerce_order_status_changed', 'handle_status_change', 10, 4 );

商品データフック:

// GOOD: 商品管理フック
add_action( 'woocommerce_product_options_general_product_data', 'add_custom_field' );
add_action( 'woocommerce_process_product_meta', 'save_custom_field' );

チェックアウトフィールドフック:

// GOOD: チェックアウトフィールドを追加
add_filter( 'woocommerce_checkout_fields', 'add_gift_message_field' );
function add_gift_message_field( $fields ) {
    $fields['order']['gift_message'] = array(
        'type' => 'textarea',
        'label' => __( 'Gift message', 'text-domain' ),
        'required' => false
    );
    return $fields;
}

add_action( 'woocommerce_checkout_update_order_meta', 'save_gift_message' );
function save_gift_message( $order_id ) {
    if ( ! empty( $_POST['gift_message'] ) ) {
        $order = wc_get_order( $order_id );
        $order->update_meta_data( 'gift_message', sanitize_textarea_field( $_POST['gift_message'] ) );
        $order->save();
    }
}

カート操作（WOO-08）

カート商品データ:

// GOOD: カスタムカート商品データを追加
add_filter( 'woocommerce_add_cart_item_data', 'add_custom_cart_data', 10, 2 );
function add_custom_cart_data( $cart_item_data, $product_id ) {
    if ( isset( $_POST['custom_field'] ) ) {
        $cart_item_data['custom_field'] = sanitize_text_field( $_POST['custom_field'] );
    }
    return $cart_item_data;
}

カート手数料:

// GOOD: カスタム手数料を追加
add_action( 'woocommerce_cart_calculate_fees', 'add_custom_fee' );
function add_custom_fee() {
    if ( WC()->cart->get_subtotal() > 100 ) {
        WC()->cart->add_fee( __( 'Handling fee', 'text-domain' ), 5 );
    }
}

カート検証:

// GOOD: カート内容を検証
add_action( 'woocommerce_check_cart_items', 'validate_cart_items' );
function validate_cart_items() {
    if ( WC()->cart->get_cart_contents_count() < 3 ) {
        wc_add_notice( __( 'Minimum 3 items required', 'text-domain' ), 'error' );
    }
}

オーダーステータス遷移（WOO-07）

カスタムオーダーステータス:

// GOOD: カスタムオーダーステータスを登録
add_action( 'init', 'register_awaiting_shipment_status' );
function register_awaiting_shipment_status() {
    register_post_status( 'wc-awaiting-shipment', array(
        'label' => __( 'Awaiting Shipment', 'text-domain' ),
        'public' => true,
        'show_in_admin_status_list' => true,
        'label_count' => _n_noop(
            'Awaiting shipment <span class="count">(%s)</span>',
            'Awaiting shipment <span class="count">(%s)</span>',
            'text-domain'
        )
    ) );
}

add_filter( 'wc_order_statuses', 'add_awaiting_shipment_to_order_statuses' );
function add_awaiting_shipment_to_order_statuses( $order_statuses ) {
    $order_statuses['wc-awaiting-shipment'] = __( 'Awaiting Shipment', 'text-domain' );
    return $order_statuses;
}

// GOOD: オーダーステータスを設定
$order = wc_get_order( $order_id );
$order->set_status( 'awaiting-shipment', 'Order ready for shipment' );

カートフラグメントパフォーマンス（WOO-15）

条件付きデキューイング:

// GOOD: 条件付きカートフラグメント読み込み
add_filter( 'woocommerce_get_script_data', 'conditional_cart_fragments', 10, 2 );
function conditional_cart_fragments( $data, $handle ) {
    if ( 'wc-cart-fragments' === $handle ) {
        // WC ページのみに読み込み
        if ( ! is_woocommerce() && ! is_cart() && ! is_checkout() ) {
            return null;
        }
    }
    return $data;
}

// CRITICAL: サイト全体カートフラグメント読み込み
// BAD: デキュー条件なし。すべてのページに読み込み

Mini-Cart ブロック代替:

// INFO: Mini-Cart ブロックへの移行を推奨
// Mini-Cart ブロックは組み込みパフォーマンス最適化を持つ
// カートフラグメント不要

Action Scheduler パターン

バックグラウンド処理:

// GOOD: 一括操作用 Action Scheduler
function schedule_order_export() {
    as_enqueue_async_action(
        'process_order_export',
        array( 'batch_id' => 123 ),
        'wc-exports'
    );
}

add_action( 'process_order_export', 'do_order_export', 10, 1 );
function do_order_export( $batch_id ) {
    $orders = wc_get_orders( array(
        'limit' => 100,
        'offset' => $batch_id * 100
    ) );

    foreach ( $orders as $order ) {
        // エクスポートロジック
    }

    // 必要に応じて次バッチをスケジュール
    if ( count( $orders ) === 100 ) {
        as_enqueue_async_action(
            'process_order_export',
            array( 'batch_id' => $batch_id + 1 ),
            'wc-exports'
        );
    }
}

// WARNING: 重い WC タスク用 wp_cron
// BAD:
wp_schedule_event( time(), 'hourly', 'process_order_export' );

Webhook セキュリティ（WOO-20）

署名検証:

// GOOD: Webhook 署名を検証
function verify_wc_webhook( $payload, $signature, $secret ) {
    $expected = base64_encode( hash_hmac( 'sha256', $payload, $secret, true ) );

    // CRITICAL: タイミング攻撃防止に hash_equals を使用
    return hash_equals( $expected, $signature );
}

// Webhook ハンドラー
$payload = file_get_contents( 'php://input' );
$signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$delivery_id = $_SERVER['HTTP_X_WC_WEBHOOK_DELIVERY_ID'] ?? '';

// WARNING: 署名検証が不足
if ( ! verify_wc_webhook( $payload, $signature, $secret ) ) {
    http_response_code( 401 );
    exit;
}

// GOOD: 重複配信をチェック
if ( get_transient( 'wc_webhook_' . $delivery_id ) ) {
    http_response_code( 200 );
    exit;
}
set_transient( 'wc_webhook_' . $delivery_id, true, DAY_IN_SECONDS );

// GOOD: Action Scheduler 経由で非同期処理
as_enqueue_async_action( 'process_wc_webhook', array( 'payload' => $payload ) );

テンプレートオーバーライドアンチパターン（WOO-10、WOO-11、WOO-12）

フックを保持:

// 子テーマ/woocommerce/content-product.php 内

// GOOD: 元のテンプレートからすべてのアクションフックを保持
do_action( 'woocommerce_before_shop_loop_item' );
do_action( 'woocommerce_before_shop_loop_item_title' );
// ここにカスタムコンテンツ
do_action( 'woocommerce_shop_loop_item_title' );
do_action( 'woocommerce_after_shop_loop_item_title' );
do_action( 'woocommerce_after_shop_loop_item' );

// CRITICAL: テンプレートオーバーライドで削除されたフック
// BAD: do_action() 呼び出しなし。プラグイン統合が壊れます

バージョン追跡:

// GOOD: バージョンコメント付きテンプレート
/**
 * Product loop template
 *
 * @version 8.9.0
 */

// WARNING: 古いバージョン
// テンプレートバージョン 3.6.0 で WC 10.5 時点。アップデート見逃す可能性

フック優先哲学:

// BETTER: テンプレートオーバーライドの代わりにフックを使用
add_action( 'woocommerce_shop_loop_item_title', 'add_custom_content', 15 );
function add_custom_content() {
    // フック経由カスタムコンテンツ。テンプレートオーバーライド不要
}

// INFO: フックが存在する場所でテンプレートオーバーライド
// フック使用をテンプレートオーバーライドの代わりに提案

相互参照:

• wp-theme-development で汎用テンプレートパターンを参照

サーフェスレベルチェック

WooCommerce Blocks チェックアウト統合（WOO-14）:

// GOOD: Additional Checkout Fields API 経由チェックアウトフィールドを追加（WC 8.6+）
add_action( 'woocommerce_init', 'register_custom_checkout_field' );
function register_custom_checkout_field() {
    woocommerce_register_additional_checkout_field( array(
        'id' => 'namespace/gift-message',
        'label' => __( 'Gift message', 'text-domain' ),
        'location' => 'order',
        'type' => 'text'
    ) );
}

WooCommerce REST API 拡張機能（WOO-09）:

// INFO: カスタム REST エンドポイント登録
add_action( 'rest_api_init', 'register_custom_endpoint' );
function register_custom_endpoint() {
    register_rest_route( 'wc/v3', '/custom-endpoint', array(
        'methods' => 'GET',
        'callback' => 'custom_endpoint_callback',
        'permission_callback' => function() {
            return current_user_can( 'manage_woocommerce' );
        }
    ) );
}

クーポン検証（WOO-21）:

// GOOD: カスタムクーポン検証
add_filter( 'woocommerce_coupon_is_valid', 'validate_custom_coupon', 10, 3 );
function validate_custom_coupon( $valid, $coupon, $discount ) {
    if ( WC()->cart->get_cart_contents_count() < 3 ) {
        throw new Exception(
            __( 'Coupon requires at least 3 items', 'text-domain' ),
            109
        );
    }
    return $valid;
}

セッション処理（WOO-18）:

// WARNING: 30 日キャップ超過のカスタムセッションフィルター（WC 10.1+）
// BAD:
add_filter( 'wc_session_expiration', function() {
    return 60 * DAY_IN_SECONDS; // キャップを超過
} );

// GOOD: 30 日キャップを尊重
add_filter( 'wc_session_expiration', function() {
    return 30 * DAY_IN_SECONDS; // 最大許可値
} );

クイック検出用検索パターン（WOO-22）

重大度別に整理された WooCommerce スキャンの rg コマンドとシェルチェック。

CRITICAL パターン

# HPOS 宣言候補
# これが WooCommerce 拡張機能で何も返さない場合、プラグインは HPOS 宣言が不足している可能性があります。
rg -n "declare_compatibility\s*\(\s*['\"]custom_order_tables['\"]" . -g '*.php'

# shop_order での get_posts/WP_Query
rg -n "post_type.*shop_order|shop_order.*post_type" . -g '*.php'

# オーダーの wp_posts に対する直接 $wpdb クエリ
rg -n "\$wpdb.*wp_posts.*shop_order" . -g '*.php'

# 生のカードデータ保存/ログ
rg -n "card_number|card_cvv|cvv.*meta|card.*error_log" . -g '*.php'

# do_action() 呼び出しなしのテンプレートオーバーライド
find . -path "*/woocommerce/*.php" -exec rg -L "do_action|apply_filters" {} \;

# Webhook 署名処理候補（手動で検証ロジックを確認）
rg -n "X-WC-Webhook-Signature|hash_hmac|verify" . -g '*.php'

WARNING パターン

# post_type=product での WP_Query（結果セットを手動で比較）
rg -n "WP_Query|get_posts" . -g '*.php'
rg -n "post_type.*product|product.*post_type" . -g '*.php'

# 条件付きデキューなしのサイト全体カートフラグメント読み込み（手動コンテキストチェック）
rg -n "wc-cart-fragments|woocommerce_get_script_data|is_woocommerce|is_cart" . -g '*.php'

# 一括 WC 操作用 wp_cron（手動コンテキストチェック）
rg -n "wp_schedule_event|wp_cron|wc_|order|product" . -g '*.php'

# ハードコード API 認証情報
rg -n "api_key.*=.*['\"][A-Za-z0-9]{20,}" . -g '*.php'

# オーダーフィールド用 get_post_meta/update_post_meta
rg -n "get_post_meta.*order_id|update_post_meta.*order_id" . -g '*.php'

# 30 日キャップ超過のセッションフィルター（返された値に手動フォローアップ）
rg -n "wc_session_expiration|wc_session_expiring" . -g '*.php'

INFO パターン

# フックが存在する場所でのテンプレートオーバーライド
find . -path "*/woocommerce/*.php" -type f

# 繰り返し商品読み込みのオブジェクトキャッシング不足
rg -n "wc_get_product" . -g '*.php'

# Action Scheduler 候補
rg -n "foreach.*wc_get_orders|foreach.*wc_get_products" . -g '*.php'

# WC Blocks 統合機会
rg -n "woocommerce_register_additional_checkout_field|Store API" . -g '*.php'

注: WC 固有パターンは汎用 WP と異なるコンテキストが必要です。非オーダーポストタイプの get_posts() は有効です。標準投稿/ページの WP_Query は有効です。WC 固有ポストタイプと組み合わせた場合のみフラグを設定します。

WooCommerce コンテキスト検出

ファイル構造とパターンに基づくコンテキスト認識レビュー注：

拡張機能/プラグイン

検出: WC 依存チェック付きメインプラグインファイル、HPOS 宣言 レビューフォーカス: 完全 HPOS + CRUD + フック監査 最も一般的なコンテキスト

テーマ統合

検出: テーマ内の woocommerce/ ディレクトリとテンプレートオーバーライド レビューフォーカス: テンプレートオーバーライド品質、フック保持 相互参照: wp-theme-development でテーマパターン

決済ゲートウェイ

検出: WC_Payment_Gateway を拡張するクラス レビューフォーカス: セキュリティレビューを強化（カードデータ保存禁止、HTTPS チェック、Webhook 検証） 相互参照: wp-security-review で一般的なセキュリティ

配送方法

検出: WC_Shipping_Method を拡張するクラス レビューフォーカス: calculate_shipping() レビュー、ゾーンサポート、料金計算

カスタム商品タイプ

検出: WC_Product を拡張するクラス レビューフォーカス: データストアレビュー、商品タイプ登録、クラス階層

WC Blocks 統合

検出: Store API 使用、チェックアウトブロック拡張ポイント レビューフォーカス: サーフェスレベルレビュー、Additional Checkout Fields API 相互参照: wp-block-development で詳細ブロックパターン

クイックリファレンス: WooCommerce 開発パターン（WOO-23）

関心別に整理された一般的な WooCommerce パターン。すべての例は WordPress PHP Coding Standards（括弧内のスペース、array() ではなく [] 非推奨、Yoda 条件）に従います。

HPOS 互換性宣言

❌ BAD: HPOS 宣言が不在

<?php
// 拡張機能は HPOS 有効化ストアで無言で壊れます

✅ GOOD: before_woocommerce_init フック内で互換性を宣言

<?php
add_action( 'before_woocommerce_init', function() {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            __FILE__,
            true
        );
    }
} );

オーダーデータアクセス

❌ BAD: 直接ポストアクセス（HPOS を破損）

<?php
$orders = get_posts( array(
    'post_type' => 'shop_order',
    'post_status' => 'wc-completed'
) );
update_post_meta( $order_id, 'custom_field', $value );

✅ GOOD: HPOS 互換 CRUD

<?php
$orders = wc_get_orders( array(
    'status' => 'completed',
    'limit' => 10
) );

$order = wc_get_order( $order_id );
$order->update_meta_data( 'custom_field', $value );
$order->save();

オーダーメタ操作

❌ BAD: 直接メタ関数

<?php
update_post_meta( $order_id, 'delivery_date', '2026-02-15' );
$date = get_post_meta( $order_id, 'delivery_date', true );

✅ GOOD: WC_Order メソッド

<?php
$order = wc_get_order( $order_id );
$order->update_meta_data( 'delivery_date', '2026-02-15' );
$order->save();

$date = $order->get_meta( 'delivery_date', true );

商品データアクセス

❌ BAD: 商品用 WP_Query（将来破損）

<?php
$products = new WP_Query( array(
    'post_type' => 'product',
    'posts_per_page' => 10
) );

✅ GOOD: WC_Product_Query

<?php
$query = new WC_Product_Query( array(
    'status' => 'publish',
    'limit' => 10,
    'category' => array( 'clothing' ),
    'orderby' => 'date',
    'order' => 'DESC'
) );
$products = $query->get_products();

決済ゲートウェイ

❌ BAD: 生のカードデータ保存、HTTPS チェック不足

<?php
public function process_payment( $order_id ) {
    // CRITICAL: 生のカードデータ保存禁止
    update_post_meta( $order_id, 'card_number', $_POST['card_number'] );

    // 決済を処理
    $order = wc_get_order( $order_id );
    $order->update_status( 'processing' ); // 手動ステータス変更

    return array(
        'result' => 'success',
        'redirect' => $this->get_return_url( $order )
    );
}

✅ GOOD: トークン化、HTTPS チェック、payment_complete()

<?php
public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );

    // 本番環境で HTTPS をチェック
    if ( ! is_ssl() && 'yes' !== $this->get_option( 'testmode' ) ) {
        wc_add_notice( __( 'SSL required', 'text-domain' ), 'error' );
        return array( 'result' => 'failure' );
    }

    // API 経由で処理（トークン化を使用、生のカード保存禁止）
    $result = $this->api_charge( $order );

    if ( $result->success ) {
        // 手動ステータス変更ではなく payment_complete() を使用
        $order->payment_complete( $result->transaction_id );

        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    }

    return array( 'result' => 'failure' );
}

配送方法

✅ GOOD: 完全配送方法

<?php
class WC_Shipping_Custom extends WC_Shipping_Method {

    public function __construct( $instance_id = 0 ) {
        $this->id = 'custom_shipping';
        $this->instance_id = absint( $instance_id );
        $this->method_title = __( 'Custom Shipping', 'text-domain' );
        $this->supports = array( 'shipping-zones', 'instance-settings' );

        $this->init();
    }

    public function calculate_shipping( $package = array() ) {
        $rate = array(
            'id' => $this->id . $this->instance_id,
            'label' => $this->title,
            'cost' => 10.00,
            'calc_tax' => 'per_order'
        );

        $this->add_rate( $rate );
    }
}

カスタム商品タイプ

✅ GOOD: カスタム商品タイプを登録して実装

<?php
// 商品タイプを登録
add_filter( 'product_type_selector', 'add_custom_product_type' );
function add_custom_product_type( $types ) {
    $types['custom-product'] = __( 'Custom Product', 'text-domain' );
    return $types;
}

// 商品クラス
class WC_Product_Custom extends WC_Product {

    public function __construct( $product = 0 ) {
        $this->product_type = 'custom-product';
        parent::__construct( $product );
    }

    public function get_type() {
        return 'custom-product';
    }
}

// 商品クラスを登録
add_filter( 'woocommerce_product_class', 'load_custom_product_class', 10, 2 );
function load_custom_product_class( $classname, $product_type ) {
    if ( 'custom-product' === $product_type ) {
        $classname = 'WC_Product_Custom';
    }
    return $classname;
}

カート操作

✅ GOOD: カート商品データを追加

<?php
add_filter( 'woocommerce_add_cart_item_data', 'add_custom_cart_data', 10, 2 );
function add_custom_cart_data( $cart_item_data, $product_id ) {
    if ( isset( $_POST['custom_field'] ) ) {
        $cart_item_data['custom_field'] = sanitize_text_field( $_POST['custom_field'] );
    }
    return $cart_item_data;
}

✅ GOOD: カート手数料を追加

<?php
add_action( 'woocommerce_cart_calculate_fees', 'add_custom_fee' );
function add_custom_fee() {
    if ( WC()->cart->get_subtotal() > 100 ) {
        WC()->cart->add_fee( __( 'Handling fee', 'text-domain' ), 5 );
    }
}

オーダーステータス遷移

❌ BAD: 手動ポストステータス変更

<?php
wp_update_post( array(
    'ID' => $order_id,
    'post_status' => 'wc-processing'
) );

✅ GOOD: WC_Order::set_status() を使用

<?php
$order = wc_get_order( $order_id );
$order->set_status( 'processing', 'Payment received' );
// 自動保存

✅ GOOD: 決済フロー用 payment_complete() を使用

<?php
$order = wc_get_order( $order_id );
$order->payment_complete( $transaction_id );

フック保持付きテンプレートオーバーライド

❌ BAD: テンプレートオーバーライドで削除されたフック

<?php
// 子テーマ/woocommerce/content-product.php
// CRITICAL: do_action() 呼び出しなし。プラグイン統合が壊れます
?>
<li class="product">
    <h2><?php the_title(); ?></h2>
    <div class="price"><?php echo $product->get_price_html(); ?></div>
</li>

✅ GOOD: すべてのアクションフックを保持

<?php
// 子テーマ/woocommerce/content-product.php
do_action( 'woocommerce_before_shop_loop_item' );
do_action( 'woocommerce_before_shop_loop_item_title' );
?>
<h2><?php the_title(); ?></h2>
<?php
do_action( 'woocommerce_shop_loop_item_title' );
do_action( 'woocommerce_after_shop_loop_item_title' );
do_action( 'woocommerce_after_shop_loop_item' );

✅ BETTER: テンプレートオーバーライドの代わりにフックを使用

<?php
add_action( 'woocommerce_shop_loop_item_title', 'add_custom_content', 15 );
function add_custom_content() {
    // フック経由カスタムコンテンツ。テンプレートオーバーライド不要
}

カートフラグメント最適化

❌ BAD: サイト全体カートフラグメント読み込み

<?php
// 条件付きデキューなし。すべてのページに読み込み
// CRITICAL パフォーマンス問題

✅ GOOD: 条件付きデキューイング

<?php
add_filter( 'woocommerce_get_script_data', 'conditional_cart_fragments', 10, 2 );
function conditional_cart_fragments( $data, $handle ) {
    if ( 'wc-cart-fragments' === $handle ) {
        if ( ! is_woocommerce() && ! is_cart() && ! is_checkout() ) {
            return null;
        }
    }
    return $data;
}

✅ BETTER: Mini-Cart ブロックへ移行

// Mini-Cart ブロックは組み込みパフォーマンス最適化を持つ
// カートフラグメント不要

Action Scheduler

❌ BAD: 一括 WC 操作用 wp_cron

<?php
wp_schedule_event( time(), 'hourly', 'process_order_export' );

add_action( 'process_order_export', 'do_export' );
function do_export() {
    // 信頼性低、トラフィック依存、リトライなし
}

✅ GOOD: 一括操作用 Action Scheduler

<?php
function schedule_order_export() {
    as_enqueue_async_action(
        'process_order_export',
        array( 'batch_id' => 0 ),
        'wc-exports'
    );
}

add_action( 'process_order_export', 'do_order_export', 10, 1 );
function do_order_export( $batch_id ) {
    $orders = wc_get_orders( array(
        'limit' => 100,
        'offset' => $batch_id * 100
    ) );

    foreach ( $orders as $order ) {
        // エクスポートロジック
    }

    // 必要に応じて次バッチをスケジュール
    if ( 100 === count( $orders ) ) {
        as_enqueue_async_action(
            'process_order_export',
            array( 'batch_id' => $batch_id + 1 ),
            'wc-exports'
        );
    }
}

Webhook セキュリティ

❌ BAD: 署名検証が不足

<?php
// Webhook ハンドラー
$payload = file_get_contents( 'php://input' );
$data = json_decode( $payload );

// WARNING: