WP Manifestindependent plugin directory
manifest / ecommerce / planet-product-sync

Planet Product Sync

Syncs Planet products and categories to WooCommerce using custom tables, MD5 hash-based change detection, full reconciliation, and level-by-level category comparison.

by H M Shahadul Islam · github.com/shahadul878/planet-product-sync · website

★ 0stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/shahadul878/planet-product-sync/archive/refs/heads/master.zip
Readme github.com/shahadul878/planet-product-sync ↗

A WordPress plugin that synchronizes Planet products and categories to WooCommerce using custom database tables, MD5 hash-based change detection, and full reconciliation capabilities.

Features

  • Three-Level Category Sync: Automatically syncs 1st, 2nd, and 3rd level categories from Planet API
  • Smart Product Sync: Fetches complete product details with MD5 hash-based change detection
  • Custom Database Tables: High-performance custom tables for categories, products, and sync logs
  • WooCommerce Integration: Seamless integration with WooCommerce products and categories
  • Reconciliation: Built-in tools to ensure data consistency between Planet and WooCommerce
  • Manual & Automatic Sync: Trigger sync manually or schedule automatic synchronization
  • Comprehensive Logging: Track all sync activities with detailed logging
  • Image Handling: Automatically downloads and attaches product images
  • Deletion Detection: Identifies and handles products removed from Planet API

Requirements

  • WordPress 5.8 or higher
  • PHP 7.4 or higher
  • WooCommerce 5.0 or higher

Installation

  1. Upload the planet-product-sync folder to /wp-content/plugins/
  2. Activate the plugin through the 'Plugins' menu in WordPress
  3. Go to WooCommerce → Products → Planet Sync

Database Tables

The plugin creates three custom tables:

wp_planet_categories

Stores category data with parent-child relationships and MD5 hashes.

Column Type Description
id BIGINT Local ID
planet_id INT API category ID
level TINYINT Category level (1, 2, or 3)
name VARCHAR(255) Category name
slug VARCHAR(255) Category slug
desc LONGTEXT Description
parents JSON API parent IDs
parent_local_id BIGINT Local parent reference
woo_term_id BIGINT WooCommerce term ID
hash CHAR(32) MD5 hash
last_synced DATETIME Last sync timestamp

wp_planet_products

Stores product data with full JSON and hash tracking.

Column Type Description
id BIGINT Local ID
planet_slug VARCHAR(255) Unique API slug
planet_id VARCHAR(255) API internal ID
title VARCHAR(255) Product title
data_json LONGTEXT Raw JSON from API
category_ids JSON Linked category IDs
hash CHAR(32) MD5 hash
woo_product_id BIGINT WooCommerce product ID
status ENUM active/deleted/pending
last_synced DATETIME Last sync timestamp

wp_planet_sync_log

Activity logging for monitoring and debugging.

Column Type Description
id BIGINT Log ID
type ENUM category/product/system
action ENUM create/update/delete/skip/error
slug_or_id VARCHAR(255) Reference identifier
message TEXT Log message
created_at DATETIME Timestamp

Usage

Manual Sync

  1. Navigate to WooCommerce → Products → Planet Sync
  2. Click one of the sync buttons:
    • Sync All: Syncs both categories and products
    • Sync Categories: Syncs only categories
    • Sync Products: Syncs only products

Automatic Sync

  1. Go to WooCommerce → Products → Planet Sync
  2. Scroll to Settings section
  3. Check Enable automatic synchronization
  4. Choose sync frequency (Hourly or Daily)
  5. Click Save Settings

Category Comparison

The comparison tool provides a detailed level-by-level comparison between remote (API) and local (database) categories:

  1. Click Compare Categories button (green button in admin)
  2. Review the detailed comparison showing:
    • Categories missing in local database (need to be added)
    • Categories in local but not in remote API (will be removed)
    • Categories with different data (need updates)
    • Categories that are identical (up to date)
  3. View statistics per level (Level 1, 2, and 3)
  4. Click Sync All Categories Now to synchronize based on the comparison
  5. Refresh the page after sync to see updated results

Product-Category Assignment Check

The product-category checker diagnoses and fixes category assignments:

  1. Click Check Product Categories button (blue button in admin)
  2. Review the assignment analysis showing:
    • Total products and assignment status
    • Products with correct assignments
    • Products with mismatched assignments
    • Products without categories
    • Unmapped categories (categories referenced but not in database)
  3. View sample products with detailed category mapping
  4. Click Fix All Category Assignments to reassign all categories correctly
  5. The tool shows both expected (from database) and actual (from WooCommerce) categories

Reconciliation

The reconciliation tool checks for inconsistencies between your custom tables and WooCommerce:

  1. Click Reconcile WooCommerce button
  2. Review the report showing:
    • Orphaned WooCommerce items
    • Missing WooCommerce items
    • Hash mismatches
    • Category assignment issues
  3. The tool automatically fixes detected issues

Settings

Auto Sync

Enable or disable automatic synchronization.

Sync Frequency

  • Hourly: Runs sync every hour
  • Daily: Runs sync once per day

Delete Handling

What to do with WooCommerce products when deleted from Planet API:

  • Move to Trash: Moves products to trash (default)
  • Keep Products: Leaves products unchanged
  • Permanently Delete: Removes products completely

Debug Mode

Enables detailed logging to WordPress debug.log (requires WP_DEBUG).

API Configuration

The plugin connects to Planet API using:

  • Base URL: https://www.planet.com.tw/api
  • API Key: Configured in the main plugin file

API Endpoints Used

  • /getProductList - Fetch product list
  • /getProductBySlug - Fetch product detail
  • /getProduct1stCategoryList - Fetch 1st level categories
  • /getProduct2ndCategoryList - Fetch 2nd level categories
  • /getProduct3rdCategoryList - Fetch 3rd level categories

How It Works

Category Sync Flow

  1. Fetches all three category levels from API
  2. Builds category map by planet_id
  3. Processes categories in hierarchy order (1st → 2nd → 3rd)
  4. For each category:
    • Generates MD5 hash of category data
    • Compares with stored hash
    • If unchanged, skips
    • If new/changed, creates/updates in both custom table and WooCommerce
  5. Cleans up deleted categories

Product Sync Flow

  1. Fetches product list from API
  2. For each product:
    • Fetches full product detail
    • Generates MD5 hash
    • Compares with stored hash
    • If unchanged, skips
    • If new/changed:
      • Updates custom table
      • Creates/updates WooCommerce product
      • Downloads and attaches images
      • Maps categories
      • Stores metadata
  3. Marks missing products as deleted
  4. Optionally removes from WooCommerce

MD5 Hash Detection

$hash = md5(json_encode($data));

Hash is compared on each sync. If identical, the item is skipped, saving processing time and preventing unnecessary updates.

Logging

All sync activities are logged to the wp_planet_sync_log table:

  • View Logs: Check the Sync Log section in the admin interface
  • Filter Logs: Filter by type (category/product/system) and action
  • Clear Logs: Remove old logs to save database space
  • Debug Mode: Enable for additional logging to debug.log

Troubleshooting

Sync Takes Too Long

  • Sync products in smaller batches
  • Increase PHP max_execution_time
  • Use Action Scheduler if available

Products Not Updating

  • Check sync logs for errors
  • Verify API connection with Test API button
  • Run reconciliation to fix inconsistencies

Categories Not Hierarchical

  • Ensure parent categories are synced first
  • Run category sync before product sync
  • Check reconciliation report

Images Not Downloading

  • Verify image URLs are accessible
  • Check WordPress media upload permissions
  • Review error logs

Development

Hooks & Filters

Actions:

  • planet_auto_sync - Triggered during automatic sync

Helper Functions:

  • planet_sync_all() - Main sync function
  • planet_get_md5_hash($object) - Generate MD5 hash

Extending the Plugin

Create custom sync handlers:

add_action('planet_auto_sync', 'my_custom_sync_handler');

function my_custom_sync_handler() {
    // Your custom sync logic
}

Uninstallation

To completely remove the plugin:

  1. Deactivate the plugin
  2. Optionally, add this to your theme's functions.php to drop tables:
Planet_Sync_Database::drop_tables();

Support

For issues or questions:

Important Notes

Category Uniqueness

The plugin handles cases where the same category ID exists across different levels (1st, 2nd, 3rd). Categories are uniquely identified by the combination of planet_id and level. If you have existing data, you may need to:

  1. Deactivate and reactivate the plugin to recreate tables with the correct unique index
  2. Run a fresh category sync
  3. Run reconciliation to fix any issues

Slug Conflicts

When the same category name appears at different levels (e.g., "Wireless Router" as both 2nd and 3rd level), the plugin automatically:

  • Appends the level number to the slug for levels 2 and 3 when conflicts occur
  • Maintains proper parent-child relationships
  • Ensures WooCommerce categories are correctly hierarchical

Changelog

1.0.1 (2025-10-15)

  • Added: Category comparison tool for detailed remote vs local analysis
  • Added: Level-by-level comparison (Level 1, 2, and 3)
  • Added: Visual indicators for categories that need adding, updating, or removing
  • Added: Hash-based change detection in comparison view
  • Added: Direct sync from comparison page
  • Added: Product-category assignment checker and fixer
  • Added: Test single product tool for debugging category assignments
  • Added: Enhanced category assignment logging with debug mode
  • Added: Automatic validation of WooCommerce term existence during mapping
  • Added: Final verification logging after category assignment
  • Improved: Category synchronization workflow
  • Improved: Product sync with detailed category assignment tracking
  • Improved: Product save sequence - categories now assigned AFTER images
  • Fixed: Category assignment verification and auto-correction
  • Fixed: Critical bug - categories were being overwritten by image save
  • Fixed: Product save order to ensure categories are preserved

1.0.0 (2025-10-14)

  • Initial release
  • Three-level category synchronization
  • Product sync with MD5 hash detection
  • Custom database tables with composite unique keys
  • WooCommerce reconciliation
  • Manual and automatic sync
  • Comprehensive logging
  • Admin dashboard
  • Fixed: Category parent-child relationships with duplicate IDs across levels
  • Fixed: Slug conflicts for categories with same name at different levels

License

GPL v2 or later

Credits

Developed by H M Shahadul Islam for Codereyes