This migration guide covers the changes required in order to make a plugin compatible with Matomo 5. A list of all changes in Matomo 5 can be found in the Changelog.
We recommend creating a new branch for your plugin that supports Matomo 5. For example 5.x-dev
. This way you will be able to make changes to your plugin for Matomo 4 and Matomo 5 and release independent versions for each of them. You can still publish updates to your plugin that supports Matomo 4 once you have published an update for a version that supports Matomo 5.
For your plugin to be executed in Matomo 5 you first need to show it is compatible with Matomo 5 in your plugin.json
file:
"matomo": ">=4.0.0-b1,<5.0.0-b1"
).4.1.9
to 5.0.0
.The plugin.json
would look like this:
"version": "5.0.0",
"require": {
"matomo": ">=5.0.0-b1,<6.0.0-b1"
},
It's not allowed to support multiple major Matomo versions such as Matomo 4 and Matomo 5: "matomo": ">=4.0.0-b1,<6.0.0-b1"
. In this case you would receive an error email and the release would not be published.
The minimum PHP version that Matomo is still compatible with is PHP 7.2.5, so there aren't any changes needed in terms of e.g. removed PHP functions. However, with PHP 8.1 and 8.2 being available already, you may need to check that your plugin doesn't throw warnings or deprecation notices in those newer PHP versions.
Matomo 5 completes the migration from AngularJS to the VueJS 3 framework. If your plugin contains templates which make use of AngularJS components or directives then these will need to be recreated in VueJS and the templates adjusted.
A new VueJS component can be created for your plugin using the console command:
./console generate:vue-component --pluginname=MYPLUGIN --component=NEWCOMPONENT
This will create an example component in plugins/MYPLUGIN/vue/src/NEWCOMPONENT.vue
which shows the basic component structure and can be used as a starting point to build a new component.
Because Matomo uses TypeScript within its VueJS components, the *.vue
files will be compiled and stored in /plugins/MYPLUGIN/vue/dist
before they can be used. This can be achieved using the following console command:
./console vue:build MYPLUGIN
This will build all vue components for your plugin and must be run before testing any VueJS change. The --watch
option for this command can be used to constantly monitor any VueJS changes for your plugin and automatically compile them.
With Matomo 5 we have introduced vendor proxy patterns. Plugins should no longer directly use any dependencies that are shipped with Matomo. We have introduced a set of classes and methods that can be used instead.
This step will allow us to easily update and replace vendor libraries without the requirement to do a major release for it as plugins will be fully encapsulated and separated from our dependencies. If your plugin needs direct access to a certain dependency, consider creating a GitHub issue for adding a proxy pattern for it, or bundle your own prefixed version of the dependency with your plugin. For example, if you wanted to use a version of the sparkline library or yaml parser in your plugin, you could either create an issue to have them proxied in Matomo or you could use PhpScoper to prefix the libraries directly in your plugin.
The following part will explain how to replace the usage of certain vendor libraries with our proxies:
In config.php
files and in methods like provideContainerConfig
in tests it is possible to define dependency configurations. Those configurations were previously done by directly using functions of the PHPDI library. We have introduced our own class providing static methods with the same functionality that need to be used instead. In addition you can no longer use \Psr\Container\ContainerInterface
or \DI\Container
as type hints as Matomo is now using its own container class \Piwik\Container\Container
.
DI
namespaced functions need to be replaced with static \Piwik\DI
methods.
\DI\add()
will become \Piwik\DI::add()
\DI\string()
will become \Piwik\DI::string()
\Piwik\Exception\DI\DependencyException
or \Piwik\Exception\DI\NotFoundException
\Piwik\Container\Container
where you used to use \Psr\Container\ContainerInterface
or \DI\Container
as typehintsWe used to use \Monolog\Logger
or \Psr\Log\LoggerInterface
to access our logging interface through dependency injection.
\Piwik\Log\Logger
instead of \Monolog\Logger
\Piwik\Log\LoggerInterface
instead of \Psr\Log\LoggerInterface
\Piwik\Log\NullLogger
instead of \Psr\Log\NullLogger
To access our logging interface you can e.g. use
$logger = \Piwik\Container\StaticContainer::get(\Piwik\Log\Logger::class);
Or when injecting the logger into e.g. an API constructor using dependency injection you can use
public function __construct(\Piwik\Log\LoggerInterface $logger)
{
$this->logger = $logger;
Our console commands were using parts of the Symfony Console library directly. Command classes will no longer be allowed to extend any Symfony components directly, instead we have rewritten our base class for commands \Piwik\Plugins\ConsoleCommand
. This class will now give you access to console functionalities directly. To update your plugin command you need to apply the following changes:
run
, execute
, interact
or initialize
can no longer be overwritten. Instead, use our custom methods prefixed with do
: doExecute
, doInteract
or doInitialize
doExecute()
method needs to return integers. We recommend using the class constants SUCCESS
or FAILURE
as return values.$this->getInput()
or $this->getOutput
instead. Don't use InputInterface
or OutputInterface
as method typehints.addOption
and addArgument
can no longer be used
addOptionalArgument
or addRequiredArgument
addNegatableOption
, addOptionalValueOption
, addNoValueOption
or addRequiredValueOption
askForConfirmation
, askAndValidate
or ask
initProgressBar
, startProgressBar
, advanceProgressBar
and finishProgressBar
renderTable
runCommand
We used to use Travis CI for testing. With Matomo 5 we discontinued support for running tests on Travis CI, instead we now use GitHub actions for this. You can find more details on how to set up your own GitHub test action in this guide.
jQuery has been updated to 3.6.3. Please check your plugin's JavaScript code if it needs to be adjusted. More details can be found in jQuery update guides: https://jquery.com/upgrade-guide/3.0/ and https://jquery.com/upgrade-guide/3.5/
Plugin names are now limited to 60 characters. If your plugin name is longer than 60 characters then you will need to rename it.
piwikPageChange
, which is triggered when a reporting page is loaded, has been renamed to matomoPageChange
. Ensure to update your plugin if you rely on it.Common::fixLbrace()
function has been removed. It was only necessary for AngularJS and no longer needs to be used.In this guide we have seen which steps to take to migrate your Matomo plugin to be compatible with our latest Matomo 5. If you need further help with converting your plugin to Matomo 5, head over to the Matomo developers community forums.
Once you've adjusted your plugin, don't forget to release a new version!