This blog post is aimed at developers of Piwik Plugins. If you are simply using Piwik and not developing plugins for Piwik, you do not need to read this post.

Piwik 2.1 will be released in a few days . This blog post will inform Piwik Plugin developers of the changes in Piwik 2.1 that may require that you update your plugin to work with this latest version.

Breaking API changes

Piwik can now handle an unlimited number of users having Super User access (#2589 #4564). In the past Piwik 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 Piwik 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->superUser

As 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 Piwik 2.1, your plugin will no longer work with previous Piwik versions. Therefore you should define the minimum required version in your plugin.json file as follows:

"require": {
 "piwik": ">=2.1" 
}

Summary

Piwik 2.1 introduces some changes in the Piwik Core APIs. This blog post explains how to modify any Plugins compatible with Piwik 2.0 to be compatible with Piwik 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.


Piwik Core Team

Piwik is liberating web analytics by offering an open platform with built-in privacy. Piwik is used on more than 1 million websites worldwide and is translated in 53 languages. The Marketplace enables the community to create innovation in the world of web analytics. Roadmap - Get involved.