Import WooCommerce Products Plugin

A comprehensive WordPress plugin for importing products from Excel (.xlsx) and CSV (.csv) files into WooCommerce with advanced logging, product updates, and error handling.

Features

🚀 File Upload Support

• Excel Files: Support for .xlsx format
• CSV Files: Support for .csv format
• File Validation: Automatic file type detection and validation
• Secure Upload: WordPress security measures and file handling

📊 Comprehensive Import Logging

• Import Statistics: Total rows processed, products created/updated
• Detailed Logs: Complete import history with timestamps
• Error Tracking: Row-by-row error logging with specific error messages
• Import History: View recent import logs in admin dashboard

🔄 Smart Product Management

• Product Creation: New products are created with all specified attributes
• Product Updates: Existing products with same names are automatically updated
• Category Management: Automatic category creation and assignment
• Hierarchical Categories: Import categories from JSON with unlimited nesting levels
• Image Handling: Support for multiple product images and galleries with smart filename matching

📈 Import Statistics

• Real-time Progress: Live updates during import process
• Summary Reports: Complete import results with success/error counts
• Performance Metrics: Import timing and efficiency data
• Data Validation: Row-by-row validation and error reporting

🛡️ Error Handling & Validation

• Comprehensive Error Logging: Detailed error messages for troubleshooting
• Row-level Error Tracking: Identify specific problematic rows
• Graceful Failure Handling: Continue processing even if individual rows fail
• User-friendly Error Messages: Clear feedback for administrators

Requirements

• WordPress: 5.0 or higher
• WooCommerce: 3.0 or higher (must be installed and activated)
• PHP: 8.2.0 or higher (compatible with PHP 8.2.27)
• PhpSpreadsheet: Library for Excel/CSV processing (version 1.29+)

Installation

1. Upload Plugin: Place the plugin folder in /wp-content/plugins/
2. Install Dependencies: Run composer install in the plugin directory to install PhpSpreadsheet
3. Activate Plugin: Activate through WordPress admin panel
4. Verify WooCommerce: Ensure WooCommerce is active

Installing Dependencies

The plugin requires the PhpSpreadsheet library for Excel/CSV processing. To install it:

cd /path/to/wp-content/plugins/import-woo-products
composer install

Or if you don't have a composer.json file:

composer require phpoffice/phpspreadsheet

Usage

Basic Import Process

1. Navigate to Admin: Go to WordPress Admin → Import Products
2. Upload File: Select Excel (.xlsx) or CSV (.csv) file
3. Start Import: Click "Import Products" button
4. Monitor Progress: View real-time import progress and results
5. Review Logs: Check import logs for detailed information

Import Categories

1. Navigate to Categories: Go to WordPress Admin → Import Products → Import Categories
2. Upload JSON File: Select a JSON file with hierarchical category structure
3. Start Import: Click "Import Categories" button
4. View Results: Check categories import logs for detailed information

File Format Requirements

Products (Excel/CSV)

The plugin expects files with the following column structure:

Categories (JSON)

The JSON file should follow this hierarchical structure:

{
  "Parent Category": {
    "Child Category 1": {},
    "Child Category 2": {
      "Grandchild Category": {}
    }
  }
}

Category Detection

• Category Headers: Rows with only the first column filled are treated as category headers
• Format: "CategoryName:" (colon is automatically removed)
• Nesting: All products below a category header are assigned to that category

Smart Image Matching

The plugin uses advanced algorithms to match image filenames from your import files to the actual media library files, handling common WordPress filename issues:

• Special Character Support: Automatically matches Swedish characters (å, ä, ö) and other special characters
• Filename Sanitization: Handles WordPress automatic filename cleaning (removes special chars, adds numbers)
• Multiple Matching Strategies: Uses 7 different approaches to find images:
  1. Direct filename match in media library
  2. Sanitized filename matching
  3. Title-based matching (preserves original filename)
  4. Sanitized title matching
  5. Filename without numbers (handles WordPress duplicate numbering)
  6. Fuzzy matching for special characters
  7. Meta-based filename matching
• Image Processing Logs: Detailed tracking of which images were found/not found

Admin Interface

Import Dashboard

• File Upload Form: Simple drag-and-drop or file selection
• Import Results: Real-time display of import progress and results
• Error Summary: Quick overview of any issues encountered

Import Logs Table

• Recent Imports: Last 10 import operations
• Status Tracking: Success, failure, or completion status
• Statistics: Products created, updated, and error counts
• Action Buttons: View detailed information for each import

Technical Details

Database Storage

• Import Logs: Stored in WordPress options table
• Log Retention: Automatically keeps last 10 import logs
• Data Structure: Comprehensive logging with timestamps and metadata

Performance Features

• Batch Processing: Efficient row-by-row processing
• Memory Management: Optimized for large file imports
• Error Recovery: Continues processing despite individual row failures

Security Features

• User Capability Check: Only users with 'manage_options' can import
• File Type Validation: Strict file extension checking
• Data Sanitization: Proper escaping and validation of all data

Troubleshooting

Common Issues

1. PhpSpreadsheet Not Found

   • Install via Composer: composer require phpoffice/phpspreadsheet
   • Or manually include the library files

2. WooCommerce Not Active

   • Install and activate WooCommerce plugin
   • Ensure WooCommerce is properly configured

3. Import Failures

   • Check file format and column structure
   • Verify file permissions and upload limits
   • Review error logs for specific issues

4. Memory Issues

   • Increase PHP memory limit
   • Process smaller files in batches
   • Check server resource constraints

Error Log Analysis

• Row Numbers: Identify specific problematic rows
• Error Messages: Clear descriptions of what went wrong
• Product Names: See which products had issues
• Timing Information: Track when errors occurred

Image Matching Issues

If images are not being linked correctly:

1. Check Filename Variations: WordPress may have stored the file with a different name

   • Original: Högstående_dek.png
   • WordPress: Hogstaende_dek.2.png
   • The plugin will automatically try multiple matching strategies

2. Verify Media Library: Ensure images are uploaded to WordPress media library

3. Check File Extensions: The plugin automatically handles common extensions (.jpg, .jpeg, .png, .gif, .webp)

4. Review Image Processing Logs: Check import results for detailed image matching information

Common Solutions:

• Upload images to media library before importing products
• Use consistent naming conventions in your import files
• Check that image filenames in import files match media library files

Development

Plugin Structure

import-woo-products/
├── import-woo-products.php    # Main plugin file
├── vendor/                    # PhpSpreadsheet library
└── README.md                 # This documentation

Hooks and Filters

• Admin Menu: admin_menu action
• File Processing: Custom functions for import logic
• Logging System: WordPress options API for data storage

Extending the Plugin

• Custom Fields: Add support for additional product attributes
• Import Formats: Extend to support other file types
• Advanced Logging: Integrate with external logging systems
• API Integration: Add REST API endpoints for programmatic imports

Support

For technical support or feature requests:

• Check the error logs for specific issues
• Verify all requirements are met
• Test with sample files to isolate problems
• Review WordPress and WooCommerce compatibility

Changelog

Version 2.0

• Added CSV file support
• Implemented comprehensive logging system
• Added product update functionality
• Enhanced error handling and reporting
• Added import statistics and history

Version 1.0

• Basic Excel import functionality
• Product creation with categories
• Image linking support
• Simple admin interface

License

This plugin is provided as-is for educational and development purposes. Please ensure compliance with WordPress and WooCommerce licensing requirements.