qdr.app.woo.plugins/studiou-wc-ord-print-statuses/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a WordPress plugin that extends WooCommerce functionality to manage print orders sent to third-party providers. It adds custom order statuses ("Prepare to Printing" and "In Printing"), bulk actions, CSV export/import capabilities, and tracking fields specific to the printing workflow.

Plugin Details:

• Text Domain: studiou-wc-ord-print-statuses
• Current Version: 1.3.2
• Requires: WordPress 5.8+, WooCommerce 3.0+, PHP 7.2+
• Tested with: WordPress 6.8.3, WooCommerce 10.2.2

Recent Changes

Version 1.3.2 (2025-10-18)

Bug Fix: Empty prod_var_type column in CSV export

Fixed an issue where the prod_var_type column was always empty in the "Prepare to Printing Export" CSV file.

Root Cause: The SQL query in Studiou_DB_Manager::get_orders_for_printing() was incorrectly using the wc_product_attributes_lookup table to retrieve product variation attributes. This table stores product-level attribute data (for parent products), not the specific attribute values for individual variations.

Solution: Modified the query (lines 55-65 in includes/class-db-manager.php) to:

1. Join with wp_postmeta table instead of wc_product_attributes_lookup
2. Look for meta_key = 'attribute_pa_format' which stores the variation's format attribute value
3. Join with wp_terms using the slug field (matching against meta_value) instead of term_id

HPOS Compatibility Declaration

Added explicit HPOS (High-Performance Order Storage) compatibility declaration to prevent WooCommerce warnings.

Solution: Added before_woocommerce_init hook in the main plugin file to declare compatibility with WooCommerce custom order tables using FeaturesUtil::declare_compatibility().

Files Changed:

• includes/class-db-manager.php - Updated LEFT JOIN logic for product_variations_attr and product_variations_name tables
• studiou-wc-ord-print-statuses.php - Added HPOS compatibility declaration

Impact:

• The prod_var_type column in exported CSV files now correctly displays the Format attribute value (e.g., "A4", "A5") for each product variation
• Plugin no longer shows HPOS incompatibility warnings in WooCommerce

Tested On:

• WordPress 6.8.3
• WooCommerce 10.2.2 (with HPOS enabled)

Architecture

Manager-Based Pattern

The plugin uses a manager-based architecture where the main plugin class (Studiou_WC_Ord_Print_Statuses) initializes specialized manager classes that handle distinct concerns:

1. Order_Status_Manager (includes/class-order-status-manager.php)

   • Registers custom order statuses: wc-to-print and wc-in-print
   • Handles status transitions and automatically updates metadata timestamps
   • Hooks into WooCommerce payment completion to set orders to "processing"

2. Order_Fields_Manager (includes/class-order-fields-manager.php)

   • Adds "Print Information" section to order edit pages
   • Manages fields: to_print_date, in_print_date, external_ref_ord_no, external_ref_ord_delivered

3. Bulk_Actions_Manager (includes/class-bulk-actions-manager.php)

   • Registers bulk actions: "Prepare to Printing Export", "Set Status to Prepare to Printing", "Set Status to In Printing"
   • Generates CSV exports with complex product data (categories, variations, images)

4. Custom_Columns_Manager (includes/class-custom-columns-manager.php)

   • Adds custom columns to WooCommerce orders list: "To Print Date", "In Print Date", "External Order Number"

5. Import_Manager (includes/class-import-manager.php)

   • Provides admin UI under WooCommerce menu for importing CSV protocols
   • Handles InPrint Protocol (sets orders to "in-print" with external references)
   • Handles Delivered Protocol (sets orders to "completed" with delivery timestamp)

6. Order_Search_Manager (includes/class-order-search-manager.php)

   • Extends WooCommerce order search to include external reference order numbers

7. Studiou_DB_Manager (includes/class-db-manager.php)

   • Centralized database operations using static methods
   • Contains complex SQL for export query joining orders, products, variations, categories, and images
   • Handles CSV parsing and protocol imports

Key Database Operations

The export query in Studiou_DB_Manager::get_orders_for_printing() performs a complex join across:

• wp_wc_orders (order data)
• wp_wc_order_product_lookup (order products)
• wp_posts (products and variations)
• wp_postmeta (product variation attributes - specifically 'attribute_pa_format')
• wp_terms and wp_term_taxonomy (product categories and variation attribute values)
• wp_postmeta (product images via '_thumbnail_id' meta)

This query extracts: order number, product category, product name, variation name, variation type, image URL, quantity, and customer email.

Order Metadata Keys

• to_print_date - Timestamp when order moved to "Prepare to Printing" status
• in_print_date - Timestamp when order moved to "In Printing" status
• external_ref_ord_no - External order number from print provider
• external_ref_ord_date - Date from external print provider
• external_ref_ord_delivered - Delivery timestamp

Development Commands

Logging

The plugin includes a simple logging utility (includes/utils-log.php):

• UtilsLog::log($message) - Logs to WordPress error log when WP_DEBUG is enabled
• Check logs in wp-content/debug.log if WP_DEBUG_LOG is enabled

WordPress/WooCommerce Hooks

All managers register their hooks in constructors. Common patterns:

• add_action('init', ...) - Register post statuses
• add_filter('wc_order_statuses', ...) - Modify WooCommerce status lists
• add_filter('bulk_actions-woocommerce_page_wc-orders', ...) - Add bulk actions
• add_action('woocommerce_admin_order_data_after_order_details', ...) - Display custom fields

Testing

When testing status changes:

1. Enable WP_DEBUG in wp-config.php to see log output
2. Check that metadata is properly set when statuses change
3. Test bulk actions with multiple orders to verify CSV generation
4. Test import functionality with properly formatted CSV files

CSV Formats

Export Format (Prepare to Printing):

• Headers: order_no, prod_cat, prod_name, prod_var, prod_var_type, prod_img_url, qty, email

InPrint Protocol Import Format:

• Required headers: order_no, externalorder, externalorderdate

Delivered Protocol Import Format:

• Required header: order_no

Localization

The plugin supports internationalization:

• Text domain: studiou-wc-ord-print-statuses
• Translation files in languages/ directory
• Czech localization (cs_CZ) already implemented
• Use WordPress __(), _e(), _n_noop(), _x() functions for all user-facing strings

Important Considerations

1. HPOS Compatibility: The plugin is fully compatible with WooCommerce High-Performance Order Storage (HPOS)

   • Uses woocommerce_page_wc-orders hooks for HPOS compatibility
   • Uses {$wpdb->prefix}wc_orders table (HPOS custom table) in SQL queries
   • Uses wc_get_order() which works with both HPOS and legacy systems
   • Declares compatibility via FeaturesUtil::declare_compatibility('custom_order_tables', ...)

2. Status Slug Naming: Custom statuses use wc- prefix internally but display without prefix (wc-to-print vs "Prepare to Printing")

3. CSV Output: The prepare_to_printing_export bulk action terminates with exit after outputting CSV headers, preventing further PHP execution

4. Database Queries: Direct SQL queries use $wpdb->prepare() implicitly through intval() for order IDs. Always sanitize inputs when modifying database operations.

5. Admin Menu: Import functionality is added as a submenu under WooCommerce admin menu, requires manage_woocommerce capability