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!
Tip: It might be a good idea to sync your Mautic to a (local) server, try the update, check everything is working and only then update your productive environment.
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
orcomposer 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
- Open your
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.
Comments ()