Colab PMLC (Post Migration Link Cleanup)

A robust WordPress plugin for comprehensive database search and replace operations, specifically designed for post-migration link cleanup and URL management. Features enterprise-grade batch processing, intelligent URL handling, and comprehensive database coverage.

This plugin should only be present on non-production sites

Features

1. CSV-Based Database Search & Replace

Core Functionality

• Bulk URL Migration: Upload CSV files with "Original URL" and "New URL" columns for database-wide replacements
• URL Boundary-Aware Replacement: Prevents protocol duplication (e.g., https://https://) through intelligent URL matching
• Smart URL Conversion: Automatically converts absolute URLs to relative paths with legacy URL structure transformation
• Comprehensive Database Coverage: Searches all database tables and columns with intelligent security exclusions

Advanced Processing

• Intelligent URL Variations: Generates optimized URL patterns (www/non-www, protocol/no-protocol, trailing slashes, file extensions)
• Serialized Data Support: Safely processes WordPress serialized data with incomplete object error handling
• Batch Processing: AJAX-driven processing with aggressive timeout protection and memory management
• Fallback Recovery: Robust error handling for Gravity Forms and other complex plugin data

User Experience

• Test Mode: Preview all changes without modifying database (dry-run capability)
• Real-time Progress: Live progress tracking with table-by-table status updates
• Batch Continuation: Automatic resumption of interrupted operations
• Detailed Reporting: Comprehensive CSV output with database locations and content URLs

Performance & Reliability

• Memory Optimization: Explicit garbage collection and variable cleanup
• Timeout Protection: Configurable execution limits with intelligent batch sizing
• Error Recovery: Comprehensive exception handling for serialized data issues
• Response Size Management: Optimized URL variations to prevent AJAX response limits

2. Single String Database Search & Replace ⏳ PLANNED

• Admin interface for one-off string replacements
• Same safety and reporting features as CSV mode

3. Content Audit & Reporting ⏳ PLANNED

• Database-wide string occurrence audit
• Context-rich reporting for manual content review

Requirements

• WordPress: 5.0 or higher
• PHP: 8.1 to 8.4
• Memory: 128MB minimum (256MB recommended for large sites)

Installation

Via Composer (Recommended)

1. Navigate to your WordPress plugins directory:

   cd /path/to/wordpress/

2. Clone or download the plugin:

   ddev composer require teamcolab/colab-pmlc

3. Activate the plugin through WordPress admin or WP-CLI:

   ddev wp plugin activate colab-pmlc

Configuration

After activation, visit Tools > Link Cleanup Dashboard in your WordPress admin to access the plugin.

Settings

Access plugin settings through Tools > Link Cleanup > Plugin Settings:

• Batch Size: Number of database rows to process per batch (5-50, default: 5)
• Timeout Limit: Maximum execution time per batch in seconds (5-30, default: 10)
• Memory Management: Automatic garbage collection and cleanup (enabled by default)

Usage

CSV-Based Database Search & Replace

1. Prepare Your CSV File

Create a properly formatted CSV with two required columns:

Column	Required	Description
Original URL	✅	The string/URL to search for
New URL	✅	The replacement string/URL

Requirements:

• ✅ Both columns must contain values (empty rows are skipped)
• ✅ Include headers in the first row
• ✅ Maximum file size: 5MB
• ✅ Supports any text strings, not just URLs

Example CSV:

Original URL,New URL
https://old-domain.com/page,https://new-domain.com/page
www.legacy-site.com/path,/new-path/
/old-corporate/,/en/
broken-link-text,updated-link-text

2. Access the Tool

1. Navigate to Tools > Link Cleanup Dashboard
2. Click "CSV Search & Replace" (hidden from Tools sidebar for security)

3. Configure Options

• Test Mode: ✅ Recommended first run - generates audit without database changes
• Convert to Relative URLs: ✅ Automatically converts absolute URLs to relative paths
• File Upload: Select your prepared CSV file

4. Monitor Processing

Real-time Features:

• ✅ Progress Bar: Visual progress indicator
• ✅ Current Table: Shows which database table is being processed
• ✅ Live Results Count: Updates as matches are found
• ✅ Memory Usage: Displays current memory consumption
• ✅ Batch Continuation: Automatically resumes if processing times out

Processing Details:

• Batch Size: 5-10 rows per batch (optimized for stability)
• Timeout Protection: 10-second execution limit per batch
• Memory Management: Automatic garbage collection
• Error Recovery: Graceful handling of serialized data issues

5. Download Results

Automatic CSV Download containing:

Column	Description
Table	Database table name
Column	Database column name
Row ID	Database row identifier
Original String	The search term that was found
Replacement String	What it was replaced with
Content URL	URL to view/edit the content (when available)
Database Location	Full database location reference

Database Coverage

✅ Tables Included in Search:

• WordPress core tables (wp_posts, wp_options, wp_postmeta, etc.)
• Plugin and theme configuration tables
• Custom post types and metadata
• Widget and menu content
• Theme customizer settings

🛡️ Tables Excluded for Safety:

• Authentication: users, usermeta (login credentials)
• Security Plugins: Wordfence, iThemes Security, Defender data
• Redirections: Redirection plugin data (prevents redirect breakage)
• System Tables: Action scheduler, cache, logs, sessions
• Backup Data: Backup plugin and migration tables

🔍 Content Types Processed:

• ✅ Regular Content: Standard text search and replace
• ✅ Serialized Data: WordPress serialized arrays and objects
• ✅ HTML Content: Preserves HTML structure and attributes
• ✅ JSON Data: Safely processes JSON without corruption
• ✅ URLs in Attributes: Handles href="" and src="" attributes

Advanced Features

URL Variation Generation:

• https://www.example.com/path → Creates 6-8 search patterns
• Handles www/non-www variations
• Protocol/no-protocol combinations
• Trailing slash variations
• File extension alternatives (.html, .php)

URL Processing:

• Maintains URL structure consistency
• Preserves query parameters and fragments
• Handles complex URL patterns safely

Error Handling:

• ✅ Incomplete object recovery (Gravity Forms, etc.)
• ✅ Memory limit protection
• ✅ Timeout prevention with batch continuation
• ✅ Comprehensive error logging

Development

This plugin follows WordPress coding standards and modern PHP practices:

Code Standards

• PSR-4 Autoloading: Modern namespace structure
• WordPress Coding Standards: Follows WPCS guidelines
• OOP Architecture: Object-oriented design patterns
• Composer Ready: Dependency management and autoloading

Project Structure

colab-pmlc/
├── assets/
│   ├── css/
│   │   └── admin.css
│   └── js/
│       └── admin.js
├── languages/
├── src/
│   ├── Admin/
│   │   ├── Admin_Manager.php
│   │   └── Menu_Manager.php
│   ├── Activator.php
│   ├── Deactivator.php
│   └── Plugin.php
├── composer.json
├── phpcs.xml
├── colab-pmlc.php
└── README.md

Development Commands

# Install development dependencies
composer install

# Run code style checks
composer run phpcs

# Fix code style issues
composer run phpcbf

# Run all tests
composer run test

Extending the Plugin

The plugin is designed to be extensible. You can add custom functionality by:

1. Creating new classes in the src/ directory
2. Following the existing namespace pattern
3. Hooking into WordPress actions and filters
4. Adding new admin pages or tools

Adding Custom Link Processors

// Example: Custom link processor
class Custom_Link_Processor {
    public function process_links($links) {
        // Your custom logic here
    }
}

Database Tables

The plugin creates the following database table:

wp_pmlc_link_cleanup_log

Stores information about processed links:

• id: Unique identifier
• post_id: WordPress post ID
• old_url: Original URL found
• new_url: Corrected URL
• status: Processing status (pending, fixed, error)
• created_at: When the issue was first detected
• updated_at: Last modification timestamp

Support

For support, feature requests, or bug reports, please contact the development team.

License

This plugin is licensed under the GPL v2 or later.

Changelog

1.0.0 - Feature 1 Complete

CSV-Based Database Search & Replace ✅

• Core Implementation: Complete database search and replace with CSV upload
• URL Boundary-Aware Replacement: Fixed protocol duplication issues (https://https://)
• Intelligent URL Variations: Optimized pattern generation (www/non-www, protocols, extensions)
• Batch Processing: AJAX-driven processing with timeout protection and automatic continuation
• Serialized Data Support: Safe handling of WordPress serialized content with error recovery
• Memory Management: Explicit garbage collection and variable cleanup for large datasets
• Test Mode: Comprehensive dry-run capability for safe testing
• Security: Intelligent table exclusion to protect authentication and system data
• URL Processing: Safe handling of complex URL structures and patterns
• Comprehensive Reporting: Detailed CSV output with database locations and content URLs
• Error Handling: Robust exception handling for Gravity Forms and complex plugin data
• Progress Tracking: Real-time processing updates with table-level status
• Project-Agnostic Code: Removed all project-specific logic for universal compatibility

Architecture & Standards

• PHP 8.1-8.4 Compatibility: Modern PHP feature utilization
• WordPress Coding Standards: Full WPCS compliance with phpcs.xml
• OOP Design: Clean class architecture with proper separation of concerns
• Composer Integration: PSR-4 autoloading and dependency management
• Namespace: ColabMultimedia\PostMigrationLinkCleanup
• Text Domain: colab-pmlc
• Admin Interface: Hidden submenus for security, breadcrumb navigation

Performance Optimizations

• Optimized Batch Size: 5-10 rows per batch for stability
• Response Size Management: Limited URL variations to prevent AJAX timeouts
• Timeout Protection: 10-second execution limits with intelligent continuation
• Memory Monitoring: Real-time memory usage tracking and cleanup

Upcoming Features

• Feature 2: Single String Database Search & Replace (planned)
• Feature 3: Content Audit & Reporting (planned)