ContextQMD
Back to Mautic

User facing changes

UPGRADE-5.0.md

7.1.114.0 KB
Original Source

User facing changes

Mailer

The underlying library used for sending emails (Swift Mailer) was discontinued and Mautic 5 is using the Symfony Mailer library instead. There are user facing changes coming with this change.

  1. All the email transports were removed from Mautic's core and must be re-created as separate plugins.
  2. The good news is that Mautic now supports email transports created for Symfony Mailer.
  3. SMTP transport is the only transport supported by Mautic after fresh installation.
  4. The "Email Step" was removed from the installation wizzard because the transports were removed. The email transport must be configurad right after Mautic installation.
  5. The email transport configuration has changed from various fields unique for each transport to unified "DSN". Any transport can be configured using the same form. There is a migration that should handle most of the email transport configuration from Mautic 4 and re-configure it for Mautic 5.
  6. The command bin/console mautic:emails:send for sending emails via cron jobs was removed and now Symfony Messenger is used instead. Use this command to start a consumer: bin/console messenger:consume email. The Messenger in the async configuration can work with various queues.

Backwards compatibility breaking changes

  • Platform Requirements
    • Minimal PHP version was increased from 7.4 to 8.0 and 8.1.
  • Configuration
    • Replace all occurances of %kernel.root_dir% to %kernel.project_dir%/app as the "root_dir" was deprecated in Symfony 4 and removed in Symfony 5. The "project_dir" variable is path to the Mautic root directory. The "root_dir" variable was path to the app directory.
    • The index_dev.php was removed. Use env variables to set the environment.
    • We are following symfony env naming convention. Symfony 4.4
      • .env contains default values for the environment variables needed by the app
      • .env.local uncommitted file with local overrides
      • .env.$APP_ENV committed environment-specific defaults
      • .env.$APP_ENV.local uncommitted environment-specific overrides
    • The system run similar index_dev.php if you use APP_ENV=dev and APP_DEBUG=1 in your .env.local file.
    • Remove Custom shortener API URL from configuration (link_shortener_url variable) and remove Mautic\CoreBundle\Helper\UrlHelper::buildShortUrl() method. As a developer, use the \Mautic\CoreBundle\Shortener\Shortener::class service.
    • the application config (/app/config) was separated from local config (/config) to make Mautic more compatible with a Composer based workflows.
      There is a Doctrine migration that moves the local config files to the new directory.
  • Installation
    • The email step was removed from both GUI and CLI installers.
    • The installation is considered completed once db_driver and site_url parameters are set. It used to be db_driver and mailer_from_name.
  • Mailer
    • The Swiftmailer library was replaced with SymfonyMailer. Details in https://github.com/mautic/mautic/pull/11613
    • There is only one callback route for all transports now. Changed from /mailer/{transport}/callback to /mailer/callback.
    • Mautic\EmailBundle\Mailer\Exception\UnsupportedTransportException was removed. Use EmailEvents::ON_TRANSPORT_WEBHOOK instead.
    • Mautic\EmailBundle\Mailer\Transport\CallbackTransportInterface was removed. Use EmailEvents::ON_TRANSPORT_WEBHOOK instead.
    • Mautic\EmailBundle\Event\TransportWebhookEvent does not have the transport in it. Each transport must validate the callback payload and decide if they are able to process it or not. If so, set the Response to the event to indicate success.
    • Swift_Message was replaced with Mautic\EmailBundle\Mailer\Message\MauticMessage.
    • Swift_Transport was replaced with Symfony\Component\Mailer\Transport\TransportInterface.
    • The following classes were removed without any replacement:
      • Mautic\EmailBundle\Exception\PartialEmailSendFailure
      • Mautic\EmailBundle\Helper\PlainTextMessageHelper
      • Mautic\EmailBundle\Model\TransportType
      • Mautic\EmailBundle\DependencyInjection\Compiler\SpoolTransportPass
      • Mautic\EmailBundle\DependencyInjection\Compiler\EmailTransportPass
      • Mautic\EmailBundle\DependencyInjection\Compiler\SwiftmailerDynamicMailerPass
    • All configuration keys connected with the email transports (starting with mailer_) were replaced with the single configuration key mailer_dsn.
    • All classes the resided in the app/bundles/EmailBundle/SwiftMailer were removed.
    • Spooling was removed in favour of the queuing functionality provided by the Symfony messenger.
  • Commands
    • The command bin/console mautic:segments:update will no longer update the campaign members but only the segment members. Use also command bin/console mautic:campaigns:update to update the campaign members if you haven't already. Both commands are recommended from Mautic 1.
    • Command Mautic\LeadBundle\Command\CheckQueryBuildersCommand and the methods it use:
      • Mautic\LeadBundle\Model\ListModel::getVersionNew()
      • Mautic\LeadBundle\Model\ListModel::getVersionOld()
    • mautic:broadcast:send --limit=10 --batch=2 fix process emails with combination of parameters limit/batch. Before it processed all emails with batch 10. Now process 10 emails with batch 2. If you used to use before, probably you need change it.
  • Services
    • Repository service mautic.user.token.repository for Mautic\UserBundle\Entity\UserTokenRepository was removed as it was duplicated. Use mautic.user.repository.user_token instead.
    • In tests replace self::$container->get('mautic.http.client.mock_handler') with self::$container->get(\GuzzleHttp\Handler\MockHandler::class) to get HTTP client mock handler.
  • JS Dependencies
  • Other
    • Mautic\UserBundle\Security\Firewall\AuthenticationListener::class no longer implements the deprecated Symfony\Component\Security\Http\Firewall\ListenerInterface and was made final. The public function handle(GetResponseEvent $event) method was changed to public function __invoke(RequestEvent $event): void to support Symfony 5.
    • Mautic\IntegrationsBundle\Configuration\PluginConfiguration removed - we don't use it
    • Mautic\SmsBundle\Callback\ResponseInterface removed - we don't use it
    • Mautic\CoreBundle\Controller\AbstractModalFormController removed - we don't use it
    • Mautic\CoreBundle\Templating\Helper\ExceptionHelper removed - we don't use it
    • Mautic\LeadBundle\Model\LeadModel::getContactFromRequest() method removed. Use Mautic\LeadBundle\Helper\ContactRequestHelper::getContactFromQuery() instead.
    • Mautic\LeadBundle\Model\LeadModel::mergeLeads() method removed. Use \Mautic\LeadBundle\Deduplicate\ContactMerger::merge() directly.
    • Mautic\LeadBundle\Model\LeadModel::checkForDuplicateContact() method do not take Lead as a second parameter anymore and so it do not merges contacts. Use \Mautic\LeadBundle\Deduplicate\ContactMerger::merge() afterwards.
    • Class Mautic\LeadBundle\Model\LegacyLeadModel removed. Use \Mautic\LeadBundle\Deduplicate\ContactMerger instead.
    • Method Mautic\ReportBundle\Event\ReportGeneratorEvent::applyTagFilter() removed. Use Mautic\ReportBundle\Builder\MauticReportBuilder::getTagCondition() instead.
    • Class Mautic\CoreBundle\Form\DataTransformer\EmojiToShortTransformer was removed. Details
    • Mautic\CoreBundle\Doctrine\AbstractMauticMigration::entityManager protected property was removed as unused.
    • The User entity no longer implements Symfony\Component\Security\Core\User\AdvancedUserInterface as it was removed from Symfony 5. These methods required by the interface were also removed:
      • Mautic\UserBundle\Entity\User::isAccountNonExpired()
      • Mautic\UserBundle\Entity\User::isAccountNonLocked()
      • Mautic\UserBundle\Entity\User::isCredentialsNonExpired()
      • Mautic\UserBundle\Entity\User::isEnabled()
    • Two French regions were updates based on ISO_3166-2 (Val-d'Oise, La Réunion). If you use it in API, please change values to Val d'Oise or Réunion
    • AbstractMauticTestCase::loadFixtures and AbstractMauticTestCase::loadFixtureFiles now accept only two arguments: array $fixtures and bool $append. If you need to use old parameters - refer to the documentation of LiipTestFixturesBundle
    • Transactional emails in campaigns ignore the DNC setting.
    • There are no unsubscribe headers in transactional emails.
    • The SortablePanels templates, JS and CSS was removed as unused.
    • Country name of Swaziland was update to Eswatini based on Standard: ISO 3166.
    • Region names in Austria, Germany and Switzerland were updated based on Standard: ISO_3166-2.
    • Mautic\CoreBundle\Controller\CommonController::addFlash() was renamed to CommonController::addFlashMessage()to prevent naming collision with Symfony\Bundle\FrameworkBundle\Controller\AbstractController::addFlash(). Controllers adding flash messages should use $this->addFlashMessage().
    • Deprecated cookie mtc_sid removed.
    • The dev dependency php-http/mock-client was removed as abandoned and unused. See https://github.com/mautic/mautic/pull/12439
    • 'mautic.guzzle.client' service was removed. Use 'mautic.http.client' instead.
    • Removed onlyForBC themes: coffee, Mauve, nature
    • Replaced asset minification library mrclay/minify with matthiasmullie/minify for faster asset generation.

QueueBundle removed in favor symfony's messenger, see: readme

  • Related configuration is no longer valid.
  • Events removed without replacement: QueueEvents, Event\QueueConsumerEvent, Event\QueueEvent
  • QueueService removed without replacement
  • Helper removed app/bundles/QueueBundle/Helper/QueueRequestHelper.php in favor of serialization (reused)
  • Command mautic:queue:process is no longer available, use messenger:consume instead

Dependency injection improvements

Mautic 5 adds support for Symfony's autowiring and autoconfigure for services.

Advantages:

  • New services no longer need to have any definition in the app/bundles/*Bundle/Config/config.php. Symfony will guess what services are needed in the services by types of arguments in the constructor.
  • Services that aren't used in other services as dependencies like subscribers, commands and form types were deleted completely.
  • Existing service definitions can be reduced to setting just the string alias to keep backward compatibility and controllers working.
  • app/config/services.php is automatically configuring all bundles including plugins so if the bundle doesn't do anything uncommon then it should work out of the box.
  • The legacy services definitions in *Bundle/Config/config.php file are still working but will be removed in Mautic 6.

Possible backward compatibility breaks:

  • If your plugin does break it may be using some value objects out of common places. Get inspiration in existing plugins/*Bundle/Config/services.php to exclude the folders or files from autowiring.
  • Some services might need to be configured. For example if they need a config parameter in the constructor. Follow the official Symfony docs to configure such services.
  • Start converting your controllers to support DI over loading services from container as that is an anti-pattern that Symfony no longer supports. That is the reason why all the services are set as public so the old controllers can still work. This will change throughout the life of Mautic 5 and will be removed in Mautic 6. See https://symfony.com/doc/current/controller/service.html