HashtagCMS Migration Tool

A production-grade, asynchronous database, media, and template migration tool for HashtagCMS. Move a complete CMS site — including all data layers, translations, media files, and relational graph — from a source database to a target installation with a beautiful guided wizard UI.

✨ Feature Highlights

| Feature | Status | |:---|:---| | 7-Step ETL Pipeline (Context → Structural → Glue → Content → Media → Validation) | ✅ | | Legacy terminology support (Auto-detect tenants vs platforms) | ✅ | | Smart Template Migration (with automated namespace refactoring) | ✅ | | Pre-migration Package Audit (Detect missing composer dependencies) | ✅ | | Artisan CLI Interface (cms:migrate-site & cms:migrate-templates) | ✅ | | ID Mapping Engine (old_id → new_id across connections) | ✅ | | Asynchronous Background Job Processing & Progress Monitoring | ✅ | | Auto-run one queue job on dispatch (queue:work --once) | ✅ | | Scale-ready Performance (Chunked data processing for large sites) | ✅ | | Conflict Resolution: Terminate / Overwrite / Rename | ✅ | | Media & Asset File Synchronization | ✅ | | Automated Post-Migration Integrity Validation | ✅ | | Staff-only access guard at controller level (user_type = Staff) | ✅ | | Auto-create missing target tables from source schema (with permission checks) | ✅ |

📋 Requirements

• PHP ^8.2
• Laravel 10.x, 11.x, or 12.x
• HashtagCMS core package hashtagcms/hashtagcms
• A queue driver configured (e.g., database, redis, sqs)

🚀 Installation

1. Require the package via Composer:

composer require hashtagcms/migration-tool

2. Publish configuration and run migrations:

php artisan vendor:publish --tag="migration-tool-config"
php artisan migrate

3. Run your queue worker (recommended for sustained migrations):

php artisan queue:work

If `auto_queue_work_once` is enabled in config (default), each migration dispatch can auto-start a one-shot worker process.

💻 Usage

📊 Migration Wizard (UI)

Open the Migration Wizard in your browser for a guided experience: https://your-app.com/cms-migration

• Discovery Phase: Automatically identifies site statistics and warns about missing composer packages found in the source project.
• Template Sync: Independently migrate your theme and module blade files with real-time namespace refactoring (MarghoobSuleman\HashtagCms → HashtagCms).

⌨️ Artisan Commands (CLI)

1. Full Data Migration

php artisan cms:migrate-site {site_id} \
    --database="source_db" \
    --username="root" \
    --password="password" \
    --media --source-root="/var/www/old-site"

2. Standalone Template Migration

php artisan cms:migrate-templates {site_id} "/absolute/path/to/source"

🧠 Smart Migration Features

🔄 Legacy Compatibility

The tool automatically detects if the source database uses the older tenants and tenant_id terminology. It transparently maps these to the modern platforms and platform_id structure in HashtagCMS V2+.

📝 Code Refactoring

During template migration, the tool processes all .php and .blade.php files. It automatically bridges the gap between legacy and modern namespaces:

• MarghoobSuleman\HashtagCms $\rightarrow$ HashtagCms

📦 Dependency Audit

Before starting, the tool reads the composer.json of your legacy installation and compares it to your new one. It will provide a ready-to-use composer require command for any missing third-party packages.

📖 Documentation

| # | Document | Description | |:--|:---------|:------------| | 01 | Architecture Overview | ETL design, layers, and class structure | | 02 | Installation & Configuration | Full setup guide | | 03 | The ETL Pipeline | Details on all 7 sync steps | | 04 | Migration Wizard UI | How the frontend wizard works | | 05 | API Reference | All backend endpoints | | 06 | Conflict Resolution | Domain & data conflict strategies | | 07 | Media Migration | File sync and path handling | | 08 | Queue & Async Jobs | Background job and progress tracking | | 09 | ID Mapping Engine | How foreign keys are re-mapped | | 10 | Security | CSRF, session, and connection safety | | 11 | Template Migration | Standalone file/namespace syncing | | 12 | Legacy & Dependency Support | Terminology and package audit | | 13 | Regression Smoke Checks | Validate recent migration bug fixes |

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📄 License

MIT © Marghoob Suleman