Why Upgrade to Mautic 5?

The Mautic 5.x series has raised the bar for marketing automation, delivering powerful new features and updates:

• Mautic 5.0: This version introduced Symfony 5 and PHP 8.1 compatibility, making your platform faster, more secure, and future-proof. It also revamped outdated dependencies for better stability.
• Mautic 5.1: The Andromeda Edition added 10 new features, 168 enhancements, and 130 bug fixes, focusing on usability and reliability.
• Mautic 5.2: The Pleiades release introduced a fresh user interface alongside 12 new features, 97 enhancements, and 75 bug fixes to make workflows even more intuitive.

A New Release Strategy

To make your experience smoother, we’ve introduced a new release strategy that aligns with the needs of most organizations. Here’s what you can expect:

• Long-Term Support (LTS): Major releases now come with 18 months of active support, including regular updates, bug fixes and security updates to keep the platform running smoothly and securely. Mautic 5.2 is our first LTS release.
• Extended Long-Term Support (ELTS): For businesses needing more time to transition, ELTS offers critical updates for up to two additional years after LTS ends. Learn more about ELTS here.

Stay Ahead with Mautic

The future of Mautic is here. Whether you’re upgrading for the latest features or ensuring your platform remains secure, Mautic 5 has everything you need to keep growing. Explore the latest versions, experience the difference, and take your marketing automation to new heights.

Let’s build the future of marketing together.

While the Mautic 3 release focused on extensive rewrites ‘under the hood’ to support Symfony 3, we are pleased to say that Mautic 4 includes several long-awaited features including:

• New email and landing page builder based on the open source GrapesJS framework
• Four new MJML email templates
• An interface for managing tags within Mautic
• A read-only first phase of the new Mautic Marketplace
• An updated Zapier app including support for OAuth2

This release also provides support for Symfony 4, multiple dependency updates in readiness for PHP 8 support, and removes some long-deprecated technology such as OAuth1 (replaced with OAuth2) and the Froala editor (replaced with CKEditor).

We have also delivered the first phase from three of our six Strategic Initiatives in this release:

• New email and landing page builder
• Composer support
• Mautic Marketplace

With 46 contributors and over 1,700 files changed, this release has been a true community effort with contributions from individuals and organizations across the community.

What has changed?

There are some important changes that we have made in Mautic 4 which users and developers will need to be aware of.

• The new email and landing page builder is enabled by default – you can disable it under Plugins if you prefer to continue using the legacy builder, until Mautic 5 when the legacy builder will be removed. Ensure you reload the page if you disable the new builder.
• All themes you wish to use in the new builder will need a simple, one line change to be made in their configuration file. Read the documentation here.
• Support for OAuth1 has been removed. Use OAuth2 instead.
• The most significant changes will impact developers. A full list of deprecations and backwards compatibility breaking changes can be found here.

Important notes

There are a couple of features with the new builder which we have not been able to complete before the release due to a shortage of people working on the project – read more in the blog post. These include:

• Dynamic content is only available in HTML email themes – work is underway to enable it in MJML themes,
• Dynamic content is not currently available in landing pages,
• Gated video is not currently available in landing pages,
• Code mode can now be accessed from within the builder rather than through the separate ‘code mode’ theme,
• Preference centre pages can be created using tokens – we are in the process of creating a block in the new builder to enable configuration in the user interface.

How do I download Mautic 4?

From today, if you download Mautic from mautic.org/download you will be downloading Mautic 4.

If you prefer to work from Github you can pull the tag 4.0.0.

How do I update to Mautic 4?

Before you consider updating to Mautic 4, you must be running at least the latest stable version of Mautic 3. Updating from Mautic 2 to Mautic 4 is not, and will not, be supported. If you have not yet updated from Mautic 2 to Mautic 3, please review the documentation here.

Once you are running the latest stable version of Mautic 3, make sure that you take a backup of your files and database, and check that they are working by setting up a development area. Also ensure that you have PHP 7.4 available on your server – 7.3 is no longer supported.

Once you have tested your backup, you can proceed with the update in the usual way:

At command line (preferred)

1. Connect to your server at the command line and use the cd command to move into the directory where you have Mautic installed
2. Ensure that your server meets the minimum requirements listed here
3. Ensure that any third-party plugins and integrations have been updated to support Mautic 4 – if you are not sure, temporarily disable them and/or remove them from your plugins directory until after you have completed the update
4. Check for updates using path/to/php bin/console mautic:update:find to find updates, and then path/to/php bin/console mautic:update:apply to apply the updates (replacing path/to/php with the path to PHP on your server)
5. Remember to update your themes to include the new syntax for supported builders!

In the user interface (not recommended)

1. Ensure that your server meets the minimum requirements listed here
2. Ensure that any third-party plugins and integrations have been updated to support Mautic 4 – if you are not sure, temporarily disable them and/or remove them from your plugins directory until after you have completed the update
3. Check for the update alert in your browser notifications
4. Click to update to Mautic 4
5. Remember to update your themes to include the new syntax for supported builders!

Where can I get help?

If you encounter errors with installing or upgrading to Mautic 3, we have dedicated documentation available, and a forum category for community-powered support.

We also have a dedicated forum category for Mautic 4 install and upgrade in the community forum.

Please ensure that you use the post template and provide all the required information, as this enables our volunteers in the forum to troubleshoot with you more efficiently.

This has been the culmination of over a year’s work by several individuals in the Mautic Community, and has been available since the Mautic 3.2 release for beta testing.

What is the new builder?

The new builder has been created using the open source GrapesJS framework which supports email and landing pages in Mautic. This enables a fully responsive drag-and-drop interface which is highly customizable and easy to use.

The new builder also allows you to use both the traditional HTML markup in themes while also supporting the modern way to create great responsive email themes using MJML.

How can I use the new builder?

From Mautic 3.2 the builder was available in the Plugins section to enable and test while we were in the beta phase.

From Mautic 4.0, the new builder will now be enabled by default. There is an option to disable the new builder and revert to the legacy builder until Mautic 5, when we will completely remove the legacy builder. Please refer to the documentation for instructions on how to do this. Please note you should as a matter of course clear your Mautic cache, browser cache and refresh the page after updating, to ensure you are getting the latest builder files after updating.

Are there any limitations or known issues?

Currently there are some MJML elements which are not rendered by the builder:

1. mj-head components are not rendered:

   mj-attributes, mj-breakpoint, mj-font, mj-html-attributes, mj-preview, mj-style, mj-title
    

2. Body components not rendered include:

   mj-table

Blocks for implementing the following features are not yet ready for release but will follow in subsequent releases:

1. Preference centre configuration on landing pages (tokens still function as a workaround, and work is almost complete to bring full configurability)
2. Gated video on landing pages
3. Dynamic content on landing pages
4. Dynamic content on MJML-based email templates (Dynamic Content is still available in HTML-based emails)

How can I contribute to improving the new builder?

We would love to have new contributors both in the code and with improving the documentation, resources and tutorials that we now need to update using the new builder!

Please join us in Slack (get an invite at https://mautic.org/slack) at #i-builders where the team can advise you on getting started or tasks that are outstanding. You can find issues in the core Mautic issue queue with the label builder-grapesjs.

For developers, anything related to Mautic and the integration with GrapesJS can be found in the plugin directory, and anything related to GrapesJS itself (such as the blocks, components etc) can be found in the Mautic preset.

Where can I learn more about the builder? 

We have information available in the Documentation which explains more about the new builder.

Many organizations are moving toward a GitOps-based approach to managing software, and the way that Mautic was configured from the Composer perspective was previously suboptimal for organizations who need to manage Mautic installation and deployment with Composer.

This also made it very difficult to apply patches – whether from Mautic or from the organization themselves – in a way that is commonly accepted as best practice.

Two other Strategic Initiatives – Mautic Next Generation and the Mautic Marketplace – depend on significant changes to our architecture for being able to decouple plugins and themes and also have them managed independently.

We announced the Composer Initiative as a Strategic Initiative in November 2020 and work started to determine how to move Mautic toward a more future-friendly configuration.

What we have done

This project has been led by Nick Veenhof from Dropsolid and we are extremely grateful for his knowledge and time in making this initiative a reality. Also, big thanks to Rahul Shinde, John Linhart, and Dennis Ameling for their support in testing, reviewing, and suggesting improvements; and to the Drupal project from which we have taken much inspiration!

Three things were kept in mind when deciding how to execute this project:

• Making the developer experience as smooth as possible
• Enabling a phased approach to decoupling from core
• Following established best practices

There are several key things to be aware of now that we have mostly completed this project.

1. While we have ‘technically’ decoupled the app directory, all plugins, and themes into separate repositories, you will still find them located in the original folders in github.com/mautic/mautic at this stage:
   1. This approach allows for a smooth development process as all the files and folders that you see in Mautic are in the same repository.
   2. In the future, we may consider removing some plugins that are not widely used from Core and enabling users to selectively install them via the marketplace.
   3. Those plugins will, at that point, become maintained by a separate Tiger Team.
   4. The mirror repositories are read-only, pull requests should be made against https://github.com/mautic/mautic, not the mirrors – you will receive a reply from the bot if you attempt to make a PR against a mirror.
2. Whenever a pull request is made which touches any of these files, the changes are automatically pushed down to the read-only mirror repositories thanks to the amazing tool SubTreeSplit by Tobias Nyholm.
3. We now have a composer.json file in /app (as well as in all plugin and theme directories) which is used to build Mautic when installing with Composer.
4. We now have the Recommended Project repository – https://github.com/mautic/recommended-project and the scaffold – https://github.com/mautic/core-composer-scaffold which allows you to manage dependencies and move files outside the web root directory if you wish to do so.

What happens when you build Mautic

As before, you can still pull down Mautic and use the composer install command to install dependencies. This will now be much faster thanks to the upgrade to Composer 2.

You will notice that we now have a requirement on mautic/core-lib – this is the /app folder. We also now pull in all of the plugins and themes individually however in this first phase, we are telling Composer to use the files which it finds in mautic/mautic rather than looking elsewhere for the files – this is a precursor to being able to move some of this outside of the core.

We have also added some configuration settings and we set the correct paths for the different types of resources we are pulling in – the app directory, plugins, and themes.

Within the app folder, we have an additional composer.json file (in fact, all plugins and themes also now have a composer.json file) which has some settings relating to the scaffolding.

How do you use the recommended project?

This recommended project template provides a starter kit for managing your Mautic dependencies with Composer.

Usage

Note: The instructions below refer to the global composer installation. You might need to replace composer with php composer.phar (or similar) for your setup.

After that you can create the project:

composer create-project mautic/recommended-project:4.x-dev some-dir --no-interaction

With composer require … you can download new dependencies to your installation.

cd some-dir
composer require mautic/mautic-saelos-bundle:~2.0

The composer create-project command passes ownership of all files to the project that is created. You should create a new git repository, and commit all files not excluded by the .gitignore file.

What does the template do?

When installing the given composer.json some tasks are taken care of:

• Mautic will be installed in the public-directory.
• Autoloader is implemented to use the generated composer autoloader in vendor/autoload.php, instead of the one provided by Mautic (public/vendor/autoload.php).
• Plugins (packages of type mautic-plugin) will be placed in public/plugins/
• Themes (packages of type mautic-theme) will be placed in public/themes/
• Creates public/media directory.
• Creates environment variables based on your .env file. See .env.example.

Updating Mautic Core

This project will attempt to keep all of your Mautic Core files up-to-date; the project mautic/core-composer-scaffold is used to ensure that your scaffold files are updated every time mautic/core is updated. If you customize any of the “scaffolding” files (commonly .htaccess), you may need to merge conflicts if any of your modified files are updated in a new release of Mautic core.

Follow the steps below to update your core files.

1. Run composer update mautic/core –with-dependencies to update Mautic Core and its dependencies.
2. Run git diff to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to .htaccess or others.
3. Commit everything all together in a single commit, so the public will remain in sync with the core when checking out branches or running git bisect.
4. In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use git merge to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as kdiff3. This setup is not necessary if your changes are simple; keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy.

FAQs

Should I commit the contributed plugins I download?

Composer recommends no. They provide arguments against but also workarounds if a project decides to do it anyway.

Should I commit the scaffolding files?

The Mautic Composer Scaffold plugin can download the scaffold files (like index.php, .htaccess, …) to the public/ directory of your project. If you have not customized those files you could choose to not check them into your version control system (e.g. git). If that is the case for your project it might be convenient to automatically run the mautic-scaffold plugin after every install or update of your project. You can achieve that by registering @composer mautic:scaffold as post-install and post-update command in your composer.json:

"scripts": {
"post-install-cmd": [
"@composer mautic:scaffold",
"..."
],
"post-update-cmd": [
"@composer mautic:scaffold",
"..."
]
},

How can I apply patches to downloaded plugins?

If you need to apply patches (depending on the project being modified, a pull request is often a better solution), you can do so with the composer-patches plugin.

To add a patch to Mautic plugin foobar insert the patches section in the extra section of composer.json:

"extra": {
"patches": {
"mautic/foobar": {
"Patch description": "URL or local path to patch"
}
}
}

How do I specify a PHP version?

This project supports PHP 7.4 as the minimum version, however, it’s possible that a composer update will upgrade some package that will then require PHP 7+ or 8+.

To prevent this you can add this code to specify the PHP version you want to use in the config section of composer.json:

"config": {
"sort-packages": true,
"platform": {
"php": "7.4"
}
},