NXT Site Sync - WordPress Plugin

A minimal WordPress plugin designed to synchronize page structure and hierarchy from a live WordPress site to a staging environment via sitemap analysis or WordPress REST API.

Purpose

After redesigning a WordPress site on staging, this plugin helps selectively synchronize changes made on the live site without losing the staging work. It analyzes the live site's sitemap to understand page structure and applies only approved changes to staging.

Features

• Dual Data Sources: Choose between sitemap analysis or WordPress REST API for complete page data
• Smart Comparison: Compares page slugs and hierarchy between live and staging
• Strict Mode: Optional Page ID-based comparison for exact staging duplicates
• Polylang Support: Automatically detects language codes in URLs and matches pages by language
• Draft Protection: Excludes draft pages from comparisons to avoid false positives
• Enhanced Display: Shows language and status badges for better clarity with multilingual sites
• Direct Page Access: Quick links to view and edit pages from comparison results
• Safety First: Shows all differences before making any changes
• Selective Sync: Apply changes individually or in bulk
• No Data Loss: Requires explicit user approval for all operations

Installation

1. Upload the nxt-site-sync folder to /wp-content/plugins/ directory on your staging site
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Go to Tools → Site Sync in the WordPress admin

Usage

Step 1: Configure Settings

1. Navigate to Tools → Site Sync
2. Choose your data source:
   • Sitemap: Uses sitemap_index.xml (traditional method)
   • REST API: Direct WordPress REST API access (recommended for complete data)
3. Enter the appropriate URL:
   • Sitemap URL: https://yourlivesite.com/sitemap_index.xml
   • REST API URL: https://yourlivesite.com/wp-json/wp/v2/pages
4. Choose comparison mode:
   • Standard (Slug + Language): Matches pages by slug and language (default)
   • Strict (Page IDs): Matches pages by WordPress Page ID (for exact duplicates)
5. Click Save Settings

Step 2: Fetch & Analyze

1. Click Fetch & Analyze button
2. The plugin will:
   • Fetch data from your chosen source (sitemap or REST API)
   • Extract all page URLs and metadata
   • Parse URL structure to determine hierarchy
   • Compare with staging pages using selected comparison mode
   • Generate a detailed report

Step 3: Review Differences

The plugin shows four types of differences:

Slug Differences

• Pages where the slug differs between live and staging
• Each has a "Sync Slug" button for individual updates

Hierarchy Differences

• Pages where the parent relationship differs
• Each has a "Fix Hierarchy" button for individual updates

Pages Only on Live

• Pages that exist on live but not on staging
• Each has a "Create Page" button (creates as draft)

Pages Only on Staging

• Pages that exist on staging but not on live
• Each has a "Move to Trash" button

Step 4: Apply Changes

Individual Changes:

• Click the action button next to any difference
• Confirm the action in the dialog
• The row will be marked as synced

Bulk Changes:

• Click Apply All Approved Changes at the bottom
• This applies all slug and hierarchy changes at once
• Page creation and deletion must be done individually for safety

How It Works

Hierarchy Detection

The plugin parses URL paths to determine parent-child relationships:

• /about/ → Top-level page
• /about/team/ → "team" is child of "about"
• /about/team/leadership/ → "leadership" is child of "team"

Polylang Integration

When Polylang is active, the plugin:

• Detects Language Codes: Automatically removes language prefixes from URLs (e.g., /en/services/ → /services/)
• Language-Aware Matching: Matches pages by both slug AND language to handle duplicate slugs across languages
• Displays Language Info: Shows language badges (EN, DE, FR, etc.) in all comparison tables
• Respects Language Context: Won't incorrectly match pages with the same slug in different languages

Example: /en/services/ and /de/services/ are treated as two separate pages.

Safety Measures

• No automatic changes without user approval
• Confirmation dialogs for create/delete operations
• Draft pages excluded from comparisons (only publish/private)
• Changes applied via WordPress functions (not direct DB queries)
• All operations logged
• Pages created as drafts (never published automatically)
• Deleted pages moved to trash (recoverable)

Technical Details

• Minimum WordPress Version: 5.8
• Minimum PHP Version: 7.4
• Dependencies: None (pure WordPress, no external libraries)
• Polylang Compatibility: Automatically detects and integrates with Polylang if installed
• Language Codes Supported: en, de, fr, es, it, nl, pt, ru, zh, ja, ko, ar, pl, tr, cs, da, fi, no, sv, hu, ro, bg, hr, sk, sl, sr, uk, he, th, vi, id, ms
• Compatibility: Works with any WordPress theme
• Performance: Uses transients to cache comparison results (1 hour)

File Structure

nxt-site-sync/
├── nxt-site-sync.php              # Main plugin file
├── includes/
│   ├── class-sitemap-parser.php    # Fetches and parses sitemap
│   ├── class-rest-api-parser.php   # Fetches data via WordPress REST API
│   ├── class-hierarchy-builder.php # Builds page hierarchy from URLs
│   ├── class-page-comparator.php   # Compares live vs staging
│   └── class-sync-manager.php      # Applies approved changes
├── admin/
│   ├── admin-page.php              # Admin interface
│   └── ajax-handlers.php           # AJAX endpoints
└── assets/
    ├── css/
    │   ├── admin-styles.scss       # Source styles
    │   └── admin-styles.css        # Compiled styles
    └── js/
        └── admin-scripts.js        # Vanilla JS (no dependencies)

Security

• Capability checks: manage_options for settings, edit_pages for modifications
• Nonce verification on all AJAX requests
• Input sanitization and validation
• Output escaping
• WordPress Coding Standards compliant

Limitations

• Requires either a sitemap or accessible WordPress REST API on live site
• Only syncs pages (not posts, custom post types, or media)
• Only compares published and private pages (drafts, pending, and future posts are excluded)
• Hierarchy detected from URL structure only
• Does not sync page content, meta fields, or featured images
• Does not handle redirects or permalink settings
• Language detection assumes standard URL structure (language code as first path segment)

Support

For issues, questions, or feature requests, contact NexTab.

License

Copyright © NexTab. All rights reserved.

Changelog

1.0.9

• CRITICAL FIX: Fixed staging page retrieval to include ALL post statuses (not just publish/private)
• Added comprehensive post status analysis to identify missing pages
• Fixed issue where only 183 staging pages were found instead of 926 total pages
• Enhanced debugging to show all available post statuses and their counts
• Updated both local staging queries and REST API queries to include draft, pending, future statuses

1.0.8

• CRITICAL FIX: Implemented proper pagination to fetch ALL pages from REST API (not just first 100)
• Added comprehensive logging for each pagination request to track progress
• Fixed issue where only 100 pages were retrieved from sites with 900+ pages
• Enhanced error handling with detailed HTTP status and JSON parsing logs
• Improved debugging output to identify exactly how many pages are fetched per request

1.0.7

• Added extensive debugging and logging for page matching issues
• Improved REST API pagination handling for large sites
• Enhanced error reporting with detailed debug information
• Fixed potential issues with page count mismatches between live and staging

1.0.6

• Fixed hierarchy recognition for REST API data (bypassed incorrect Hierarchy Builder usage)
• Improved handling of large sites (900+ pages) with proper per_page=-1 implementation
• Added comprehensive logging for debugging large site synchronization
• Increased timeout for REST API requests to handle large datasets

1.0.5

• Fixed "Cannot increment array" error in REST API parser
• Added robust error handling for all API response scenarios
• Improved loop safety with proper array initialization and type checking
• Enhanced error recovery to prevent infinite loops

1.0.4

• Added comprehensive critical error handling for all AJAX operations
• All PHP functions now wrapped in try-catch blocks with detailed logging
• Improved JSON response handling with fallback error messages
• Enhanced debugging capabilities with detailed error information in server logs

1.0.3

• Fixed WordPress REST API parameter issue with status filtering
• Now fetches published and private pages separately to avoid API errors
• Added duplicate prevention for pages that exist in both states
• Improved error handling for REST API responses

1.0.2

• Added WordPress REST API as alternative data source
• Enhanced Page ID extraction and matching capabilities
• Improved data accuracy with direct API access
• Dynamic UI switching between Sitemap and REST API modes

1.0.1

• Added Polylang support with automatic language detection
• Language codes automatically removed from URLs during parsing
• Language-aware page matching prevents false duplicates
• Draft pages excluded from comparisons
• Enhanced UI with language and status badges
• Improved display for multilingual sites
• Introduced Strict Mode for Page ID-based comparison
• Added direct page access links (view staging, view live, edit staging)

1.0.0

• Initial release
• Sitemap parsing and analysis
• Slug synchronization
• Hierarchy synchronization
• Individual and bulk operations
• Safety confirmations and logging