How to Update to Mautic 5 Using Composer

Mautic 5 is here, but the update process isn't just one click or command if you installed Mautic using composer.

I read many forum posts and distilled my learnings into this article.

This guide walks you through the steps on how to do that. It also lists the errors you might bump into—along with solutions known to me.

Before You Begin: Backup!

Update Mautic Using Composer

Updating Mautic with composer is a bit tricky, because you need to manually change your composer.json.

I'll walk you through the update process step by step. It's a five main steps process. Let's dive in!

Step 1: Add Missing Repositories

First things first, you need to make sure your composer.json is ready. It has to have all the repositories it needs. Run these commands to add them:

composer config repositories.0 git https://github.com/mautic/FOSOAuthServerBundle.git
composer config repositories.1 git https://github.com/mautic/SpBundle.git
composer config repositories.2 git https://github.com/mautic/SymfonyBridgeBundle.git
# Update minimum required PHP version
composer config platform.php 8.0.2

This adds three new Mautic repositories to your composer.json. It also changes the minimum required PHP version to run Mautic to PHP v8.0.2

Additionally, you need to manually edit the composer.json. Composer needs to run some post-update scripts every time you'll update Mautic in the future.

Let's add them. Open your composer.json and overwrite to the "scripts" part with this:

  "scripts": {
    "githooks": [
      "php -r \"if(file_exists('./.git')&&file_exists('./build/hooks/pre-commit'.(PHP_OS=='WINNT'?'.win':''))){copy('./build/hooks/pre-commit'.(PHP_OS=='WINNT'?'.win':''),'./.git/hooks/pre-commit');} if(file_exists('./.git')&&file_exists('./build/hooks/post-checkout')){copy('./build/hooks/post-checkout','./.git/hooks/post-checkout');}\"",
      "php -r \"if(file_exists('./.git/hooks/pre-commit')&&(PHP_OS!='WINNT')){chmod('./.git/hooks/pre-commit',0755);} if(file_exists('./.git/hooks/post-checkout')&&(PHP_OS!='WINNT')){chmod('./.git/hooks/post-checkout',0755);}\""
    ],
    "post-install-cmd": [
      "@githooks",
      "@npm-ci",
      "@npx-patch-package",
      "@generate-assets"
    ],
    "post-update-cmd": [
      "@githooks",
      "@npm-ci",
      "@npx-patch-package",
      "@generate-assets"
    ],
    "test": "bin/phpunit -d memory_limit=1G --bootstrap vendor/autoload.php --configuration app/phpunit.xml.dist",
    "phpstan": "[ ! -f var/cache/test/AppKernelTestDebugContainer.xml ] && (echo 'Building test cache ...'; APP_ENV=test APP_DEBUG=1 bin/console > /dev/null 2>&1);  php -d memory_limit=4G bin/phpstan analyse --ansi",
    "cs": "bin/php-cs-fixer fix --config=.php-cs-fixer.php -v --dry-run --diff",
    "fixcs": "bin/php-cs-fixer fix -v",
    "rector": "bin/rector process --ansi",
    "npm-ci": "npm ci --prefer-offline --no-audit",
    "npx-patch-package": "npx patch-package",
    "generate-assets": "bin/console mautic:assets:generate"
  },

Step 2: Remove Old Packages

Before we bring in the new, let's clear out the old.

This step removes any plugins or themes that are obsolete in Mautic 5.

composer remove mautic/plugin-citrix mautic/theme-nature mautic/theme-mauve mautic/theme-coffee

Step 3: Update Dependencies

Next, update the package dependencies for Mautic 5. This step ensures that all the required packages are set to their correct versions.

# Core and essential plugin bundles
composer require --no-update "mautic/core-lib":"^5.0"
composer require --no-update "mautic/grapes-js-builder-bundle":"^5.0" "mautic/plugin-clearbit":"^5.0" "mautic/plugin-cloudstorage":"^5.0" "mautic/plugin-crm":"^5.0" "mautic/plugin-emailmarketing":"^5.0" "mautic/plugin-focus":"^5.0" "mautic/plugin-fullcontact":"^5.0" "mautic/plugin-gmail":"^5.0" "mautic/plugin-tagmanager":"^5.0" "mautic/plugin-outlook":"^5.0" "mautic/plugin-social":"^5.0" "mautic/plugin-zapier":"^5.0"
# Themes
composer require --no-update "mautic/theme-aurora":"^5.0" "mautic/theme-blank":"^5.0" "mautic/theme-brienz":"^5.0" "mautic/theme-cards":"^5.0" "mautic/theme-confirmme":"^5.0" "mautic/theme-fresh-center":"^5.0" "mautic/theme-fresh-fixed":"^5.0" "mautic/theme-fresh-left":"^5.0" "mautic/theme-fresh-wide":"^5.0" "mautic/theme-goldstar":"^5.0" "mautic/theme-neopolitan":"^5.0" "mautic/theme-oxygen":"^5.0" "mautic/theme-paprika":"^5.0" "mautic/theme-skyline":"^5.0" "mautic/theme-sparse":"^5.0" "mautic/theme-sunday":"^5.0" "mautic/theme-vibrant":"^5.0" "mautic/theme-trulypersonal":"^5.0"

Step 4: Run the Update

With everything set up, it's time to run the update.

This command updates all dependencies, ensuring that your Mautic installation moves smoothly to version 5.

composer update --with-all-dependencies
php bin/console cache:clear

Step 5: Run Post-Install Scripts

After updating everything you need to execute some maintenance post-install scripts.

These commands will apply any changes made to the core, migrate the database, and generate the new JavaScript and other assets for your dashboard.

php bin/console mautic:update:apply --finish
php bin/console doctrine:migration:migrate --no-interaction
php bin/console mautic:assets:generate
php bin/console cache:clear

Known Errors while Updating to Mautic 5 Using Composer

While updating you might bump into some errors. Here are a few issues that I know that you might encounter. Along with straightforward solutions to get you back on track.

Class XYZ Not Found Error

• Problem: You might see a fatal PHP error message about a missing class. The messages comes from ParameterLoader.php and looks, similar to this:

PHP Fatal error: Uncaught Error: Class "Symfony\Component\Filesystem\Path" not found in .../mautic/docroot/app/bundles/CoreBundle/Loader/ParameterLoader.php:198

• Underlying Issue: This usually means that some Composer dependencies haven't been installed correctly.
• Solution: Run composer update or composer install again to install any missing dependencies. If the problem persists, the Mautic forum is a great place to seek further assistance.

Warning About Unregistered Commands—The parameter "XYZ" must be defined

• Problem: When attempting to run Mautic, you encounter a warning about commands not being registered due to an undefined parameter:

[WARNING] Some commands could not be registered: In AppKernelProdContainer.php line 11207: The parameter "2F" must be defined.

• Underlying Issue: This usually happens if your email transport (i.e., SMTP, Amazon SES, etc.) password includes special characters. This occurs, because mailer_dsn is not properly configured, as the update process struggles with special character handling for some reason.
• Solution:
  • Open your config/local.php file.
  • Find the mailer_dsn line.
  • Comment it out by adding a # at the beginning of the line.
  • Then, clear the cache. Mautic should now run.
  • Afterwards, you'll need to reconfigure your mailer_dsn from your dashboard

For more details on this issue, check the discussion on GitHub.

npm ERR! code 137 During Installation/Update

• Problem: The NPM build process might unexpectedly terminate, showing an error like this

sh: line 1: 1563 Killed npm run build
npm ERR! code 137
npm ERR! path /var/www/mautic
npm ERR! command failed

• Underlying Issue: This error typically means the NPM build process is consuming too much RAM. As a result the web server kills the process to ensure it won't crash.
• My Current Workaround: Sync your Mautic instance to your local machine, run the NPM build locally, and then sync it back. Here's how you can do it on a Linux system:

cd /tmp
mkdir mtc
cd mtc
rsync -avz -e 'ssh -i ~/.ssh/id_rsa' user@domain.com:/var/www/mautic/ .
npm install
npm ci --prefer-offline --no-audit
npx patch-package
rsync -avz -e 'ssh -i ~/.ssh/id_rsa' . user@domain.com:/var/www/mautic

Tip: Make sure NPM is installed on your local machine for this workaround 😉.

Dashboard Usability Issues

• Problem: You might find that parts of the dashboard aren't working as expected. This can affect buttons or the campaign, email or page builders.
• Underlying Issue: This is likely due to missing JavaScript assets. Most likely because parts of the update process were skipped.
• Solution: Run the following commands to install the necessary assets and regenerate them

npm install
npm ci --prefer-offline --no-audit
npx patch-package
php bin/console mautic:assets:generate

That's a wrap.

I hope this steps helped you upgrade to the newest (and most promising) version of Mautic.

I am eager to use it.

PS If you run into errors go to the forum. You'll find help there.