Update Plugins for Mautic 5

以下是大多数插件从 Mautic 4 升级到 Mautic 5 可能需要执行的步骤。您应该能够完成每个步骤，提交更改，然后继续下一个步骤。完成所有步骤后，您的插件就已成功升级。

持续集成

如果您尚未配置持续集成 (CI)，现在是配置的最佳时机。这不是一个强制步骤，但最好在早期而不是晚期进行配置。以下是如何配置 CI： /plugins/continuous-integration.

在您的拉取请求 (PR) 中，还应添加对 PHP 8.1 和 8.2 的支持，并将 Mautic 版本从 4.4 升级到 5.1。此外，Mautic 5 将 local.php 文件放在 config/local.php 而不是 app/config/local.php 中，因此也需要更新该文件。

自动注入

Mautic 5 具有 PHP 服务自动注入功能，这意味着开发体验得到了显著改善，并且代码大小减少了。

已经有一篇很好的文档介绍了此主题： Autowiring - 请参考该文档以获取说明。

为了快速验证服务是否已正确配置和连接，您可以使用以下命令，这比刷新浏览器窗口更快：

rm -rf var/cache && bin/console

Note

理想情况下，您应该能够从 config.php 文件中删除整个 services 部分，但这应该在您确信一切正常后再进行，因为此过程中的后续步骤可能会给您带来问题。

config.php - 控制器

当所有服务通过自动注入配置完成后，config.php 文件将变得更加简洁。还有一件事需要验证：控制器现在使用不同的语法定义。以下是一个示例：

- 'controller' => 'CronfigBundle:Cronfig:index',
+ 'controller' => 'MauticPlugin\CronfigBundle\Controller\CronfigController::indexAction'

Symfony 5 的定义更加明确。这很好，即使它更长。您不必猜测语法是什么。它基本上只是标准的完全限定类名 (FQCN)，后面是两个冒号表示的方法名称。您甚至不再需要将控制器方法命名为 *Action。

渲染视图

由于 Symfony 5 删除了 PHP 模板引擎，因此 Mautic 需要切换到 Twig。您的插件也必须将所有视图从 PHP 更新为 Twig。以下是一个有用的资源，介绍了如何将 *.html.php 文件迁移到 *.html.twig 文件：

Upgrading PHP to Twig templates

在控制器中，您还需要更新视图路径，例如：

- $this->renderView('MauticCoreBundle:Notification:flash_messages.html.php');
+ $this->renderView('@MauticCore/Notification/flash_messages.html.twig');

运行以下命令比在浏览器中刷新所有视图更快。它验证 Twig 语法，并可指导您完成此过程：

bin/console lint:twig plugins/MyBundle

Note

将 MyBundle 更新为您的 bundle 名称。

集成类

如果您删除了 config.php 中的所有服务，您可能会在使用 Mautic 的集成类和接口时遇到问题。 IntegrationsBundle 的内部机制期望您的集成具有特定格式的服务键。 Mautic 6 旨在改进这一点，但目前，请在 services.php 中添加一个别名：

$services->alias('mautic.integration.[MY_INTEGRATION]', \MauticPlugin\[MY_INTEGRATION]Bundle\Integration\[MY_INTEGRATION]Integration::class);

Note

将 [MY_INTEGRATION] 替换为您的插件名称。

编译器传递

如果您的插件使用编译器传递，您可能需要验证其是否正常工作。在许多情况下，您可能需要更改服务别名以使用完全限定的类名 (FQCN)，如下所示：

- ->setDecoratedService('mautic.form.type.email', 'mautic.form.type.email.inner');
+ ->setDecoratedService(EmailType::class, 'mautic.form.type.email.inner')

在测试中获取容器

这是一个简单的查找和替换：

- $handlerStack = self::$container->get('mautic.http.client.mock_handler');
+ $handlerStack = static::getContainer()->get(MockHandler::class);

请注意，您也可以使用 FQCN 代替字符串服务键，这更方便。

自动化重构

您的插件现在应该可以在 Mautic 5 上运行了。如果能稍微缩短一些代码该有多好？ Mautic 5 使用 PHP 8.0+，因此可以利用其语法。 Rector 可以为您升级代码。

运行 bin/rector process plugins/MyBundle 并审查更改。

Note

将 MyBundle 更新为您的 bundle 名称。

自动化代码风格

提高插件代码库质量的另一种好方法是运行 CS Fixer：bin/php-cs-fixer fix plugins/MyBundle.

Note

将 MyBundle 更新为您的 bundle 名称。

静态分析

PHPSTAN 是另一个很棒的工具，可以帮助您检测错误。最好在整个代码库上运行它，包括 Mautic 的核心部分，以便它可以了解所有类。

运行 composer phpstan

如果您的插件有太多 PHPSTAN 错误而无法立即解决，请考虑使用 PHPSTAN baseline。它允许您将技术债务存储到单个文件中，并强制您从现在开始编写更好的代码。您可以每月逐步减少基线，最终达到 0。

结论

此步骤列表由 Mautic 插件开发人员为 Mautic 插件开发人员准备。如果您发现某些常见问题未在此处解决，请添加它。