# Wp Woocommerce Dev > WooCommerce extension code review for HPOS compatibility, payment gateway security, cart optimization, and template overrides. Use when reviewing WooCommerce extension code, payment gateway development, shipping methods, custom product types, cart operations, checkout customization, or when user mentions "WooCommerce review", "WooCommerce extension", "WooCommerce plugin", "payment gateway", "shipping method", "HPOS", "High-Performance Order Storage", "wc_get_orders", "WC_Payment_Gateway", "WC_Shipping_Method", "cart fragments", "WooCommerce hooks", "WooCommerce template", "shop_order", "WooCommerce performance", "Action Scheduler", "WooCommerce REST API", "WooCommerce Blocks", "checkout block", "woocommerce_checkout". Detects HPOS issues, CRUD violations, payment security anti-patterns, performance problems, and template override mistakes in WooCommerce 8.2+ through 10.x code. - Skill: `jorgerosal/wp-woocommerce-dev-2` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add jorgerosal/wp-woocommerce-dev-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/jorgerosal/wp-woocommerce-dev-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: jorgerosal (https://skillmd.com/u/jorgerosal) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jorgerosal/wp-woocommerce-dev-2 --- # WooCommerce Development Review Skill ## Overview Systematic WooCommerce development review for WooCommerce 8.2+ through current 10.x. **Core principle:** WooCommerce has undergone a fundamental architectural shift—HPOS (High-Performance Order Storage) is default for new stores since WC 8.2 (October 2023), requiring all extensions to use CRUD APIs exclusively. Direct post access for orders is broken on modern WooCommerce installations. Extensions must use WC_Data CRUD pattern (wc_get_order(), wc_get_orders(), WC_Order methods), Action Scheduler for background processing, and hooks-over-template-overrides for maintainability. Payment gateways must never store/log raw card data. Cart fragments must be conditionally loaded. Template overrides must preserve all action hooks. Review validates HPOS compatibility, payment gateway security (code-level only, NOT PCI compliance audit), WooCommerce hook usage, template override quality, and performance patterns. Auto-detects WooCommerce context (extension, theme integration, payment gateway, shipping method, custom product type, WC Blocks integration) and adjusts review guidance. Report findings grouped by file with line numbers, severity labels (CRITICAL/WARNING/INFO), and BAD/GOOD code pairs. **Note:** This skill touches all prior skills—security (payment data handling), plugin architecture (WC as extension), blocks (WC Blocks), themes (template overrides), and performance (cart fragments, queries). Cross-references provided throughout. ## When to Use **Use when:** - WooCommerce extension architecture review - HPOS compatibility audit (declare_compatibility check, CRUD-only validation) - Payment gateway code review (WC_Payment_Gateway patterns, security anti-patterns) - Shipping method review (WC_Shipping_Method, calculate_shipping) - Custom product type review (WC_Product extension, data stores) - WooCommerce hook usage analysis (order lifecycle, product data, cart/checkout) - Template override assessment (hooks preservation, version tracking) - Cart fragments performance analysis (site-wide loading detection) - Action Scheduler pattern review (vs wp_cron anti-patterns) - WooCommerce REST API extension review - WC Blocks integration check (Store API, Additional Checkout Fields API) - Webhook security review (signature verification) **Don't use for:** - Generic plugin architecture (use wp-plugin-development) - Security-only audits (use wp-security-review for comprehensive analysis) - Block development outside WC (use wp-block-development) - Theme-only review without WC integration (use wp-theme-development) - Performance-only review (use wp-performance-review) - PCI compliance auditing (out of scope—infrastructure-level) - Store setup or hosting configuration (out of scope) ## Code Review Workflow Follow this eight-step workflow for systematic WooCommerce reviews: ### 1. Detect WooCommerce context from file structure **Extension/plugin:** - Main plugin file with WC dependency check (`WooCommerce` in plugin header) - HPOS declaration via `before_woocommerce_init` hook - Most common context—full HPOS + CRUD + hook audit **Theme integration:** - woocommerce/ directory in theme with template overrides - Template override focus with hooks-first guidance - Cross-reference wp-theme-development for theme patterns **Payment gateway:** - Class extending `WC_Payment_Gateway` - Heightened security review (never store raw cards, HTTPS check) - Webhook verification if applicable **Shipping method:** - Class extending `WC_Shipping_Method` - calculate_shipping() review, zone support, rate calculation **Custom product type:** - Class extending `WC_Product` - Data store review, product type registration, class hierarchy **WC Blocks integration:** - Store API usage, checkout block extension points - Additional Checkout Fields API (WC 8.6+) - Surface-level review, suggest wp-block-development for deep block patterns ### 2. Check HPOS compatibility (WOO-16) **CRITICAL if missing:** - `declare_compatibility()` call in `before_woocommerce_init` hook - Pattern to find: `add_action( 'before_woocommerce_init', ... )` with `FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true )` **CRITICAL violations:** - `get_posts()` or `WP_Query` with `post_type='shop_order'` - `get_post_meta()` / `update_post_meta()` for order data - Direct `$wpdb` queries against `wp_posts` / `wp_postmeta` for orders **WARNING violations:** - `WP_Query` with `post_type='product'` (future-breaking—custom product tables planned) **GOOD patterns:** - `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()` **Compatibility mode awareness:** - Code should work in both HPOS and legacy modes - Use CRUD APIs exclusively—they handle both storage modes ### 3. Check data access patterns (WOO-02, WOO-17) **Product access:** - GOOD: `wc_get_product( $id )`, `WC_Product_Query` - WARNING: `WP_Query` with `post_type='product'` (use `wc_get_products()` instead) - CRITICAL: Direct `$wpdb` queries against product tables **Order access:** - GOOD: `wc_get_order( $id )`, `wc_get_orders()` - CRITICAL: `get_posts()` with `post_type='shop_order'` - CRITICAL: Direct `$wpdb` queries for order data **WC_Data pattern:** - Base class for all WooCommerce CRUD objects - Data stores handle persistence (post-based vs HPOS tables) - Always call `->save()` after modifications ### 4. If payment gateway detected (WOO-03, WOO-19, WOO-20) **CRITICAL violations:** - Storing raw card numbers/CVV in database or sessions - Logging card data in `error_log()` or `debug.log` - Transmitting card data over HTTP (non-SSL) **WARNING violations:** - Hardcoded API credentials in code (should use settings) - Missing `is_ssl()` check before payment processing - Missing webhook signature verification **process_payment() validation:** - Must return array with 'result' and 'redirect' keys - Use `$order->payment_complete( $transaction_id )` not manual status change - Never access raw `$_POST` card data—use tokenization **Cross-reference:** - See wp-security-review for general security patterns - This skill focuses on WC-specific payment anti-patterns only ### 5. Check WooCommerce hook usage (WOO-05, WOO-06, WOO-07, WOO-08) **Lifecycle hooks:** - `woocommerce_before_cart`, `woocommerce_after_cart` - `woocommerce_checkout_process`, `woocommerce_checkout_create_order` - `woocommerce_thankyou` - `woocommerce_order_status_changed` **Product data hooks:** - `woocommerce_product_options_*` for admin fields - `woocommerce_process_product_meta` for saving **Checkout field hooks:** - `woocommerce_checkout_fields` for adding fields - `woocommerce_checkout_update_order_meta` for saving **Cart hooks:** - `woocommerce_add_cart_item_data` for custom cart data - `woocommerce_cart_calculate_fees` for fees - `woocommerce_check_cart_items` for validation **Order status transitions:** - `woocommerce_order_status_{status}` for specific status changes - Use `$order->set_status()` with note, not direct post status change ### 6. Check template overrides (WOO-10, WOO-11, WOO-12, WOO-13) **CRITICAL violations:** - Template overrides with deleted `do_action()` hooks - Breaks plugin integration—other extensions can't hook in **WARNING violations:** - Outdated template versions (@version comment mismatch) - May miss WC updates, cause display issues **INFO suggestions:** - Template override where a hook exists—suggest using hook instead **Hooks-first philosophy:** - Key teaching point: hooks are strongly preferred over template overrides - Template overrides should be last resort - Always preserve ALL `do_action()` calls from original template **Cross-reference:** - See wp-theme-development for general template patterns ### 7. Check performance patterns (WOO-15, WOO-17, WOO-18) **Cart fragments (wc-cart-fragments.js):** - CRITICAL: Site-wide loading with no conditional dequeue - WARNING: Loading on non-WC pages without justification - GOOD: Conditional dequeuing to cart/checkout/product pages only - BETTER: Migrate to Mini-Cart Block (built-in optimization) **Product queries:** - CRITICAL: Direct SQL queries against `wp_posts` for products - WARNING: `WP_Query` with `post_type='product'` - INFO: Missing object caching for repeated product loads **Action Scheduler:** - WARNING: `wp_cron()` for bulk WC operations (unreliable, traffic-dependent) - GOOD: `as_enqueue_async_action()`, `as_schedule_single_action()` - Ships with WooCommerce—no separate installation **Session handling:** - WARNING: Custom session filters exceeding 30-day cap (WC 10.1+) - INFO: Custom session implementations bypassing `WC_Session_Handler` **Cross-reference:** - See wp-performance-review for comprehensive performance analysis ### 8. Report using output format below Suggest cross-referencing skills as appropriate: - Security concerns → `/wp-sec-review` - Plugin architecture → `/wp-plugin-review` - Block issues → `/wp-block-review` - Theme issues → `/wp-theme-review` - Performance issues → `/wp-perf-review` ## File-Type Specific Checks ### HPOS Compatibility (WOO-16) **Compatibility declaration (CRITICAL if missing):** ```php // GOOD: Declare HPOS compatibility 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: Missing declaration // Extension silently breaks on HPOS-enabled stores ``` **Direct post access (CRITICAL):** - `get_posts()` with `'post_type' => 'shop_order'` - `new WP_Query( array( 'post_type' => 'shop_order' ) )` - `get_post_meta( $order_id, ... )` for order data - `update_post_meta( $order_id, ... )` for order data - Direct `$wpdb->prepare()` against `wp_posts` for orders **CRUD patterns (GOOD):** ```php // GOOD: HPOS-compatible order access $order = wc_get_order( $order_id ); $order->update_meta_data( 'custom_field', $value ); $order->save(); // GOOD: Query orders $orders = wc_get_orders( array( 'status' => 'completed', 'limit' => 10, 'date_created' => '>=' . strtotime( '-30 days' ) ) ); // BAD: Direct post access (breaks HPOS) $orders = get_posts( array( 'post_type' => 'shop_order', 'post_status' => 'wc-completed' ) ); update_post_meta( $order_id, 'custom_field', $value ); ``` ### WooCommerce CRUD Pattern (WOO-02, WOO-07) **WC_Data base class:** - All WooCommerce objects extend `WC_Data` - Data stores handle persistence (HPOS tables vs post tables) - Changes buffered until `->save()` called **Order CRUD:** ```php // GOOD: Complete order manipulation $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(); // Single save after all changes // BAD: Manual post status change wp_update_post( array( 'ID' => $order_id, 'post_status' => 'wc-processing' ) ); ``` **Product CRUD:** ```php // GOOD: WC_Product_Query for product lists $query = new WC_Product_Query( array( 'status' => 'publish', 'limit' => 10, 'category' => array( 'clothing' ), 'orderby' => 'date', 'order' => 'DESC' ) ); $products = $query->get_products(); // WARNING: WP_Query for products (future-breaking) $products = new WP_Query( array( 'post_type' => 'product', 'posts_per_page' => 10 ) ); ``` **Custom data store registration:** ```php // GOOD: Register custom data store 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; } ``` ### Payment Gateway Development (WOO-03, WOO-19) **WC_Payment_Gateway class structure:** ```php // GOOD: Complete payment gateway implementation 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: Always check HTTPS in production if ( ! is_ssl() && 'yes' !== $this->get_option( 'testmode' ) ) { wc_add_notice( __( 'SSL required', 'text-domain' ), 'error' ); return array( 'result' => 'failure' ); } // GOOD: Use payment_complete() not manual status change $order->payment_complete( $transaction_id ); return array( 'result' => 'success', 'redirect' => $this->get_return_url( $order ) ); } } ``` **CRITICAL security anti-patterns:** ```php // CRITICAL: Never store raw card data // BAD: update_post_meta( $order_id, 'card_number', $_POST['card_number'] ); $wpdb->insert( 'payment_tokens', array( 'card' => $_POST['card_number'] ) ); // CRITICAL: Never log card data // BAD: error_log( 'Card: ' . $_POST['card_number'] ); wc_get_logger()->debug( 'CVV: ' . $_POST['cvv'] ); // GOOD: Use tokenization $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(); ``` **Refund handling:** ```php // GOOD: Implement refund support public function process_refund( $order_id, $amount = null, $reason = '' ) { $order = wc_get_order( $order_id ); // Process refund via API $result = $this->api_refund( $order, $amount ); if ( $result->success ) { $order->add_order_note( sprintf( __( 'Refunded %s', 'text-domain' ), $amount ) ); return true; } return false; } ``` **Cross-reference:** - See wp-security-review for comprehensive security patterns - This focuses on WC payment-specific anti-patterns only ### Shipping Methods (WOO-04) **WC_Shipping_Method class structure:** ```php // GOOD: Complete shipping method implementation 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 ); } } ``` ### Custom Product Types (WOO-02) **Product type registration:** ```php // GOOD: Register custom product type 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: Product class extending 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: Register product class 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 Hooks Catalog (WOO-05, WOO-06) **Lifecycle hooks:** ```php // GOOD: Order lifecycle hooks 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 ); ``` **Product data hooks:** ```php // GOOD: Product admin hooks add_action( 'woocommerce_product_options_general_product_data', 'add_custom_field' ); add_action( 'woocommerce_process_product_meta', 'save_custom_field' ); ``` **Checkout field hooks:** ```php // GOOD: Add checkout field 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(); } } ``` ### Cart Operations (WOO-08) **Cart item data:** ```php // GOOD: Add custom cart item data 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; } ``` **Cart fees:** ```php // GOOD: Add custom fee 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 ); } } ``` **Cart validation:** ```php // GOOD: Validate cart contents 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' ); } } ``` ### Order Status Transitions (WOO-07) **Custom order status:** ```php // GOOD: Register custom order status 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 (%s)', 'Awaiting shipment (%s)', '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: Set order status $order = wc_get_order( $order_id ); $order->set_status( 'awaiting-shipment', 'Order ready for shipment' ); ``` ### Cart Fragments Performance (WOO-15) **Conditional dequeuing:** ```php // GOOD: Conditional cart fragments loading add_filter( 'woocommerce_get_script_data', 'conditional_cart_fragments', 10, 2 ); function conditional_cart_fragments( $data, $handle ) { if ( 'wc-cart-fragments' === $handle ) { // Only load on WC pages if ( ! is_woocommerce() && ! is_cart() && ! is_checkout() ) { return null; } } return $data; } // CRITICAL: Site-wide cart fragments loading // BAD: No conditional dequeue - loads on every page ``` **Mini-Cart Block alternative:** ```php // INFO: Recommend Mini-Cart Block migration // Mini-Cart Block has built-in performance optimizations // No cart fragments needed ``` ### Action Scheduler Patterns **Background processing:** ```php // GOOD: Action Scheduler for bulk operations 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 ) { // Export logic } // Schedule next batch if needed if ( count( $orders ) === 100 ) { as_enqueue_async_action( 'process_order_export', array( 'batch_id' => $batch_id + 1 ), 'wc-exports' ); } } // WARNING: wp_cron for heavy WC tasks // BAD: wp_schedule_event( time(), 'hourly', 'process_order_export' ); ``` ### Webhook Security (WOO-20) **Signature verification:** ```php // GOOD: Verify webhook signature function verify_wc_webhook( $payload, $signature, $secret ) { $expected = base64_encode( hash_hmac( 'sha256', $payload, $secret, true ) ); // CRITICAL: Use hash_equals to prevent timing attacks return hash_equals( $expected, $signature ); } // Webhook handler $payload = file_get_contents( 'php://input' ); $signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? ''; $delivery_id = $_SERVER['HTTP_X_WC_WEBHOOK_DELIVERY_ID'] ?? ''; // WARNING: Missing signature verification if ( ! verify_wc_webhook( $payload, $signature, $secret ) ) { http_response_code( 401 ); exit; } // GOOD: Check for duplicate delivery if ( get_transient( 'wc_webhook_' . $delivery_id ) ) { http_response_code( 200 ); exit; } set_transient( 'wc_webhook_' . $delivery_id, true, DAY_IN_SECONDS ); // GOOD: Process async via Action Scheduler as_enqueue_async_action( 'process_wc_webhook', array( 'payload' => $payload ) ); ``` ### Template Override Anti-Patterns (WOO-10, WOO-11, WOO-12) **Preserving hooks:** ```php // In child-theme/woocommerce/content-product.php // GOOD: Preserve all action hooks from original template do_action( 'woocommerce_before_shop_loop_item' ); do_action( 'woocommerce_before_shop_loop_item_title' ); // Custom content here do_action( 'woocommerce_shop_loop_item_title' ); do_action( 'woocommerce_after_shop_loop_item_title' ); do_action( 'woocommerce_after_shop_loop_item' ); // CRITICAL: Deleted hooks in template override // BAD: No do_action() calls - breaks plugin integration ``` **Version tracking:** ```php // GOOD: Template with version comment /** * Product loop template * * @version 8.9.0 */ // WARNING: Outdated version // Template version 3.6.0 when WC is 10.5 - may miss updates ``` **Hooks-first philosophy:** ```php // BETTER: Use hooks instead of template override add_action( 'woocommerce_shop_loop_item_title', 'add_custom_content', 15 ); function add_custom_content() { // Custom content via hook - no template override needed } // INFO: Template override where hook exists // Suggest using hook instead of copying entire template ``` **Cross-reference:** - See wp-theme-development for general template patterns ### Surface-Level Checks **WooCommerce Blocks checkout integration (WOO-14):** ```php // GOOD: Add checkout field via 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 extensions (WOO-09):** ```php // INFO: Custom REST endpoint registration 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' ); } ) ); } ``` **Coupon validation (WOO-21):** ```php // GOOD: Custom coupon validation 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; } ``` **Session handling (WOO-18):** ```php // WARNING: Custom session filter exceeding 30-day cap (WC 10.1+) // BAD: add_filter( 'wc_session_expiration', function() { return 60 * DAY_IN_SECONDS; // Exceeds 30-day cap } ); // GOOD: Respect 30-day cap add_filter( 'wc_session_expiration', function() { return 30 * DAY_IN_SECONDS; // Maximum allowed } ); ``` ## Search Patterns for Quick Detection (WOO-22) Use these `rg` commands and shell checks for quick WooCommerce scanning. Organized by severity. ### CRITICAL Patterns ```bash # HPOS declaration candidates # If this returns nothing in a WooCommerce extension, the plugin likely lacks HPOS declaration. rg -n "declare_compatibility\s*\(\s*['\"]custom_order_tables['\"]" . -g '*.php' # get_posts/WP_Query with shop_order rg -n "post_type.*shop_order|shop_order.*post_type" . -g '*.php' # Direct $wpdb queries against wp_posts for orders rg -n "\$wpdb.*wp_posts.*shop_order" . -g '*.php' # Raw card data storage/logging rg -n "card_number|card_cvv|cvv.*meta|card.*error_log" . -g '*.php' # Template overrides without do_action() calls find . -path "*/woocommerce/*.php" -exec rg -L "do_action|apply_filters" {} \; # Webhook signature handling candidates (manually confirm verification logic) rg -n "X-WC-Webhook-Signature|hash_hmac|verify" . -g '*.php' ``` ### WARNING Patterns ```bash # WP_Query with post_type=product (compare these result sets manually) rg -n "WP_Query|get_posts" . -g '*.php' rg -n "post_type.*product|product.*post_type" . -g '*.php' # Site-wide cart-fragments loading without conditional dequeue (manual context check) rg -n "wc-cart-fragments|woocommerce_get_script_data|is_woocommerce|is_cart" . -g '*.php' # wp_cron for bulk WC operations (manual context check) rg -n "wp_schedule_event|wp_cron|wc_|order|product" . -g '*.php' # Hardcoded API credentials rg -n "api_key.*=.*['\"][A-Za-z0-9]{20,}" . -g '*.php' # get_post_meta/update_post_meta for order fields rg -n "get_post_meta.*order_id|update_post_meta.*order_id" . -g '*.php' # Session filters exceeding 30-day cap (manual follow-up on returned values) rg -n "wc_session_expiration|wc_session_expiring" . -g '*.php' ``` ### INFO Patterns ```bash # Template overrides where hooks exist find . -path "*/woocommerce/*.php" -type f # Missing object caching for repeated product loads rg -n "wc_get_product" . -g '*.php' # Action Scheduler candidates rg -n "foreach.*wc_get_orders|foreach.*wc_get_products" . -g '*.php' # WC Blocks integration opportunities rg -n "woocommerce_register_additional_checkout_field|Store API" . -g '*.php' ``` **Note:** WC-specific patterns need different context than generic WP. `get_posts()` for non-order post types is valid. `WP_Query` for standard posts/pages is valid. Only flag when combined with WC-specific post types. ## WooCommerce Context Detection Context-aware review notes based on file structure and patterns: ### Extension/plugin **Detection:** Main plugin file with WC dependency check, HPOS declaration **Review focus:** Full HPOS + CRUD + hook audit **Most common context** ### Theme integration **Detection:** woocommerce/ directory in theme with template overrides **Review focus:** Template override quality, hooks preservation **Cross-reference:** wp-theme-development for theme patterns ### Payment gateway **Detection:** Class extending `WC_Payment_Gateway` **Review focus:** Heightened security review (never store raw cards, HTTPS check, webhook verification) **Cross-reference:** wp-security-review for general security ### Shipping method **Detection:** Class extending `WC_Shipping_Method` **Review focus:** calculate_shipping() review, zone support, rate calculation ### Custom product type **Detection:** Class extending `WC_Product` **Review focus:** Data store review, product type registration, class hierarchy ### WC Blocks integration **Detection:** Store API usage, checkout block extension points **Review focus:** Surface-level review, Additional Checkout Fields API **Cross-reference:** wp-block-development for deep block patterns ## Quick Reference: WooCommerce Development Patterns (WOO-23) Common WooCommerce patterns organized by concern. All examples follow WordPress PHP Coding Standards (spaces in parentheses, `array()` not `[]`, Yoda conditions). ### HPOS Compatibility Declaration **❌ BAD: Missing HPOS declaration** ```php 'shop_order', 'post_status' => 'wc-completed' ) ); update_post_meta( $order_id, 'custom_field', $value ); ``` **✅ GOOD: HPOS-compatible CRUD** ```php 'completed', 'limit' => 10 ) ); $order = wc_get_order( $order_id ); $order->update_meta_data( 'custom_field', $value ); $order->save(); ``` ### Order Meta Operations **❌ BAD: Direct meta functions** ```php update_meta_data( 'delivery_date', '2026-02-15' ); $order->save(); $date = $order->get_meta( 'delivery_date', true ); ``` ### Product Data Access **❌ BAD: WP_Query for products (future-breaking)** ```php 'product', 'posts_per_page' => 10 ) ); ``` **✅ GOOD: WC_Product_Query** ```php 'publish', 'limit' => 10, 'category' => array( 'clothing' ), 'orderby' => 'date', 'order' => 'DESC' ) ); $products = $query->get_products(); ``` ### Payment Gateway **❌ BAD: Raw card data storage, missing HTTPS check** ```php update_status( 'processing' ); // Manual status change return array( 'result' => 'success', 'redirect' => $this->get_return_url( $order ) ); } ``` **✅ GOOD: Tokenization, HTTPS check, payment_complete()** ```php get_option( 'testmode' ) ) { wc_add_notice( __( 'SSL required', 'text-domain' ), 'error' ); return array( 'result' => 'failure' ); } // Process via API (use tokenization, never store raw cards) $result = $this->api_charge( $order ); if ( $result->success ) { // Use payment_complete() not manual status change $order->payment_complete( $result->transaction_id ); return array( 'result' => 'success', 'redirect' => $this->get_return_url( $order ) ); } return array( 'result' => 'failure' ); } ``` ### Shipping Method **✅ GOOD: Complete shipping method** ```php 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 ); } } ``` ### Custom Product Type **✅ GOOD: Register and implement custom product type** ```php product_type = 'custom-product'; parent::__construct( $product ); } public function get_type() { return 'custom-product'; } } // Register product class 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; } ``` ### Cart Operations **✅ GOOD: Add cart item data** ```php cart->get_subtotal() > 100 ) { WC()->cart->add_fee( __( 'Handling fee', 'text-domain' ), 5 ); } } ``` ### Order Status Transitions **❌ BAD: Manual post status change** ```php $order_id, 'post_status' => 'wc-processing' ) ); ``` **✅ GOOD: Use WC_Order::set_status()** ```php set_status( 'processing', 'Payment received' ); // Automatically saved ``` **✅ GOOD: Use payment_complete() for payment flow** ```php payment_complete( $transaction_id ); ``` ### Template Override with Hook Preservation **❌ BAD: Deleted hooks in template override** ```php

  • get_price_html(); ?>
    • ``` **✅ GOOD: Preserve all action hooks** ```php

    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 ) { // Export logic } // Schedule next batch if needed if ( 100 === count( $orders ) ) { as_enqueue_async_action( 'process_order_export', array( 'batch_id' => $batch_id + 1 ), 'wc-exports' ); } } ``` ### Webhook Security **❌ BAD: Missing signature verification** ```php $payload ) ); ``` ### WooCommerce Blocks Checkout **✅ GOOD: Additional Checkout Fields API (WC 8.6+)** ```php 'namespace/gift-message', 'label' => __( 'Gift message', 'text-domain' ), 'location' => 'order', 'type' => 'text', 'attributes' => array( 'maxLength' => 200 ) ) ); } // Access field value $order = wc_get_order( $order_id ); $gift_message = $order->get_meta( 'namespace/gift-message' ); ``` ### REST API Extension **✅ GOOD: Custom REST endpoint with authentication** ```php 'GET', 'callback' => 'cust …(truncated)