As an open-source project maintained by the community, Mautic is a continual work-in-progress with new features & bug fixes always being added to the codebase. Contrary to what most users’ believe, you don’t need to wait for the next Mautic release if you have a pressing problem which a developer on the Mautic GitHub has already created a patch for. We recommend this guide for intermediate to advanced users, comfortable with the Linux command line with basic knowledge of Git and programming principles.
Caveat: Untested code that has not been merged officially by Mautic’s maintainers should always be considered alpha-quality, not guaranteed to function correctly in production. Testing a patch from GitHub should ideally happen on a separate, staging instance of Mautic. In any circumstances, always make a full backup of your instance before applying a Github patch.
GitHub patches should be considered experimental. Reading other users’ comments and checking the contribution history of a developer who submits a pull request can help inform about whether the patch is safe and effective to use.
Often problems with Mautic occur in the versions ending with 0, such as 2.xx.0. Bug fix releases such as 2.xx.1 or 2.xx.2, are usually more stable with the major bugs in the point-zero release resolved. Usually within hours of a Mautic release coming out, the issue tracker will begin filling up with bug reports. If you encounter an error in the Mautic error log (view at gear icon > System Info > Error Log in the dashboard, or /app/logs/ in the Mautic folder on your server), searching for that PHP error message on GitHub (or Google) will reveal any other users who encountered the same problem.
Here are two examples of how we recently used patches to resolve issues with broken Mautic features for our customers after they upgraded to the latest Mautic version. Note that you should not proactively apply these patches unless you use the specific feature and are encountering problems. Sometimes new commits can cause regressions in other features. If unsure, it is recommended to have a Mautic consultant assess the benefits versus risks of installing a patch on your instance.
Bounce/unsubscribe tracking through webhooks not working (2.15.0)
Problem: On a new Mautic instance, the client opted to use Amazon SES as their email gateway along with Amazon SNS to alert their server about any bounces & unsubscribes through webhooks. After setting up the webhook in the AWS dashboard and providing the Mautic callback URL at https://mautic.example.com/mailer/amazon/callback, the error log showed this 500 internal server error. The SNS subscription remained in the “PendingConfirmation” instead of being confirmed, which meant SES could not send notification events to the Mautic instance.
[2019-02-05 15:03:07] mautic.CRITICAL: Uncaught PHP Exception Symfony\Component\Debug\Exception\FatalThrowableError: "Type error: Argument 1 passed to Mautic\EmailBundle\Swiftmailer\Transport\AmazonTransport::processCallbackRequest() must be an instance of Symfony\Component\HttpFoundation\Request, null given, called in /html/app/bundles/EmailBundle/EventListener/EmailSubscriber.php on line 172" at /html/app/bundles/EmailBundle/Swiftmailer/Transport/AmazonTransport.php line 97 {"exception":"[object] (Symfony\\Component\\Debug\\Exception\\FatalThrowableError(code: 0): Type error: Argument 1 passed to Mautic\\EmailBundle\\Swiftmailer\\Transport\\AmazonTransport::processCallbackRequest() must be an instance of Symfony\\Component\\HttpFoundation\\Request, null given, called in /html/app/bundles/EmailBundle/EventListener/EmailSubscriber.php on line 172 at /html/app/bundles/EmailBundle/Swiftmailer/Transport/AmazonTransport.php:97)"} []
[2019-02-05 15:03:31] mautic.NOTICE: PHP Notice - Undefined variable: request - in file /html/app/bundles/EmailBundle/Event/TransportWebhookEvent.php - at line 56 [] []
Solution: GitHub issues #7199 and #7217 revealed that other users were experiencing the identical issue. The pull request (patch) contributed by Aaron Robinson at #7015 fixed this. After testing on a staging instance, the Autoize team applied the patch to the client’s instance and was able to successfully confirm their SNS subscription like in the screenshot below. Bounce and unsubscribe tracking was no longer broken, meaning such events would be reflected correctly in Mautic’s reports.
Forms with multi-select fields hanging on submit ( 2.15.1)
Problem: A client who extensively uses multi-select custom fields (checkboxes) across the Mautic forms in their instance faced an issue with forms hanging at “Please wait” after submission. Understandably they were quite distraught when they contacted our team, as it was causing them to miss leads from contact forms while their expensive Google AdWords campaign kept running. The multi-select fields were critical for this company as it allowed them to segment their leads by “service area”, place them in the relevant email autoresponder campaign, and route them to the correct sales reps.
Fortunately, this PHP error was recorded in the Mautic error log giving us some clues.
[2019-04-02 13:43:40] mautic.CRITICAL: Uncaught PHP Exception Symfony\Component\Validator\Exception\UnexpectedTypeException: "Expected argument of type "string", "array" given" at /var/www/html/vendor/symfony/validator/Constraints/LengthValidator.php line 38 {"exception":"[object] (Symfony\\Component\\Validator\\Exception\\UnexpectedTypeException(code: 0): Expected argument of type \"string\", \"array\" given at /var/www/html/vendor/symfony/validator/Constraints/LengthValidator.php:38)"} []
Solution: We were initially quite puzzled as this problem seemed to occur on some Mautic instances on 2.15.1 and not others. Once we narrowed it down to instances using multi-select custom fields, we located the GitHub issue #7344 which described this precise bug. Applying the patches #7376 and #7375 contributed by Zdeno Kuzmany and Lukáš Drahý, then making sure to clear the Symfony cache miraculously fixed the issue. The commits fixed the reference to the LengthValidator function in the code, allowing forms to be submitted. Our DBA also had to update the instance’s Mautic database doctrine and schema, after making a backup, to resolve an unrelated issue with leads not being able to be deleted from the Contacts or Form Results list in the dashboard.
How to Apply a Mautic Patch
So as you can see above, there are clearly benefits to knowing how to apply a GitHub patch to your Mautic instance. Here are the steps you should follow, after taking a snapshot of your Mautic instance with your cloud provider and/or downloading the files in the Mautic directory and exporting the MySQL database to a safe place.
First, identify the pull request corresponding to the patch you wish to apply to your instance. This can be done by searching through the GitHub issues with your specific error message, and reading through the comments. Make sure the patch applies to your version of Mautic.
If git is not yet installed on your system, install it using the applicable package manager for your distribution. RHEL or CentOS users use yum install git and Ubuntu or Debian users use apt install git.
Once you’ve found the pull request by number, substitute it into the commands below where #### appears. This commands should be run from your Mautic directory, such as /var/www/html. If your web server does not run as user “apache”, substitute the correct Unix user following sudo -u.
The last part is very important because if you screw up the permissions on Mautic’s files and folders, you will encounter even more problems with your Mautic instance. Most tutorials we have seen online how to apply a patch do not address this.
sudo curl -L https://github.com/mautic/mautic/pull/####.diff | sudo -u apache git apply -v
Next, clear the Mautic cache by running this command, also from the Mautic directory.
sudo -u apache php app/console cache:clear
If successful, please consider commenting on the GitHub issue to share your findings with the developers so they know which fixes can be merged into an upcoming Mautic version to resolve the problem for all users. That’s the spirit of open source and it’s a neighborly thing to do.
How to Unapply a Mautic Patch
Suppose something has gone wrong after applying a Mautic patch, or it simply didn’t fix the problem you were trying to resolve. Luckily, the git command provides the capability to roll back the patch by undoing the diffs described in the patch file downloaded from Github.
sudo curl -L https://github.com/mautic/mautic/pull/####.diff | sudo -u apache git apply -R -v
Finally, clear the Mautic cache again to flush any changes made against your instance.
sudo -u apache php app/console cache:clear
When to Call In a Professional
If you can’t narrow down which GitHub issue and pull request applies to the Mautic bug you’re experiencing, or are not particularly savvy with the command line, our server engineering team is available to begin investigating your problem and provide professional support. We can clone your Mautic instance to a staging server, troubleshoot against the test instance, then communicate to you the findings and whether we recommend applying any patches.
Note that any patches applied via the git method will only apply until you upgrade to the next Mautic version, when the upgrade script will overwrite any core files with the master versions distributed by the Mautic Foundation. Generally any show-stopping bugs will be fixed by the next version anyways so this is rarely a concern, but we recommend having one of our server admins handle your next Mautic upgrade for peace of mind.
1 Comment.
Thanks a Ton, much needed information.