As mentioned in the previous development updates #1 New UI design, API changes & release date, #2 Git master branch will become Matomo 3 and #3 Marketplace we are actively working on the Matomo 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 Matomo upgrades as easy as possible, we have usually avoided database schema changes that affect large tables during the Matomo 2.X release cycle. The Matomo 3 update will however require several database updates in order to fix some limitations and bugs in the Matomo database schema. If you have a fair amount of traffic and/or large Matomo database, we recommend to execute the database updates for Matomo 3 on the command line.
If you struggle updating Matomo you can also get in touch with the Matomo Support and ask for a quote so we can help you with upgrading.
New server & browser Requirements
Matomo 3 updates the server requirements. Matomo 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+).
Matomo 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.getUsersorGoals.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 Matomo Analytics (formerly 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 Matomo server is behind a proxy.
When Matomo 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 Matomo 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 Matomo JavaScript Tracker file piwik.js
From Matomo 3 we recommend to have the file /piwik.js writable in your Matomo directory, so that the PHP and webserver processes can edit this file. It is not required to have the file writable for Matomo 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 Matomo 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 Matomo 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 Matomo 3.
For a list of all changes have a look at the developer changelog.
Until our next Matomo 3 update, be well, and Happy Analytics!
