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.3.1(2mo ago)077MITPHPPHP ^8.0 || ^8.1 || ^8.2 || ^8.3CI passing 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 1mo ago READMEChangelog (1)Dependencies (8)Versions (255)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 **any cloud storage providers**. Whether you're dealing with a tangled mess of nested directories or moving between AWS S3, Google Cloud Storage, Azure, Backblaze B2, Wasabi, Cloudflare R2, 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, Backblaze B2, Wasabi, Cloudflare R2, DigitalOcean Spaces, or local filesystemsβ€”mix and match any combination. - 🚦 **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 command queue visibility. - πŸ” **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) - **18 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, Backblaze B2, Wasabi, Cloudflare R2, DigitalOcean Spaces, or Local 🌍 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**Backblaze B2**Cloud$Fast80% cheaper than S3**Wasabi**Cloud$FastNo egress fees**Cloudflare R2**Cloud$FastZero egress fees**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. **Pre-Flight Validation** - Verify configuration and connectivity 2. **Database URL Replacement** - Update S3 URLs in content tables 3. **Template URL Replacement** - Update hardcoded URLs in Twig templates 4. **File Migration** - Copy physical assets from AWS to DigitalOcean 5. **Filesystem Switch** - Switch volumes to use DigitalOcean Spaces 6. **Configuration Updates** - Update plugin configs and field settings 7. **Transform Management** - Discover and pre-generate image transforms 8. **Post-Migration Verification** - Validate successful migration 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/ # 18 console controllers β”‚ β”œβ”€β”€ MigrationCheckController.php β”‚ β”œβ”€β”€ ImageMigrationController.php β”‚ β”œβ”€β”€ FilesystemSwitchController.php β”‚ └── ... (11 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, queue 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 48 β€” FairBetter than 94% of packages Maintenance94 Actively maintained with recent releases Popularity9 Limited adoption so far Community8 Small or concentrated contributor base Maturity69 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 ~0 days Recently: every ~24 days Total 250 Last Release 64d 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://www.gravatar.com/avatar/54c109c124670c5e142f118e5372242c067554eb332836b8d73b84b22644dec6?d=identicon)[csabourin](/maintainers/csabourin) --- Top Contributors [![csabourin](https://avatars.githubusercontent.com/u/16245338?v=4)](https://github.com/csabourin "csabourin (376 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (356 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 [dgrigg/craft-migration-assistant Create content migrations at the click of a mouse. Keep environments in sync with ease. 2782.3k](/packages/dgrigg-craft-migration-assistant)[nystudio107/craft-seomatic SEOmatic facilitates modern SEO best practices & implementation for Craft CMS 5. It is a turnkey SEO system that is comprehensive, powerful, and flexible. 1741.4M46](/packages/nystudio107-craft-seomatic)[verbb/navigation Create navigation menus for your site. 90683.7k17](/packages/verbb-navigation)[verbb/image-resizer Resize assets when they are uploaded. 127269.1k7](/packages/verbb-image-resizer)[verbb/formie The most user-friendly forms plugin for Craft. 101372.9k40](/packages/verbb-formie)[verbb/cp-nav Manage the Craft Control Panel navigation. 128186.9k3](/packages/verbb-cp-nav) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)