How to switch a legacy Mautic install to Composer without touching the database
The short answer is that the codebase is rebuilt with composer create-project mautic/recommended-project in a new directory, and the existing database is kept and reused. Switching to a Composer-based installation changes only the code, not the data, so contacts, segments, campaigns and configuration stay where they are. For a team running a self-hosted Mautic from a ZIP package, this matters because current releases and the Mautic Marketplace assume the Composer layout. Mautic's own switching guide notes that Composer became the default installation and update method with Mautic 5, partly because ZIP installs caused installation and update errors and are incompatible with the Marketplace.
The effort depends on several things you need to pin down before any work starts. The first is the target release, since each release line has its own PHP and database requirements and its own support window. Mautic 7.0 requires PHP 8.2, 8.3, 8.4 or 8.5 and MySQL 5.7 or higher with InnoDB, or MariaDB 10.2 or higher. Your current server may fall short of one of those, and a PHP or database upgrade then becomes part of the scope. The second is your custom plugins and any changes made inside the ZIP tree, because those files do not carry over automatically and must be reviewed against the new layout. The third is your cron setup. Segment updates, campaign updates, campaign triggers, the broadcasts command and, where emails are queued, the messenger consumer all need to be re-pointed at the new directory and checked for staggering.
Before you schedule the cut-over, confirm three things with your own team and the vendor documentation. Check the exact PHP extensions and Composer version the target release expects, and test the build on a copy of the production database rather than on the live system. Record the current web server and cron user, because permissions and paths often break during the move. Plan a rollback path that keeps the old ZIP directory intact until the new install has run through a full campaign cycle. Ask for a written scope that lists the target release, the plugins in scope, the server changes and the verification steps, so that effort and duration can be quoted against facts rather than assumptions.
What carries over from a ZIP install and what gets rebuilt
This table compares a legacy ZIP-based Mautic install with the Composer-based install across the database, codebase, plugins, Marketplace, updates, cron jobs and runtime requirements. Read the rows marked as carried over as settled facts, and treat the rows about your configuration, custom plugins and themes as items your team must verify in its own environment before cutover, since those depend on what your install contains.
| Area | Legacy ZIP install | Composer-based install |
|---|---|---|
| Database | Holds contacts, campaigns, segments and settings. Stays in place during the switch. | Left untouched. The switch changes only the codebase, so the same database is reused. |
| Codebase | Files were unpacked from a ZIP package and edited in place over time. | Rebuilt from composer create-project mautic/recommended-project in a new directory. |
| Custom plugins and themes | Copied into the existing tree. Their compatibility with the new layout must be checked by your team. | Must be re-added and confirmed against the new codebase. Verify each plugin and theme before cutover. |
| Marketplace | Not compatible with ZIP installs, per the Mautic switching guide. | Compatible, since Composer is the method the Marketplace supports. |
| Updates | Manual file replacement, which the Mautic project links to installation and update errors. | Updated through Composer, the default method since Mautic 5. Confirm the update steps in the current how-to guide. |
| Cron jobs | Existing schedules point at the old path. Review them after the move. | Reconfigure cron jobs to the new install path, staggered as the docs describe for segments, campaigns and triggers. |
| Runtime requirements | Confirm your current PHP and database versions against the release you target. | Mautic 7.0 requires PHP 8.2 to 8.5, MySQL 5.7 or higher with InnoDB or MariaDB 10.2 or higher, and npm from Mautic 5.0. |
Why Composer replaced ZIP installs and what the rebuild involves
Composer is now the default way to install and update Mautic, and a ZIP-based installation has to be rebuilt around it before you can move to a current release line. Mautic's switching guide gives two reasons for the change: Composer became the default with Mautic 5, partly because ZIP installs produced installation and update errors, and ZIP installs are incompatible with the Mautic Marketplace. For your team, the practical consequence is that the code tree on your server must be replaced with one that Composer manages, not patched in place.
The rebuild starts in a new directory. You create it with composer create-project against the recommended project template, which gives you a fresh Mautic codebase with its dependencies resolved. The important boundary is what does not change: the switch touches only the codebase. Your existing database, with its contacts, segments, campaigns, users and configured integrations, is reused as it stands. That means the new tree must be pointed at the same database and the same data, so any schema or version differences are handled by the upgrade steps rather than by a fresh install.
Before you point the new tree at live data, your team owns the reconciliation work. Inventory every local modification to the old ZIP tree, including edited core files, theme or template overrides, custom plugins in the plugins directory, and anything set in the local configuration file. Decide for each item whether it is still needed, whether it belongs in a supported plugin or configuration setting, or whether it should be dropped. Custom plugins must be checked against the Composer-based layout and the Mautic version you are targeting. Environment settings such as the database host, mailer, cron-related paths and the site URL must be carried over deliberately, because a missing value can break the cutover in ways that only appear after traffic resumes.
Plan the cutover around a verified copy of the database and a rollback path. Take a full backup of the database and the old code tree, then run the switch against a restored copy in a non-production environment first. Confirm that logins work, that segment and campaign jobs still run from cron, and that any messenger consumer used for queued email is reading from the right place. Record which customizations were removed or replaced, because your auditors and future upgrade owners will need that trail. Ask any partner to state in the written scope who performs the reconciliation, who signs off on the test copy, and who owns the rollback decision.
Confirm the target release line before you start, since the rebuilt tree must meet that version's PHP and database requirements. Check the current supported versions and PHP range on the Mautic releases and requirements pages, and confirm your database engine and server stack against them. Because the switch is a codebase change, the effort is driven mainly by how much custom code and configuration you have to reconcile, and how many environments must be rebuilt and tested. Ask for those drivers to be itemized in any quote so the work is clear before it begins.
Documented paths and tools for the switch
Mautic documents a small set of tools for this move, and they connect in a fixed order: the switch starts from Composer, and later upgrades follow the update guide. Use the official switching guide as the procedure of record, and check each step against your own installation before you touch production.
Composer recommended project template
The switch begins by running composer create-project mautic/recommended-project in a new directory, which builds a fresh Composer-based codebase alongside your existing ZIP install. Because the switch changes only the codebase and leaves the database untouched, this new directory is where your team rebuilds the application before pointing it at the existing data. Confirm the PHP and database versions required by the release you select before you run the command.
Mautic switching guide
The official switching guide is the step-by-step procedure for moving a ZIP-based installation to Composer. It explains why Composer became the default install and update method with Mautic 5, citing installation and update errors with ZIP installs and their incompatibility with the Marketplace. Read it in full before scheduling the change, and compare its steps with your own configuration, plugins and file customizations.
Mautic update guide for later upgrades
After the switch, routine upgrades follow the official update guide rather than a fresh ZIP extraction. Your team should keep this guide with the runbook, since the steps for later releases depend on the Composer layout created during the switch. Plan who owns upgrades once the move is complete, because the release cadence includes monthly patches and releases that carry security fixes.
Marketplace requires Composer setup
The Mautic Marketplace requires the Composer-based setup, so plugins and extensions you plan to install from it depend on completing the switch first. Check which Marketplace items your business depends on and confirm their compatibility with your target release before you commit to a date. Keep a list of custom or ZIP-installed plugins, because those need a separate compatibility review.
Web, command-line and GitHub install paths
The web installer, the command-line installer and GitHub are documented for other install paths, including the production package and local development. These paths are useful for fresh environments, but they do not replace the Composer switch for an existing ZIP installation. Confirm with the documentation which path fits each environment, such as a development copy, before your team uses it for a migration rehearsal.
No documented conversion tool
Mautic's documentation describes the switch as a manual procedure that starts from Composer. It does not document an export or conversion tool that converts a ZIP installation automatically, so do not plan around one. Ask your implementation partner and internal team to confirm the procedure against the current guide, and record any step that depends on your own environment.
Sequence for a Composer switch: inventory, build, parallel run and cutover
The sequence moves a ZIP-based Mautic install onto a Composer tree while the database stays as it is, with each stage proving the next one is safe before the live site changes.
Inventory the current install
Record everything the running ZIP install depends on: the Mautic version, the PHP version, the database engine and version, every installed plugin and theme, the cron entries that trigger segment updates, campaign updates and campaign triggers, and every external integration such as CRM connectors, SMS providers and email transports. Also note whether a messenger consumer and the broadcasts command are already running. Your team or DeployOpen produces this list, and it is done when a second person can read it and rebuild the environment from it without asking questions. Confirm each target PHP and database version against the Mautic 7.0 requirements before you commit to a release line.
Take a full backup of files and database
Create a complete backup of the installation directory, including local configuration, custom plugins, themes, media uploads and the environment settings, plus a full logical dump of the database. Store the backup outside the server and test a restore on a separate machine so you know the archive is usable. This step is complete when the restore test has opened the application against the restored database and the backup location and retention are written into the change record. The backup is the rollback path for every later step, so it is not optional.
Build the Composer tree in a new directory
Create a new directory next to the existing install and run the Composer create-project command for the recommended Mautic project template. Keep the ZIP install untouched during this work. Add your custom plugins and themes to the new tree through Composer requirements or local path repositories, and move local configuration across without copying the old vendor or cache folders. This is done when the new tree installs cleanly with no dependency errors and the Mautic console reports a healthy state. Record the exact Composer version and lock file so the build can be reproduced.
Connect the new tree to a database copy
Restore the full database backup into a separate database instance or schema and point the new Composer tree at that copy. Do not point the new tree at the live database yet, because at cutover both trees would read and write the same tables. Run the Mautic database update path only against the copy and review any schema changes it reports. This step is done when the new tree loads, the admin login works against the copied data and the record counts for contacts, segments, campaigns and emails match the source.
Run a parallel test against the database copy
Exercise the new tree against the copy while the old install keeps serving production. Check contact and segment views, a sample of campaign runs, email sending to test addresses, form submissions, tracking, user logins and each integration plugin, including outbound calls to the CRM and SMS providers using sandbox credentials where available. Run the cron jobs manually against the copy in the staggered order you plan to use. The step closes when every item on the test list has a recorded pass or a logged defect with an owner.
Schedule cutover with cron, broadcasts and messenger in place
Prepare the cutover runbook. Define a maintenance window, a freeze on contact and campaign edits, the order in which you stop the old cron entries and the messenger consumer, the final database backup taken just before switching, and the point at which the web server is pointed at the new tree. Configure the new cron jobs with staggered timings as the Mautic cron documentation recommends, and confirm that the broadcasts command and the messenger consumer are running under the new tree before the old ones are stopped. The step is done when the runbook has been rehearsed on the copy and each person named in it has signed off.
Cut over to the Composer tree
Stop the old cron entries and the messenger consumer, take the final database backup, then point the web server at the new Composer tree and run the database update against the live database once, since the new tree is now the only writer. Re-enable cron and the consumer in the new tree, then check that segment updates, campaign triggers and queued emails are moving. This step is complete when logins, a test campaign and a test email succeed on the live site and the monitoring shows no new errors in the first working period.
Decommission the ZIP install after the rollback window
Keep the ZIP install and its backups in place through an agreed rollback window, during which a return to the old tree is possible if a defect appears that the copy test missed. Once the window closes without rollback, remove the old cron entries and service units that still point at it, archive the ZIP directory with the backups, and update the runbook, inventory and monitoring to reference only the Composer tree. The step is done when the old paths are gone from every scheduler and the change record is closed with the retained backup location.
Which PHP, database and hosting the Composer install must meet
Before you rebuild the codebase, confirm that the target environment meets the requirements of the Mautic release you plan to run. For Mautic 7.0, the project's requirements page lists PHP 8.2, 8.3, 8.4 or 8.5, MySQL 5.7 or higher with the InnoDB storage engine, or MariaDB 10.2 or higher, and a web server of Apache, Nginx or IIS. Because the Composer install runs against the same database you already have, the database engine and version on the new server must match or exceed what the legacy install already uses. Check the versions with the server, not the documentation, and record the results alongside the PHP extensions your current install depends on.
Node.js and npm. From Mautic 5.0 onward, npm is required as well. It is needed to build front-end assets, so it must be available to the user that runs the Composer and build steps, not only on the production web server. If your build runs on a separate machine, confirm that the artifacts it produces can be copied to the production host. Ask your team who owns this step and whether the build environment is kept under change control.
Hosting. The Mautic project states that Mautic should not be installed on shared hosting and recommends a VPS or dedicated server instead. Composer-based installs add dependency downloads, build tooling and scheduled jobs that shared plans often restrict. Cron jobs for segment and campaign processing, plus the broadcast and messenger workers, need a host where you control scheduling and long-running processes. If your legacy install already runs on shared hosting, treat moving to a VPS or dedicated server as part of this project and cost it before you commit to a date.
Choosing a target release. The support window determines which release is worth moving to. The Mautic releases page lists Mautic 7.2 (Absolunto) with active and security support until 30 September 2026, and Mautic 7.3 is planned as the long-term support release with security support through 31 December 2027. Mautic 6.0 received security support until 30 September 2026, and Mautic 5.2 until 30 June 2026. Mautic 4.4 has paid Extended Long Term Support through 31 December 2026. Support dates can change, so confirm the current status on the releases page before you choose a target, and check whether 7.3 has been released by the time you plan the cutover.
What to confirm. Ask your team to document the PHP version, database engine and version, web server, Node.js and npm versions, and host type on both the current and planned environments. Confirm the target release against the releases page and the requirements page on the day you start, and record the decision so it can be reviewed later. Any gap found here is cheaper to close before the new codebase is built than during the database cutover.
What drives the effort and cost of the switch
This table lists the factors that raise or lower the effort of moving a ZIP-based Mautic install to Composer, and whether each one is paid once or recurs. Use it to see which parts of your install will move the quote, and bring the answers to the written scope so each quote item can be compared on the same basis.
| Driver | Why it changes effort or cost | What to ask for in a written quote |
|---|---|---|
| Version gap to the target release | The further the current install sits behind the target, the more upgrade stops, PHP and database changes and regression checks are needed. One-time. | Named starting and target versions, the upgrade path, and which stops are included in the scope |
| PHP and database versions | Target releases list supported PHP versions and MySQL or MariaDB minimums. Moving PHP or the database server can add host work before the codebase change. One-time. | Confirmation of current and target PHP, database and web server versions, and who changes each one |
| Custom plugins and themes | Each plugin or theme must be checked for Composer compatibility, moved into the new project layout and retested. Count and complexity both matter. One-time. | Inventory of plugins and themes with a compatibility decision for each, and whether custom code is rewritten or only relocated |
| State of the existing database | Database cleanup, schema checks and any pending migrations must be done before the codebase switch. A clean, current database lowers risk. One-time. | Database audit findings, the schema state, and any cleanup work listed separately |
| Cron and messenger setup | Segment updates, campaign triggers, broadcasts and queued email depend on scheduled jobs and a messenger consumer. Each must be recreated and verified on the new codebase. One-time, with ongoing monitoring afterward. | Cron and consumer inventory, the staggering plan, and who owns monitoring after handover |
| CRM and other integrations | HubSpot or Salesforce connections, SMS and email transports store credentials and sync settings that must be reconfirmed after the move. Recurring checks follow if sync runs continuously. | List of integrations, their plugin versions, credential handling and a test plan for each sync direction |
| Hosting type | Mautic is not supported on shared hosting, so a non-VPS or non-dedicated host may need replacement before the switch. This can be a one-time host change with recurring hosting fees. | Confirmation of the current host type, any host migration in scope, and the recurring hosting cost owner |
| Backup and rollback requirements | Full backups of files and database, plus a tested rollback path, add preparation time. Recurring backup jobs are a separate ongoing cost. | Backup scope, retention period, restore test evidence and the rollback procedure with its decision point |
| Testing scope | Smoke tests only, or full regression across campaigns, forms, emails and integrations, changes the effort more than any other driver. One-time, with optional retainer testing later. | Test cases by area, the environments used, who signs off, and whether the scope includes post-switch monitoring |
What usually goes wrong during a Composer switch and how to prevent it
A Composer switch changes only the codebase, but the failures that hurt most sit around it: database changes, plugins, scheduled jobs, queues, hosting and rollback. Each card below names one failure and the check that prevents it before cutover.
Pointing the new codebase at the database early
Running the new Composer-based codebase against the live database before validation can apply schema or configuration changes that the old ZIP installation cannot read back. Keep the production database untouched until the new directory has been tested against a copy. Take a verified database backup and confirm you can restore it before the first connection from the new code.
Custom plugins incompatible with the target release
Plugins built for the old ZIP layout or an older Mautic release may fail, or silently break, on the target version and PHP runtime. Inventory every custom and third-party plugin, record its version and source, and check each against the release you are moving to. Plan a fix or replacement for any plugin that cannot be confirmed as compatible before cutover.
Segment and campaign cron jobs left unchanged
Cron entries for segment updates, campaign updates and campaign triggers often point at the old installation directory or run at the same time. When they are not staggered or still reference the old path, campaigns can run twice, run from the wrong code, or stop entirely. Rewrite every entry to the new directory, stagger the schedules as the cron documentation advises, and confirm each job logs a successful run.
Broadcast and cron schedule overlap
Segment email sends depend on the broadcasts command, and jobs that run together can compete for the same database rows and mail queue. Review the full crontab as one schedule, not job by job, and confirm which jobs must not overlap. Test the order on the new directory before the old crontab is disabled.
Missing messenger consumer for queued email
When email is queued through the messenger component, nothing is delivered unless a consumer process is running. A consumer that was started manually or pointed at the old directory will stop after the switch, and messages will accumulate without an error on the marketing side. Make the consumer a supervised service that starts on boot, points at the new directory, and is verified by sending a test message through the queue.
Shared hosting that cannot run the stack
The Mautic project states that it should not be installed on shared hosting and recommends a VPS or dedicated server. Composer, the required PHP version, long-running consumers and the cron schedule often cannot run on a shared plan. Confirm the host supports the PHP and database versions in the requirements, allows background processes, and gives shell access before committing to the switch.
Skipping a tested rollback plan
Without a rollback plan, a failed cutover can leave the team unable to send email and unsure whether the database has changed. Keep the old ZIP directory, the crontab and the database backup intact, and write down the steps to repoint the web server and cron back to the old code. Rehearse the rollback on the staging copy so the steps are known to work before production.
Questions buyers ask before switching Mautic to Composer
How much does it cost to switch Mautic to Composer?
Cost is driven by the work to rebuild the codebase on Composer. The Mautic software is free and licensed under GPL-3.0, so the spend goes to labor, testing and infrastructure. The main drivers are how many plugins and custom changes the legacy install carries, how many integrations need end-to-end testing, how much of the environment (PHP version, web server, cron and queue workers) must be updated, and how long the test window runs. Discovery, rebuild, testing and cutover are one-time costs. Hosting, patching and any support retainer recur. When you request a quote, ask for line items for each phase, the assumptions behind the plugin and integration count, what is excluded, and what the handover includes. Fixed-scope proposals are agreed in writing before work starts.
How long does a legacy Mautic Composer switch take?
Duration depends on the size and condition of the existing install and on what your organization can approve and test. The factors that matter most are the number of plugins and custom code, the number of integrations (CRM, email transport, SMS) that must be verified, the quality of the plugin inventory, the PHP and web server changes required by the target release, and how quickly staging access and a test window are available. Realistic production-like data shortens testing because problems surface earlier. Ask any partner to show the phases, dependencies and inputs needed from you before a schedule is set. Treat any single duration offered before a scope review as provisional until it appears in the written scope.
Does switching Mautic to Composer change the database?
No. Switching to Composer changes only the codebase, and the database stays as it is. The process starts by creating a new Composer project in a new directory with composer create-project for the recommended Mautic project, then carrying configuration and customizations across. Take a full database backup before cutover anyway, because the database is the one part you cannot rebuild from code. Also check the upgrade or migration notes for your target release before running anything against production, and keep the legacy directory untouched until the new installation has been verified end to end.
What must our team provide for a Mautic Composer switch?
Your team provides the inputs that decide whether the work stays on schedule. These are a current full backup of the database and files, administrative access to the existing server and the target environment, a complete inventory of plugins and custom code with their versions, credentials for each integration such as the CRM and the email or SMS services, and a test window agreed in advance. Name a business owner who can sign off on contact, segment and campaign checks. A staging copy of production is useful if you can provide one. Missing inputs usually appear as delays during discovery or testing, so ask for a written checklist before work starts.
Can our internal team switch Mautic to Composer ourselves?
Yes, an internal team can do this if it has PHP, Composer and Symfony-aware operations skills, a staging environment that mirrors production, and time to test every plugin and integration. The difficult part is verification more than the Composer commands. Teams often underestimate plugin reconciliation, cron and messenger worker configuration, and end-to-end integration testing. An outside partner is useful when deadlines are fixed, the install carries many custom changes, or staff capacity is limited. DeployOpen plans, implements and documents this work in infrastructure you control under fixed-scope agreements, so you can compare an internal estimate with a written scope.
Which Mautic release should we target when switching to Composer?
Choose the target release by checking its PHP requirement, its support window and your hosting plan before you rebuild. Mautic 7.0 requires PHP 8.2, 8.3, 8.4 or 8.5, MySQL 5.7 or higher with InnoDB or MariaDB 10.2 or higher, and Apache, Nginx or IIS, with npm needed from Mautic 5.0 onward. Mautic 7.3 is planned as the long-term support release, so teams that want the longest security horizon will weigh it heavily once it is available. Confirm its release status and final support dates on the Mautic releases page. Also confirm that every plugin supports the target version, because plugin compatibility often sets the practical release choice.
Which Mautic support dates should we confirm before switching?
Confirm these dates against the Mautic releases page before you commit. Mautic 5.2 (Capella) receives security support until 30 June 2026, Mautic 6.0 (Tabit) until 30 September 2026, and Mautic 7.2 (Absolunto) has active and security support until 30 September 2026. Mautic 4.4 has paid Extended Long Term Support through 31 December 2026. Mautic 7.3 is planned as the long-term support release with security support through 31 December 2027. Compare these dates with your go-live date, and remember the stated cadence of monthly patch releases, minor releases every three months and major releases every two years, so the chosen line stays supported after launch.
What usually breaks during a Mautic ZIP to Composer switch?
The most common failures come from plugins and custom code that depend on the old ZIP layout, from Composer dependency conflicts, and from cron and queue workers that were never pointed at the new installation. Check that segment updates, campaign updates and campaign triggers run on staggered cron schedules as the cron documentation describes, that the broadcasts command runs for segment emails, and that a messenger consumer is running when emails are queued. Also verify that the web server points at the new project's web root, that file permissions allow the application to write its cache and logs, and that the Node tooling needed for assets is available. Send one test campaign end to end before cutover.
How DeployOpen scopes and delivers a Mautic Composer switch
DeployOpen plans and carries out the move from a ZIP-based Mautic install to the Composer-based setup as a fixed-scope engagement, with the written scope agreed before work starts. The codebase is rebuilt from the Composer project template while the existing database is kept intact, and the work is documented for your team to run.
How we scope
- Inventory the current Mautic version, PHP version, plugins, themes and custom code before estimating any work.
- Confirm the target release line and check PHP and database versions against the Mautic requirements.
- Agree in writing which plugins, customizations and cron and queue jobs move across and which are retired.
How we build
- Create the new Composer project in a separate directory from the recommended project template, leaving the live install untouched.
- Port custom code, plugin configuration and environment settings into the new codebase and verify each one.
- Test the rebuilt instance against a copy of the production database, covering logins, segments, campaigns and email sending.
How we hand over
- Document the final directory layout, Composer update procedure and rollback steps for your operations team.
- Walk through the cutover runbook, including the database check and the switch of the web root.
- Provide the configured cron schedule for segment updates, campaign triggers and the broadcasts command, plus the messenger consumer if emails are queued.
How we support
- Support after handover can be provided as a retainer covering patch and minor release updates on your chosen release line.
- Ask for the support response terms and the update cadence in the written quote, since these vary by engagement.
- Confirm with your team which Mautic release line you will stay on, using the project's published support end dates.
