README

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

Require the package via Composer:

composer require hashtagcms/migration-tool

Publish configuration and run migrations:

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

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.

hashtagcms/migration-tool

包简介

关键字：

README 文档