开发

从Piwik 2迁移插件。X到Matomo 3 (Piwik 3)

2.从Matomo(以前的Piwik)迁移插件X到Matomo 3 (Matomo 3)

这个迁移指南解释了如何做一些迁移，使一个插件与Matomo 3兼容。Matomo 3中所有更改的列表可以在更新日志．

使您的插件与Matomo 3兼容

当你在Matomo 3上测试你的Matomo插件后，有一些可能的情况:

  • 你的插件同时适用于Matomo 2和Matomo 3，
  • 或者:你的插件不适合Matomo 3，
  • 或者:你的插件只适用于Matomo 3。

如果你的插件兼容Matomo 2和Matomo 3…

如果你有一个兼容Matomo 2和Matomo 3的插件，我们建议在你的插件中明确地指定这一点plugin.json因为我们假设你的插件只与Matomo 2兼容。在plugin.json，改变这个:

"require": {"piwik": ">=2.16.0"}，

:

"require": {"piwik": ">=2.16.0，<4.0.0-b1"}，

如果你的插件还不兼容Matomo 3…

如果你的插件与Matomo 3还不兼容，我们建议为你当前的插件发布一个新的版本，并明确告诉市场该插件与Matomo 3不兼容。的plugin.json看起来是这样的:

"require": {"piwik": ">=2.16.0，<3.0.0-b1"}，

下一步是让你的插件与Matomo 3兼容:本指南将帮助你定位要对插件进行的更改。

一旦你的插件与Matomo 3兼容，发布一个新的主版本的插件

一旦你的插件与Matomo 3兼容:

  • 指定你的插件需要Matomo 3。
  • 我们也建议增加插件的主版本号，例如from1.2.3来2.0.0．

的plugin.json看起来是这样的:

“版本”:“2.0.0”,“要求”:{“piwik”:“> = 3.0.0-b1 < 4.0.0-b1 "},

仍然可以发布与Matomo 2兼容的分支更新。

市场

插件的更新日志

在过去，更改日志通常定义在README.md通过指定# #的更新日志标题。现在已经弃用了，我们建议将更改日志保存在更新日志，CHANGELOG.txt或CHANGELOG.md文件代替。

插件的常见问题解答

这同样适用于FAQ，它过去是定义在# #常见问题解答类中指定的文档/ faq.md文件。

插件的支持选项

在自述文件中也不再管理支持选项卡。相反，插件页面上的支持选项卡现在是从"support"部分在你的plugin.json中．

插件的许可证

市场现在还支持显示许可证文本，如果许可证，LICENSE.txt或LICENSE.md在插件的根目录中指定，并且可以通过指定文档/ index.md文件。

事件

如果你的插件正在监听事件，你应该重命名这个方法getListHooksRegistered来registerEvents

更新和SQL模式迁移

如果你的插件像这样定义SQL更新:

公共函数getMigrationQueries(Updater $ Updater){返回数组(//忽略现有列名错误(1060)' alter table '。Common::prefixTable('custom_dimensions')。"ADD COLUMN case_sensitive TINYINT UNSIGNED NOT NULL DEFAULT 1 AFTER extraction " => 1060，);}公共函数doUpdate(Updater $ Updater) {$ Updater ->executeMigrationQueries(__FILE__， $this->getMigrationQueries($ Updater));｝

你应该把它们转换成:

使用Piwik\Updater\Migration\Factory作为MigrationFactory;/** * @var MigrationFactory */ private $migration;公共函数__construct(MigrationFactory $factory) {$this->migration = $factory;}公共函数getMigrations(Updater $ Updater){返回数组($this->migration->db->addColumn('custom_dimensions'， 'case_sensitive'， 'INYINT UNSIGNED NOT NULL DEFAULT 1'， 'extractions'));}公共函数doUpdate(Updater $ Updater) {$ Updater -> executemig(__FILE__， $this->getMigrations($ Updater));｝

了解更多关于新的数据库更新API的信息。

插件设置

  • 系统设置和用户设置曾经定义在一个PluginSettings类。我们把它分成了两个新的类，为了转换现有的插件设置，我们建议首先为不同的类型生成新的设置，例如
$ ./console generate:settings——settingstype=系统$ ./console generate:settings——settingstype=用户

然后是时候转换每个设置了:

$this->autoRefresh =新的用户设置('autoRefresh'， '自动刷新');$this->autoRefresh->type = static::TYPE_BOOL;$this->autoRefresh->uiControlType = static::CONTROL_CHECKBOX;$this->autoRefresh->description = '如果启用，该值将根据指定的间隔自动刷新';$this->autoRefresh->defaultValue = false;$ this - > addSetting ($ this - > autoRefresh);

:

$defaultValue = false;$phpType = FieldConfig::TYPE_BOOL;$this->autoRefresh = $this-> makessetting ('autoRefresh'， $defaultValue， $phpType, function (FieldConfig $field) {$field->title = '自动刷新';$field->uiControl = FieldConfig::UI_CONTROL_CHECKBOX;$field->description = '如果启用，该值将根据指定的时间间隔自动刷新';})；

正如你所看到的，API并没有太大的变化。了解更多关于新的插件设置API的信息。

报告

如果你的插件创建了一个自定义报告，则应重命名该属性美元的类别来美元被标记．(在代码中，替换$ this - >类别通过$ this - >被标记）.

如果您已经定义了一个小部件，或者您已经将报表添加到报表页面，那么您需要遵循以下步骤:

创建小部件

在过去这是可能的创建一个小部件是这样的:

$this->widgetTitle = 'Live_RealTimeVisitorCount';$this->widgetParameters = array();

现在一个小部件是在一个单独的方法中配置的，就像这样:

公共函数configureWidgets(WidgetsList $ WidgetsList, reporttwidgetfactory $factory) {$widget = $factory->createWidget();widgetsList - > addWidgetConfig(小部件);｝

这样做的好处是，您现在可以为一个报表创建许多小部件，并通过调用其中的一个来以您想要的任何方式更改小部件ReportWidgetConfig的方法。

在报表菜单中显示页面

在过去，你所需要做的就是定义menuTitle美元财产。这有点复杂。首先，您需要定义一个小部件，如前一步所述。然后你需要移除menuTitle美元属性并添加新属性subcategoryId美元．子类别是应将报表添加到的页面的名称。这允许您向任何现有的报表页面添加任何报表，或者通过定义尚未被任何其他页面使用的新subcategoryId来创建新的报表页面。

在Reports指南中了解更多关于新API的信息。．

小部件

所有插件的小部件过去都是在一个类中定义的。这种简单的体系结构有一些缺点，比如即使只执行了一个小部件，也需要对所有小部件进行依赖(依赖项列表有时相当长)。有时在一个类中创建了许多不同的小部件，这并不是真正的干净。现在每个小部件都在自己的文件中定义，并且可以以多种方式进行配置。

我们建议首先通过控制台创建一个新的Widget:

$ ./控制台生成:小部件

下一步，是时候迁移这个旧的Matomo 2小部件结构了:

protected $category = ' exampleecompany ';protected function init() {$this->addWidget('我的小部件名称'，$method = 'myExampleWidget');}公共函数myExampleWidget(){返回'Hello world!';｝

到这样定义的新结构:

类MyExampleWidget扩展Widget{公共静态函数配置(WidgetConfig $config) {$config->setCategoryId(' exampleecompany ');$config->setName('我的小部件名称');配置- > setOrder (99);}公共函数render(){返回'Hello world!';}}

正如您可能看到的，渲染小部件的方法现在总是被调用渲染它曾经是创建小部件时指定的名称。配置现在是在静态配置方法中完成的，该方法允许您配置类别、名称、小部件的顺序等。在Widgets指南中了解更多关于新API的信息。．

用户菜单

用户菜单已被删除，现在应该在Admin菜单中定义此类链接。要做到这一点，在你的Menu.php插件文件，从方法中移动代码configureUserMenu (MenuUser菜单美元)对于方法configureAdminMenu (MenuAdmin菜单美元)．

接下来你应该更新相关的Twig模板文件(如果有的话)并替换{%扩展'用户。嫩枝' %}与{%扩展'admin。嫩枝' %}．

总结

在本指南中，我们已经了解了迁移您的Matomo插件以与我们最新的Matomo 3兼容的步骤。如果您需要将插件转换为Matomo 3的进一步帮助，请前往Matomo开发者社区论坛．

Baidu