As mentioned in the previous development updates #1 New UI design, API changes & release date, #2 Git master branch will become Piwik 3 and #3 Marketplace we are actively working on the Piwik 3 update and we will release a first beta of it soon. While the update brings many new features and bugfixes, it also comes with some important changes that may require your attention which we detail in this blog post.

Database updates

To keep Piwik upgrades as easy as possible, we have usually avoided database schema changes that affect large tables during the Piwik 2.X release cycle. The Piwik 3 update will however require several database updates in order to fix some limitations and bugs in the Piwik database schema. If you have a fair amount of traffic and/or large Piwik database, we recommend to execute the database updates for Piwik 3 on the command line.

If you struggle updating Piwik you can also get in touch with the Piwik Support and ask for a quote so we can help you with upgrading.

New server & browser Requirements

Piwik 3 updates the server requirements. Piwik 3 now requires:

  • PHP 5.5.9 or newer (we used to require PHP 5.3+),
  • MySQL 5.5 or newer or MariaDB (we used to require MySQL 4.1+).

If you are still on an old PHP and MySQL version we highly recommend to update directly to PHP 7 and a recent MySQL version (MySQL 5.7+).

Piwik 3 also drops support for the older browsers IE8 and IE9.

Default filter_limit now applies to all HTTP API methods (#8458)

In the past the default filter_limit of 100 rows was applied to HTTP API methods that return a report. This means that by default:

  • when you requested a method like SitesManager.getAllSites, UsersManager.getUsers or Goals.getGoals (which are not reports), we returned all rows.
  • when you fetched a report like Actions.getPageUrls (which is a report), the result was limited to 100 rows.

This behaviour was inconsistent and it was hard to understand which methods apply the default limit and which did not. We now apply the default limit to all HTTP API methods by default.

If your API consumer or app needs to fetch all results for an API method, you can append the following parameter to the URL: &filter_limit=-1. Alternatively, if you wish to change the default filter_limit automatically for all APIs, you can override the API_datatable_default_limit config setting in your config/config.ini.php file.

For more information about the various APIs parameters you can use, see Piwik Analytics HTTP API Reference.

Proxy client IP detection (#10342)

This is only important if you are using the proxy_client_headers[] config in the config/config.ini.php file, ie. your Piwik server is behind a proxy.

When Piwik is set up to fetch the client IP address from the proxy headers, and the header contained more than one IP address, we used to use the last IP address. From Piwik 3 we will be using the first IP address which is in line with the protocol definition. For example if HTTP_X_FORWARDED_FOR contains multiple IP addresses, we now use the first IP instead of the last one.

Writable Piwik JavaScript Tracker file piwik.js

From Piwik 3 we recommend to have the file /piwik.js writable in your Piwik directory, so that the PHP and webserver processes can edit this file. It is not required to have the file writable for Piwik to function well, but we are working on some enhanced features that will only work when the file is writable. If you don’t know whether this file is writable, go to “Administration => System Check” as a Super User and Piwik will display a warning if the file is not writable. If needed, you might be able to make the file writable by executing a command like chmod 0755 piwik.js or chown $webuser piwik.js (on Linux).

Changes for plugin developers

In the previous development updates we have already introduced some of the changes that affect Piwik plugin developers. We have made several improvements to the Marketplace that allow developers to promote their plugin better and to maintain their plugin page easier. We have also created a migration guide for plugin developers to make it easier to migrate a plugin to Piwik 3.

For a list of all changes have a look at the developer changelog.

Until our next Piwik 3 update, be well, and Happy Analytics!


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 - Help & Support.


Any questions?

Many answers and more information about Piwik You can find here:

We are social

Follow us: