qdr.app.woo.plugins/studiou-wc-product-cat-manage/CLAUDE.md

CLAUDE.md

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

Project Overview

QDR - Studiou WC Export/Import Product Categories is a WordPress plugin that extends WooCommerce to provide batch export/import functionality for product categories and category manipulation tools.

Current Version: 1.3.0

Requirements

• WordPress 6.8.1+
• PHP 8.2+
• WooCommerce 9.8+
• WooCommerce Protected Categories 2.7+ (optional, for visibility features)

Plugin Architecture

Core Files

• studiou-wc-product-cat-manage.php - Main plugin file containing:
  • Plugin initialization and dependency loading
  • Admin menu registration under Products menu
  • Asset enqueueing for admin pages
  • WooCommerce HPOS compatibility declaration
  • Text domain loading for translations

Class Structure (includes/)

The plugin follows a modular class-based architecture:

• class-studiou-wc-product-cat-manage-db.php - Database operations layer

  • Handles all database queries for product categories
  • Manages category hierarchy (parent/child relationships)
  • Provides category formatting and data retrieval
  • Interfaces with WooCommerce taxonomy and WooCommerce Protected Categories plugin

• class-studiou-wc-product-cat-manage-export.php - Export functionality

  • Generates CSV files from product categories
  • Includes all category properties (name, slug, parent, description, display-type, visibility, protected-passwords)
  • Handles UTF-8 encoding and proper CSV formatting

• class-studiou-wc-product-cat-manage-import.php - Import functionality

  • Processes CSV files with operations: 'A' (add), 'U' (update), 'D' (delete)
  • Validates data and handles errors
  • Creates/updates/deletes categories based on operation column
  • Manages WooCommerce Protected Categories settings

• class-studiou-wc-product-cat-manage-manipulator.php - Category manipulation operations

  • Move products between categories (removes from source, adds to target)
  • Batch description updates for multiple categories
  • Delete products in category (permanently deletes products and variants)
  • Uses direct database queries for reliable product detection
  • Batch processing for delete operations (10 products per batch)

Views (views/)

• import.php - Import page UI
• export.php - Export page UI
• manipulations.php - Category manipulations page UI with three operations:
  • Move products between categories (two dropdowns + "Do" button)
  • Batch description between categories (checkbox list + textarea + "Do" button)
  • Delete products in category (checkbox list + "Delete" button + progress bar)

Assets

• assets/css/admin.css - Admin styling including:
  • Progress bar styling
  • Warning message styling (yellow background for destructive operations)
  • Danger button styling (red for delete operations)
• assets/js/admin.js - Admin JavaScript including:
  • AJAX handlers for all operations
  • Batch processing logic for delete operations
  • Real-time progress bar updates
  • Confirmation dialogs for destructive operations

Translations

• languages/ - Contains .pot, .po, and .mo files
• Text domain: studiou-wc-product-cat-manage
• All user-facing strings must be wrapped in translation functions: __(), _e(), sprintf()

CSV Format

CSV files use comma separators, double-quote string isolation, UTF-8 encoding:

Column	Description
name	Category name (required, used as identifier)
url-name	URL slug
parent-name	Parent category name (empty if root)
description	Category description
display-type	Values: 'default', 'products', 'subcategories', 'both'
visibility	Values: 'public', 'protected' (WooCommerce Protected Categories)
protected-passwords	Pipe-separated passwords (|) if visibility='protected'
operation	'A' (add), 'U' (update), 'D' (delete)

Development Guidelines

When Modifying Code

1. Translations: All new user-facing strings must use __() or _e() with text domain 'studiou-wc-product-cat-manage'
2. Security: Always validate and sanitize user input, use nonces for form submissions
3. WooCommerce Integration: Use WooCommerce taxonomy 'product_cat' for all category operations
4. Error Handling: Provide clear error messages and validation feedback
5. Compatibility: Maintain HPOS (High-Performance Order Storage) compatibility declaration
6. Direct Exits: Always include if (!defined('WPINC')) { die; } at top of PHP files
7. Batch Processing: For operations on large datasets, use batch processing (10 items per batch recommended)
8. Destructive Operations: Always include confirmation dialogs and warning messages for operations that cannot be undone
9. Progress Tracking: For long-running operations, implement real-time progress bars

Plugin Constants

STUDIOU_WCPCM_VERSION        // Plugin version
STUDIOU_WCPCM_PLUGIN_DIR     // Plugin directory path
STUDIOU_WCPCM_PLUGIN_URL     // Plugin URL
STUDIOU_WCPCM_PLUGIN_BASENAME // Plugin basename

Admin Menu Structure

All pages are added under Products menu:

• Import Product Categories (slug: studiou-import-product-categories)
• Export Product Categories (slug: studiou-export-product-categories)
• Category Manipulations (slug: studiou-category-manipulations)
  • Move products between categories
  • Batch description between categories
  • Delete products in category

Key Integration Points

• WooCommerce Protected Categories: Plugin extends category visibility with 'public'/'protected' settings and password protection
• Product Assignment: When moving products, the plugin modifies product-category term relationships while preserving other category assignments
• Hierarchy Management: Categories maintain parent-child relationships via parent-name field
• Product Deletion: Uses WooCommerce wc_get_product() and product->delete(true) for proper product deletion
  • Automatically handles variable products by deleting all variations first
  • Force delete (true parameter) ensures permanent removal bypassing trash
  • Processes in batches to prevent PHP timeouts and memory issues

Testing Notes

• Test import/export with categories that have special characters, quotes, commas
• Test category hierarchy (parent/child relationships)
• Test moving products between categories when products have multiple category assignments
• Test batch description updates with multiline text
• Test delete products operation with:
  • Simple products
  • Variable products with multiple variations
  • Products in multiple categories
  • Large numbers of products (test batch processing)
  • Edge cases: empty categories, categories with only variations
• Verify translations are properly loaded
• Verify progress bar updates correctly during delete operations
• Verify confirmation dialogs appear for destructive operations

AJAX Handlers

The plugin registers the following AJAX actions:

1. studiou_wcpcm_import - Handles CSV import
2. studiou_wcpcm_export - Generates CSV export
3. studiou_wcpcm_move_products - Moves products between categories
4. studiou_wcpcm_batch_description - Updates descriptions for multiple categories
5. studiou_wcpcm_delete_products - Initial request to get product IDs for deletion
6. studiou_wcpcm_delete_products_batch - Processes product deletion in batches

All AJAX handlers include:

• Nonce verification (studiou-wcpcm-nonce)
• Permission checks (manage_woocommerce capability)
• Output buffer cleaning to prevent JSON corruption
• Comprehensive error logging when WP_DEBUG is enabled