PHPackages csabourin/spaghetti-migrator - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. csabourin/spaghetti-migrator ActiveCraft-plugin[Database & ORM](/categories/database) csabourin/spaghetti-migrator ============================ Spaghetti Migrator - Untangles your nested subfolders and migrates assets between cloud services. A production-grade Craft CMS 4/5 plugin with checkpoint/resume, rollback capabilities, and zero-downtime support. v5.9.1(1mo ago)0165MITPHPPHP ^8.0 || ^8.1 || ^8.2 || ^8.3CI failing Since Nov 7Pushed 1mo agoCompare [ Source](https://github.com/csabourin/do-migration)[ Packagist](https://packagist.org/packages/csabourin/spaghetti-migrator)[ Docs](https://github.com/csabourin/do-migration)[ RSS](/packages/csabourin-spaghetti-migrator/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (12)Versions (301)Used By (0) 🍝 Spaghetti Migrator v5.0 for Craft CMS ======================================= [](#-spaghetti-migrator-v50-for-craft-cms) [![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![Craft CMS](https://camo.githubusercontent.com/fb1aed01b52e2b251e6e6f8f5bcd2c0f4cad5d626df354e3e774d0e2f2f297b9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4372616674253230434d532d34253230253743253230352d6f72616e6765)](https://craftcms.com/)[![PHP](https://camo.githubusercontent.com/2f6f9af2e917cbf5786673e8e4ed8d0d9b29be6131327a992063e69136a93411/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e302532422d626c7565)](https://www.php.net/)[![Version](https://camo.githubusercontent.com/3b1b1270b1c31f0761039bb1583fdb7b6252aea6e092596bfc29870f0b4f6999/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f56657273696f6e2d352e302d677265656e)](https://github.com/csabourin/do-migration) **Untangle your asset spaghetti like a pro chef! Now with multi-cloud support!** Spaghetti Migrator is a production-grade Craft CMS 4/5 plugin that untangles nested subfolders and migrates assets between cloud storage providers. Whether you're dealing with a tangled mess of nested directories or moving between AWS S3, Google Cloud Storage, Azure Blob, DigitalOcean Spaces, or local filesystems, this tool helps you straighten it all out with checkpoint/resume, rollback capabilities, and zero-downtime support. πŸ†• What's New in v5.0 -------------------- [](#-whats-new-in-v50) - 🌐 **Unified Multi-Provider Engine**: One workflow for AWS S3, Google Cloud Storage, Azure Blob, DigitalOcean Spaces, or local filesystemsβ€”mix and match any of the 5 supported providers. - 🚦 **5.0 Orchestrator**: Hardened `MigrationOrchestrator` with improved checkpointing, resumable phases, and clearer safety rails for Craft 4/5. - πŸ–₯️ **Dashboard Polish**: Faster Control Panel dashboard with richer status endpoints, consolidated logs, and live migration monitoring. - πŸ” **Smarter URL Replacement**: Regex and multi-mapping strategies tuned for cross-domain consolidations and template cleanup. - 🧰 **Operational Toolkit**: Built-in diagnostics (`migration-check`, `migration-diag`, transform cleanup) so no extra helper scripts are needed in the repo root. ✨ Highlights ------------ [](#-highlights) - **Untangle the Mess**: Turn your nested folder spaghetti into a well-organized plate - **Production-Ready**: Battle-tested migration toolkit with enterprise-grade reliability - **Checkpoint/Resume System**: Survive interruptions and resume from exactly where you left off - **Complete Rollback**: Full rollback capabilities - because sometimes you need to put the spaghetti back - **Zero Dependencies**: Works with just Craft CMS - no additional packages required - **Auto-Bootstrap**: PSR-4 autoloaded - no manual configuration in `config/app.php` - **Memory Efficient**: Handles 100,000+ assets with intelligent batch processing - **Comprehensive Dashboard**: Web-based Control Panel for orchestration and monitoring 🎯 Key Features -------------- [](#-key-features) ### Migration Capabilities [](#migration-capabilities) - **20 Specialized Controllers** for different migration phases - **Batch Processing** with configurable batch sizes for memory efficiency - **Dry Run Mode** to test migrations without making changes - **Progress Tracking** with real-time ETA and throughput metrics - **Error Recovery** with automatic retry logic and health checks - **Idempotent Operations** - safe to run multiple times ### Control Panel Dashboard [](#control-panel-dashboard) - Web-based interface for migration orchestration - Real-time status monitoring - Command execution from the browser - Checkpoint inspection tools - Live log streaming - Connection testing ### Developer Experience [](#developer-experience) - Centralized configuration via `MigrationConfig` helper - 40+ type-safe configuration methods - Comprehensive inline documentation - Extensive architecture documentation - Custom Twig filters included πŸ“‹ Requirements -------------- [](#-requirements) - **PHP**: 8.0 or higher - **Craft CMS**: 4.0+ or 5.0+ - **Storage Provider**: At least one cloud storage account or local filesystem - AWS S3, Google Cloud Storage, Azure Blob, DigitalOcean Spaces, or Local filesystem 🌍 Supported Storage Providers ----------------------------- [](#-supported-storage-providers) ProviderTypeCostSpeedNotes**AWS S3**Cloud$$FastIndustry standard**Google Cloud Storage**Cloud$$FastGCP integration**Azure Blob Storage**Cloud$$FastAzure integration**DigitalOcean Spaces**Cloud$FastSimple pricing**Local Filesystem**LocalFreeVery FastReorganization/backupπŸš€ Installation -------------- [](#-installation) ### 1. Install via Composer [](#1-install-via-composer) ``` composer require csabourin/spaghetti-migrator ``` The plugin will auto-install and automatically create `config/migration-config.php` if it doesn't exist. ### 2. Configure Environment Variables [](#2-configure-environment-variables) Add these to your `.env` file: ``` # Migration Environment MIGRATION_ENV=dev # DigitalOcean Spaces Credentials DO_S3_ACCESS_KEY=your_spaces_access_key DO_S3_SECRET_KEY=your_spaces_secret_key DO_S3_BUCKET=your-bucket-name DO_S3_BASE_URL=https://your-bucket.tor1.digitaloceanspaces.com DO_S3_BASE_ENDPOINT=https://tor1.digitaloceanspaces.com ``` See [.env.example](.env.example) for all available options. ### 3. Update Migration Config [](#3-update-migration-config) Edit `config/migration-config.php`: ``` $awsSource = [ 'bucket' => 'your-aws-bucket', // ← Update this 'region' => 'us-east-1', // ← Update this ]; ``` ### 4. Verify Installation [](#4-verify-installation) ``` ./craft spaghetti-migrator/migration-check/check ``` πŸ“– Usage ------- [](#-usage) ### Console Commands [](#console-commands) #### Pre-Flight Check [](#pre-flight-check) ``` ./craft spaghetti-migrator/migration-check/check ``` #### Migrate Assets (Dry Run) [](#migrate-assets-dry-run) ``` ./craft spaghetti-migrator/image-migration/migrate --dryRun=1 ``` #### Migrate Assets (Production) [](#migrate-assets-production) ``` ./craft spaghetti-migrator/image-migration/migrate ``` #### Replace URLs in Database [](#replace-urls-in-database) ``` ./craft spaghetti-migrator/url-replacement/replace-s3-urls ``` #### Switch Filesystems [](#switch-filesystems) ``` ./craft spaghetti-migrator/filesystem-switch/to-do ``` #### Post-Migration Diagnostics [](#post-migration-diagnostics) ``` ./craft spaghetti-migrator/migration-diag/diagnose ``` ### Web Dashboard [](#web-dashboard) Access the migration dashboard in your Control Panel: ``` Control Panel β†’ Migration β†’ Dashboard ``` The dashboard provides: - Step-by-step migration guidance - Real-time progress monitoring - Command execution interface - Configuration validation - Checkpoint management πŸ—ΊοΈ Migration Workflow --------------------- [](#️-migration-workflow) The complete migration process follows these phases: 1. **Prerequisites** - Install required plugins, configure settings, sync source files, and create backups 2. **Setup & Configuration** - Create filesystems, configure volumes, and prepare quarantine/transform infrastructure 3. **Pre-Flight Checks** - Validate configuration, connectivity, and migration readiness 4. **Filesystem Switch** - Point Craft volumes at the target filesystem once the source sync is current 5. **File Organization & Cleanup** - Reconcile asset records, fix paths, quarantine orphans, and organize files already present on the target provider 6. **Volume Consolidation** - Finalize physical file locations before rewriting URLs 7. **URL Replacement** - Update database content to reference final asset URLs 8. **Template Updates** - Replace hardcoded source URLs in Twig templates 9. **Post-Migration Validation** - Run diagnostics and complete required Craft maintenance commands 10. **Image Transforms** - Discover, generate, and verify transform coverage 11. **Audit & Diagnostics** - Scan for missing files, plugin config issues, and filesystem mismatches Each phase is modular and can be executed independently or in sequence. ### OptimisedImages transform cleanup [](#optimisedimages-transform-cleanup) Before running the file migration or cleanup commands, purge stale transform files that live inside underscore-prefixed folders (for example `_1200x800/hero.jpg`) within the **Optimised Images** volume (ID 4). This prevents copying millions of auto-generated transforms to the new filesystem and keeps the migration delta small. ``` # Preview everything that would be removed ./craft spaghetti-migrator/transform-cleanup/clean --dryRun=1 # Execute the cleanup ./craft spaghetti-migrator/transform-cleanup/clean --dryRun=0 ``` Each run saves a JSON report under `storage/runtime/transform-cleanup/` so you can audit which files were targeted. πŸ“‚ Module Structure ------------------ [](#-module-structure) ``` modules/ β”œβ”€β”€ module.php # Module entry point β”œβ”€β”€ controllers/ # Web controllers β”‚ β”œβ”€β”€ DefaultController.php β”‚ └── MigrationController.php # Dashboard controller β”œβ”€β”€ console/controllers/ # 20 console controllers β”‚ β”œβ”€β”€ MigrationCheckController.php β”‚ β”œβ”€β”€ ImageMigrationController.php β”‚ β”œβ”€β”€ FilesystemSwitchController.php β”‚ └── ... (13 more) β”œβ”€β”€ helpers/ β”‚ └── MigrationConfig.php # Centralized configuration └── templates/spaghetti-migrator/ └── dashboard.twig # Control Panel interface ``` πŸ“š Documentation --------------- [](#-documentation) ### v5.0 Guides [](#v50-guides) - **[MIGRATION\_GUIDE.md](MIGRATION_GUIDE.md)** - **START HERE** - Complete migration guide for all providers - **[docs/PROVIDER\_EXAMPLES.md](docs/PROVIDER_EXAMPLES.md)** - Configuration examples for each provider - **[MULTI\_PROVIDER\_ARCHITECTURE.md](MULTI_PROVIDER_ARCHITECTURE.md)** - v5.0 multi-provider architecture and design - **[config/migration-config.php](config/migration-config.php)** - Current configuration template ### Core Documentation [](#core-documentation) - **[OPERATIONS.md](OPERATIONS.md)** - Day-to-day usage, dashboard execution, consolidation, and troubleshooting - **[PRODUCTION\_OPERATIONS.md](PRODUCTION_OPERATIONS.md)** - Production deployment, monitoring, and troubleshooting - **[ARCHITECTURE.md](ARCHITECTURE.md)** - System design and technical details - **[CLAUDE.md](CLAUDE.md)** - AI assistant guide with comprehensive codebase reference - **[AGENTS.md](AGENTS.md)** - AI agent rules and constraints - **[CHANGELOG.md](CHANGELOG.md)** - Version history - **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines - **[SECURITY.md](SECURITY.md)** - Security policy and best practices πŸ”§ Configuration --------------- [](#-configuration) The module uses a centralized configuration system with three layers: 1. **Environment Variables** (`.env`) - Credentials and secrets 2. **Configuration File** (`config/migration-config.php`) - Migration settings 3. **Helper Class** (`MigrationConfig`) - Type-safe access to config values ### Key Configuration Options [](#key-configuration-options) ``` return [ 'aws' => [ 'bucket' => 'your-source-bucket', 'region' => 'us-east-1', ], 'do' => [ 'bucket' => App::env('DO_S3_BUCKET'), 'region' => 'tor1', 'accessKey' => App::env('DO_S3_ACCESS_KEY'), 'secretKey' => App::env('DO_S3_SECRET_KEY'), ], 'migration' => [ 'batchSize' => 100, 'checkpointFrequency' => 50, 'maxRetries' => 3, ], ]; ``` πŸ›‘οΈ Safety Features ------------------ [](#️-safety-features) - **Dry Run Mode**: Test all operations before execution - **Checkpoint System**: Automatic progress saving every N items - **Rollback Capability**: Complete undo with change logs - **Health Checks**: Continuous validation during migration - **Error Recovery**: Automatic retry with exponential backoff - **Audit Logging**: Comprehensive logs of all operations 🀝 Contributing -------------- [](#-contributing) Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details. ### Development Setup [](#development-setup) 1. Fork and clone the repository 2. Install dependencies: `composer install` 3. Set up a test Craft CMS installation 4. Configure test AWS S3 and DigitalOcean Spaces accounts 5. Run pre-flight checks: `./craft spaghetti-migrator/migration-check/check` πŸ“„ License --------- [](#-license) This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. πŸ™ Acknowledgments ----------------- [](#-acknowledgments) - Built for [Craft CMS](https://craftcms.com/) by Pixel & Tonic - Inspired by real-world enterprise migration needs - Tested on production sites with millions of assets πŸ’¬ Support --------- [](#-support) - **Issues**: [GitHub Issues](https://github.com/csabourin/do-migration/issues) - **Discussions**: [GitHub Discussions](https://github.com/csabourin/do-migration/discussions) - **Documentation**: [Architecture Guide](ARCHITECTURE.md) πŸ”— Links ------- [](#-links) - **Repository**: - **Packagist**: - **Craft CMS**: - **DigitalOcean Spaces**: --- Made with ❀️ (and a touch of humor) for the Craft CMS community by the Spaghetti Migrator team ### Health Score 49 β€” FairBetter than 94% of packages Maintenance91 Actively maintained with recent releases Popularity14 Limited adoption so far Community8 Small or concentrated contributor base Maturity70 Established project with proven stability Bus Factor1 Top contributor holds 51.4% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 295 Last Release 44d ago Major Versions v1.8.199 β†’ v2.0.2002025-11-23 v2.0.200 β†’ v3.0.2022025-11-23 v3.0.206 β†’ v5.0.2072025-11-23 PHP version history (2 changes)v1.0.0PHP ^8.0 v1.0.1PHP ^8.0 || ^8.1 || ^8.2 || ^8.3 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/16245338?v=4)[Christian Sabourin](/maintainers/csabourin)[@csabourin](https://github.com/csabourin) --- Top Contributors [![csabourin](https://avatars.githubusercontent.com/u/16245338?v=4)](https://github.com/csabourin "csabourin (378 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (358 commits)") --- Tags migrationcraftcmscraft-pluginaws-s3craft cmscraft-moduledigitalocean-spacesasset-migrations3-migrationcloud-migrationspaghetti-migratoruntangle-assetsnested-folders ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/csabourin-spaghetti-migrator/health.svg) ``` [![Health](https://phpackages.com/badges/csabourin-spaghetti-migrator/health.svg)](https://phpackages.com/packages/csabourin-spaghetti-migrator) ``` ### Alternatives [verbb/formie The most user-friendly forms plugin for Craft. 102393.6k69](/packages/verbb-formie)[dgrigg/craft-migration-assistant Create content migrations at the click of a mouse. Keep environments in sync with ease. 2783.1k](/packages/dgrigg-craft-migration-assistant)[verbb/comments Add comments to your site. 13753.9k](/packages/verbb-comments)[verbb/vizy A flexible visual editor field for Craft. 4250.4k](/packages/verbb-vizy)[verbb/hyper A user-friendly links field for Craft. 24147.8k12](/packages/verbb-hyper)[verbb/social-poster Automatically post entries to social media. 918.5k](/packages/verbb-social-poster) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)