CPT Export & Import (CEI)

Version: 2.0.0 | Tested up to: WP 6.7, PHP 8.2 | Licence: GPLv2 Security: APPROVED | QA: APPROVED | Status: PRODUCTION READY

What This Does

CPT Export & Import (CEI) is a production-grade, developer-friendly WordPress plugin designed to seamlessly export and import public Custom Post Types (CPTs), taxonomy terms, metadata, media attachments, and custom database slices.

Built around a highly extensible Provider-Based OOP Architecture, CEI enables developers to easily register custom data adapters to package, transform, and restore complex data alongside standard WordPress post fields. It features a premium, interactive Bento Grid Dashboard complete with tab controls, drag-and-drop file uploading, local browser-side package auto-detection, and a robust background polling mechanism that interfaces with a stateless, chunked WP-Cron batch-worker engine to handle millions of records safely without timeouts.

Key Features

• 🗂️ Bento Grid Dashboard: High-fidelity, modern administrative interface utilizing interactive tab controls and real-time polling widgets.
• 🖲️ Interactive Tab Controls: Seamless client-side transition between Export, Import, and Quick Settings panels.
• 📥 Drag-and-Drop Auto-Detection: A highly interactive upload zone that parses uploaded JSON files client-side using the FileReader API, instantly detecting and displaying the package type (e.g., Post Migration Package, Taxonomy Terms Package, or Generic JSON File) and record counts before import.
• ⚙️ Chunked Background Processing: WP-Cron worker that divides large datasets into small batches (default 50), preventing PHP timeouts and memory exhaustion.
• 🔄 Programmatic Control: Dual integration pathways via a fully authenticated REST API controller and an advanced WP-CLI command suite.
• 🧩 Extensible Registry: Hook into the exporter/importer lifecycle to transform data on the fly (e.g., encrypt fields) or add custom tables via custom Providers.
• 🛡️ Harden Security: Strict capability checks (manage_options), multi-layered nonces (AJAX, forms, download links), input sanitization, file-type validation, .htaccess upload directory protection, and prepared SQL statement verification.

Requirements

• WordPress: 5.8 or higher (Fully tested with WP 6.7)
• PHP: 7.4 or higher (Fully tested with PHP 8.2)
• Dependencies: None. Works out of the box using WordPress native APIs.

Installation

1. Upload: Upload the custom-export-import directory to your WordPress site's /wp-content/plugins/ folder.
2. Activation: Navigate to Plugins in the WordPress admin dashboard and click Activate next to CPT Export & Import.
3. Configure: Go to Settings → CPT Export & Import to select which post types are enabled, customize the default import strategy, and set your background batch sizes.
4. Export: Visit Tools → Export CPT Data to initiate an export.
5. Import: Visit Tools → Import CPT Data to upload and restore JSON packages.

Bento Grid Dashboard Interactivity

CEI introduces a highly refined bento-style user experience loaded with modern client-side features:

1. Interactive Tab Controls

The admin interface is unified under a single, fluid bento dashboard page. Clicking the Export Data or Import Data triggers instantly switches panels client-side by toggling classes (.active / .cei-panel-card), allowing administrators to manage both pipelines, adjust settings, and view logs concurrently without full page refreshes.

2. Drag-and-Drop Upload & Auto-Detection

The import zone features an advanced drag-and-drop container (#cei-drag-drop-zone). When a file is dropped or selected:

1. The client-side controller initializes a FileReader instance to read the JSON file locally.
2. It attempts to parse the payload and runs structure auto-detection:
   • Post Migration Package: Detected if the JSON contains a posts array. It scans the first ten posts, extracts the post types, counts the records, and renders a banner displaying: "Contains X records of type(s): post, page, custom_cpt."
   • Taxonomy Terms Package: Detected if the JSON contains a terms array. It extracts the taxonomy name and term counts, displaying: "Contains X terms of taxonomy: category."
   • Generic JSON File: Displayed if the JSON schema is unrecognized.
3. A sleek Detection Banner (#cei-detection-banner) immediately renders in the dashboard, presenting these details along with file size metrics (in KB) before the administrator clicks the import button.

3. Clean Notice-Free User Experience

To deliver a clean, premium visual design inside the CPT Migration Hub, the workspace is entirely notice-free. Standard WordPress admin notices, PHP compatibility alerts, and Custom Post Type (CPT) warning banners are systematically suppressed on the dashboard page. This ensures a focused, clutter-free operations environment.

4. Background Completion Redirect & Auto-Redirect

During long-running background tasks, progress is tracked using real-time secure AJAX status polling. Upon job completion, the JavaScript controller automatically appends the new=1 query argument to the URL and redirects the browser. This reload triggers an options state purger that deletes the completed job's options keys from the database, restoring the dashboard to the clean settings and selection forms, and removing all modal notice screens automatically.

5. Secure E2E Sidebar Downloads

When an export job finishes, administrators do not have to deal with intrusive download notifications or persistent modal popups. Completed migration archives are securely downloaded directly from the persistent "Activity Tracker" sidebar timeline. Successful exports generate dynamic download links using wp_nonce_url() paired with dynamic UUID v4 job logs, allowing instant and secure downloads at any time.

6. Real-Time Cron Management & WP-CLI Clipboard Copying

Administrators have granular, real-time control over background operations directly from the Maintenance & System Storage bento panel:

• Real-Time Task Monitoring: Actively tracks registered CEI WP-Cron routines:
  • cei_prune_logs: The daily recurring log management event.
  • cei_process_batch: The stateless, single-event background migration chain.
• Immediate Cancellation: Features a safe administrative termination pathway. Clicking Cancel Batch Execution or Unschedule Job triggers a secure AJAX endpoint (cei_cancel_cron) to instantly purge the scheduled event, fail-safe the active background job, and mark the operation as failed to avoid orphaned tasks or infinite loops.
• Copy-to-Clipboard WP-CLI Blocks: Styled command containers allow developers and operators to click and instantly copy equivalent WP-CLI override commands (e.g., wp cron event delete cei_process_batch) to their clipboard for swift terminal executions.

7. Force Stop & Cancel Active Migration

When a background post or taxonomy migration is active, a dedicated urgent notice card displays at the top of the Maintenance & System Storage dashboard. Click the "Force Stop & Cancel Migration" button to trigger a secure AJAX handshake that immediately:

• Aborts any active background post or taxonomy migration job.
• Marks the active job status as failed in the database with a user-facing explanation.
• Cleanly unschedules any pending batch cei_process_batch WP-Cron events.
• Safely deletes all temporary chunk cache JSON slices from the /wp-content/uploads/cei-imports/chunks/ directory.

WP-CLI Command Suite

For automated backups, command-line operations, and continuous integration pipelines, CEI bundles a robust WP-CLI command suite under the wp cei namespace:

1. Data Export

Export posts, pages, or custom post types using registered providers to a localized JSON file.

# Export all default enabled post types to the WP uploads directory
wp cei export

# Export specific post types (e.g., portfolio and services)
wp cei export --post_types=portfolio,services

# Export using only specific data providers
wp cei export --providers=default

# Export to a custom server directory
wp cei export --dir=/var/www/html/backups

2. Data Import

Import any CEI-compatible JSON package directly from the command line, bypassing PHP upload limits.

# Basic import with default strategy (skip)
wp cei import /path/to/export.json

# Overwrite existing records using the "update" strategy
wp cei import /path/to/export.json --strategy=update

# Preview the import results without writing to the database (Dry-Run)
wp cei import /path/to/export.json --dry-run

# Restrict the import to specific post types
wp cei import /path/to/export.json --post_types=post,page

3. Log Inspection

Query recent import/export job records saved in the audit log.

# Print a beautiful table of the 20 most recent logs
wp cei log

# Limit the log output and print as raw JSON for external ingestion
wp cei log --limit=5 --format=json

4. Registry Exploration

List all data providers registered within the active WordPress environment.

wp cei list-providers --format=table

REST API Integration

All endpoints require the manage_options capability. Cookie authentication is used for same-site requests, while Application Passwords, Basic Auth, or OAuth can be used for headless integrations.

Base URL: /wp-json/cei/v1

REST API Examples

1. Dispatch Asynchronous Export Job

POST /wp-json/cei/v1/export HTTP/1.1
Host: yoursite.local
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "post_types": ["post", "page"],
  "providers": ["default"]
}

Response (202 Accepted):

{
  "success": true,
  "message": "Export job dispatched successfully.",
  "job_id": "8e36780c-ea1f-4efc-8062-817ab3de520b",
  "status": "queued"
}

2. Programmatic File Import

POST /wp-json/cei/v1/import HTTP/1.1
Host: yoursite.local
Authorization: Bearer <your-token>
Content-Type: multipart/form-data; boundary=boundary123

--boundary123
Content-Disposition: form-data; name="file"; filename="export.json"
Content-Type: application/json

...[JSON Content]...
--boundary123
Content-Disposition: form-data; name="strategy"

update
--boundary123
Content-Disposition: form-data; name="dry_run"

false
--boundary123--

Response (202 Accepted):

{
  "success": true,
  "message": "Import job dispatched successfully.",
  "job_id": "7df41ac3-94c6-4d7a-8fbd-b118fb37a91a",
  "status": "queued"
}

Action Hooks & Filter Reference

Action Hooks

• cei_register_providers ($registry): Fires on plugin boot. Developers use $registry->register( new Custom_Provider() ) to add handlers.
• cei_settings_page: Fires inside settings page form, allowing developers to output custom settings fields.
• cei_admin_page_export: Extends the export form visually.
• cei_admin_page_import: Extends the import form visually.
• cei_before_export ($args): Fires immediately before the export pipeline query starts.
• cei_post_exported ($post_id, $entry): Fires after a post is processed.
• cei_after_export ($data, $post_count): Fires when an export job finishes.
• cei_before_import ($data, $args): Fires before an import job runs.
• cei_post_imported ($post_id, $entry, $strategy): Fires after a post has been created/updated during import.
• cei_import_custom_data ($custom, $post_id): Fires when third-party provider data is available during import.
• cei_import_complete ($results, $data): Fires when an import job is finished.

Filter Hooks

• cei_enabled_post_types ($post_types): Restricts or expands available post types in settings and forms.
• cei_export_post_types ($post_types, $args): Dynamically overrides which post types to export.
• cei_export_query_args ($query_args): Modifies the arguments passed to get_posts() during export query.
• cei_export_post_data ($entry, $post_id): Filters the compiled JSON record array for a single post.
• cei_export_post_{$post_type}_data ($entry, $post_id): Specific filter for a single post type.
• cei_export_transformers ($transformers): Filters registered transformers running on export.
• cei_export_meta_{$key} ($value, $post_id): Filters a meta key's exported value.
• cei_export_term_{$taxonomy} ($entry, $post_id): Filters term data for a specific taxonomy.
• cei_pre_import_validate_file ($valid, $data): Filters import file validity. Return false to abort.
• cei_pre_import_post ($entry, $original): Filters a post entry before inserting/updating. Return null to skip.
• cei_import_strategy ($strategy, $entry): Dynamically overrides strategy per post entry.
• cei_import_meta_{$key} ($value, $post_id): Filters a meta key's value before updating in the database.
• cei_import_attachment ($result, $file_url, $post_id): Return an attachment ID directly to bypass downloading.

Troubleshooting

Background Job Appears Stuck

If an export or import progress bar stays at 0% or hangs mid-way, check the following:

1. WP-Cron Triggers: WordPress background tasks require traffic to trigger. In low-traffic local environments, load a few front-end pages to fire scheduled cron events.
2. Cron Disabled?: Check if DISABLE_WP_CRON is set to true in your wp-config.php. If so, set up a server-level cron job or disable this constant.
3. Queue Reset: To clear a stuck queue, navigate to Settings → CPT Export & Import, reduce the Batch Size, and re-submit.

Media Downloads Failing

If featured images or attachments fail to load on import:

• Check that the source website is still active and the image URLs in the JSON package are publicly accessible.
• Ensure your server has allow_url_fopen enabled or is capable of making outbound HTTP requests (wp_remote_get).

Licence

GPLv2 or later. Free to use, adapt, and distribute under open-source compliance guidelines.