UPDATE: View more recent Matomo (Piwik) Platform Changelog updates here.
This blog post is aimed at developers of Matomo Plugins. If you are simply using Matomo and not developing plugins for Matomo, you do not need to read this post.
Matomo 2.1 will be released in a few days . This blog post will inform Matomo Plugin developers of the changes in Matomo 2.1 that may require that you update your plugin to work with this latest version.
Breaking API changes
Matomo can now handle an unlimited number of users having Super User access (#2589 #4564). In the past Matomo was limited to one Super User who was defined in the config file. From now on all users with Super User access are defined in the database the same way a regular user is. This brought some API changes but we will stay backward compatible until the first of April 2014. This gives you some time to migrate any custom plugins you may use. Although there is a layer for backward compatibility we recommend to make sure your plugin works with Matomo as soon as possible before April 1st.
List of changes
Deprecated methods
The following methods are deprecated and we recommend to use the new methods from now on. There are also some methods which won’t be replaced so make sure to adjust the logic of your plugin.
\Piwik\Piwik::isUserIsSuperUser => \Piwik\Piwik::hasUserSuperUserAccess
\Piwik\Piwik::setUserIsSuperUser => \Piwik\Piwik::setUserHasSuperUserAccess
\Piwik\Piwik::checkUserIsSuperUser => \Piwik\Piwik::checkUserHasSuperUserAccess
\Piwik\Access::isSuperUser => \Piwik\Access::hasSuperUserAccess
\Piwik\Access::checkUserIsSuperUser => \Piwik\Access::checkUserHasSuperUserAccess
\Piwik\Access::setSuperUser => \Piwik\Access::setSuperUserAccess
\FakeAccess::checkUserIsSuperUser => FakeAccess::checkUserHasSuperUserAccess
\FakeAccess::setSuperUser => FakeAccess::setSuperUserAccess
\Piwik\Piwik::isUserIsSuperUserOrTheUser => \Piwik\Piwik::hasUserSuperUserAccessOrIsTheUser
\Piwik\Piwik::checkUserIsSuperUserOrTheUser => \Piwik\Piwik::checkUserHasSuperUserAccessOrIsTheUser
\FakeAccess::getSuperUserLogin => No replacement
\Piwik\Piwik::getSuperUserLogin => No replacement, returns the userLogin of the first Super User we find in the database
\Piwik\Piwik::getSuperUserEmail => No replacement, returns an empty string from now on
\Piwik\Access::getSuperUserLogin => No replacement, returns the userLogin of the first Super User we find in the database
Config Super User
As mentioned, the Super User was defined in the config and you have accessed the Super User’s data either by using a convenient method like Piwik::getSuperUserLogin or directly via the Config object as follows:
\Piwik\Config::getInstance->superUserAs the config user is no longer defined in the config this will no longer work in the future. To stay backward compatible we return the first super user found in the database. This is not necessarily always the same user. So if you have used the super user login in some way in your plugin, make sure you are using the new function such as Piwik::getSuperUserLogin
Extended Auth Interface
The last change affects plugins who specify their own Authentication mechanism, for instance when using the custom LoginLDAP plugin. From now on the interface \Piwik\Auth (https://github.com/piwik/piwik/blob/master/core/Auth.php) requires the methods setTokenAuth and setLogin. There is no backward compatibility layer but we had a look at some plugins defining a custom Authentication adapter to make sure those methods are already defined there as expected.
For another example of a Login plugin, check out the LoginHttpAuth plugin on the Marketplace.
After updating the plugin
After you have made changes in your plugin to keep it compatible with Matomo 2.1, your plugin will no longer work with previous Matomo versions. Therefore you should define the minimum required version in your plugin.json file as follows:
"require": {
"piwik": ">=2.1"
}Summary
Matomo 2.1 introduces some changes in the Matomo Core APIs. This blog post explains how to modify any Plugins compatible with Matomo 2.0 to be compatible with Matomo 2.1. Thank you for taking the time to update your plugins!
Let us know if you have any feedback. Happy hacking!
PS: if you use the Web Analytics APIs and the Web Tracking APIs, we guarantee that we will support backwards compatibility of our Web APIs.
