WC Product Migration

A WordPress/WooCommerce plugin for bulk importing products with variations from JSON files.

Features

• Admin Upload Interface: User-friendly admin page under WooCommerce menu
• JSON Import: Upload JSON files containing product data
• Product Variations: Automatically creates variable products with flavor-based variations
• Multi-Taxonomy Support: Handles flavors, tags, brands, and categories
• Term Management: Auto-creates missing taxonomy terms
• Stock Management: Flexible stock control per product with manage_stock option
• Product Export: Export products to JSON format for data portability
• Progress Tracking: Real-time import progress with detailed logs
• OOP Architecture: Clean, modular code with single-responsibility principle
• Error Resilience: Gracefully handles errors without stopping entire import

Installation

1. Place the jpjuliao-wc-product-migration folder in /wp-content/plugins/
2. Activate the plugin from WordPress admin
3. Navigate to WooCommerce → Product Importer
4. Upload your JSON file

JSON Format

[
  {
    "title": "DOZO BUBBLE HASH",
    "flavor": "American Pie, Berry Zurbert, Emperors Glue",
    "tags": "THCP, Hash, Premium",
    "brand": "DOZO",
    "price": 2999,
    "description": "Full description text...",
    "short_description": "Short version...",
    "category": "Concentrates, Extracts",
    "manage_stock": true
  }
]

Field Descriptions

• title (string): Product name
• flavor (string): Comma-separated flavor values - creates variations for each
• tags (string): Comma-separated product tags
• brand (string): Product brand
• price (integer): Price in cents (2999 = $29.99)
• description (string): Full product description
• short_description (string): Brief description
• category (string): Comma-separated product categories
• manage_stock (boolean, optional): Enable/disable stock management. Defaults to true if not provided

Taxonomies

• pa_flavor: Product attribute for variations
• product_tag: Product tags
• product_brand: Product brands
• product_cat: Product categories

All taxonomy terms are automatically created if they don't exist.

Plugin Structure

jpjuliao-wc-product-migration/
├── jpjuliao-wc-product-migration.php          # Main plugin file
├── includes/
│   ├── class-plugin.php                 # Main orchestrator (singleton)
│   ├── utilities/
│   │   ├── class-validator.php          # JSON validation
│   │   └── class-logger.php             # Logging system
│   ├── admin/
│   │   ├── class-admin-page.php         # Admin interface
│   │   └── class-upload-handler.php     # File upload handler
│   └── import/
│       ├── class-product-importer.php   # Import orchestrator
│       ├── class-variation-manager.php  # Product/variation creation
│       └── class-term-manager.php       # Taxonomy term management
├── implementation-plan.md               # Technical documentation
└── README.md                            # This file

Class Architecture

Core Classes

Plugin (Singleton - JPJULIAO\WC_Product_Migration\Plugin)

• Main entry point and dependency injector
• Manages plugin initialization
• Verifies WooCommerce is active

Validator (JPJULIAO\WC_Product_Migration\Validator)

• Validates JSON structure
• Validates individual product data including manage_stock flag
• Returns detailed error messages

Logger (JPJULIAO\WC_Product_Migration\Logger)

• Tracks import progress
• Logs term operations
• Stores logs in WordPress transients
• Supports multiple log levels (info, warning, error)

Term_Manager (JPJULIAO\WC_Product_Migration\Term_Manager)

• Processes comma-separated taxonomy terms
• Handles term creation and validation
• Deduplicates and trims whitespace
• Supports all four taxonomies

Variation_Manager (JPJULIAO\WC_Product_Migration\Variation_Manager)

• Creates variable products with stock control
• Assigns taxonomies to products
• Creates product variations based on flavors
• Registers product attributes
• Handles stock management settings

Product_Importer (JPJULIAO\WC_Product_Migration\Product_Importer)

• Orchestrates the entire import process
• Validates products before creation
• Handles import errors gracefully
• Returns import summary

Product_Exporter (JPJULIAO\WC_Product_Migration\Product_Exporter)

• Exports all products to JSON format
• Includes all product fields and stock settings
• Provides downloadable JSON files

Admin_Page (JPJULIAO\WC_Product_Migration\Admin_Page)

• Renders admin interface
• Handles menu registration
• Displays import logs and results

Upload_Handler (JPJULIAO\WC_Product_Migration\Upload_Handler)

• Handles AJAX file uploads
• Validates file type and content
• Triggers import process
• Provides error feedback

Usage

1. Click "Product Importer" under WooCommerce menu
2. Download template JSON using "Download Template" button or create your own
3. Select your JSON file and click "Import Products"
4. Monitor progress in the admin page
5. Check logs for any errors or warnings

Features

Automatic Term Creation

• If a category, brand, or tag doesn't exist, it's automatically created
• Terms are trimmed of whitespace and deduplicated

Flavor Variations

• Each flavor value creates a separate product variation
• Variations inherit pricing from parent product
• Stock is managed per-variation

Stock Management

• Control whether products use stock management via manage_stock field
• Set to true to enable stock tracking (default)
• Set to false to disable stock management
• Stock quantities default to 0 for new products

Product Export

• Export all published products to JSON format
• Includes all product data and current stock settings
• Useful for data backup and migration to other stores

Error Handling

• Invalid products are logged but import continues
• Missing terms are created automatically
• All operations are logged for audit trail

Progress Tracking

• Real-time progress updates
• Detailed logs with timestamps
• Color-coded log levels (info, warning, error)

Dependencies

• WordPress 5.0+
• WooCommerce 3.0+
• PHP 7.0+

Requirements Met

✅ OOP architecture with single-responsibility principle ✅ PHP namespaces for proper code organization ✅ DRY code patterns (reusable Term_Manager for all taxonomies) ✅ Dependency injection throughout ✅ Admin upload interface with progress tracking ✅ Multi-taxonomy support ✅ Automatic term validation and creation ✅ Comprehensive logging ✅ Error resilience ✅ Product variations based on flavor attributes ✅ Stock management control per product ✅ Product export to JSON format

Next Steps (Optional Enhancements)

• Add support for product images
• Add batch processing for large imports
• Add CSV import format
• Add duplicate prevention
• Add product update preview before import
• Add attribute support beyond flavors
• Add bulk product deletion feature