This plugin helps you generate a tracking code for Matomo, and displays some useful metrics directly within the panel.
This plugin is completely free and published under the MIT license. However, if you are using it in a commercial project and want to help me keep up with maintenance, please consider making a donation of your choice or purchasing your license(s) through my affiliate link.
- 1. Why Matomo?
- 2. Installation
- 3. Options
- 4. Template usage
- 5. Panel dashboard
- 6. Panel page widget
- 7. License
- 8. Credits
TLDR – Just get me started
- Install Matomo on your server.
- Download and copy this repository to
- Set the following values in
return array( 'sylvainjule.matomo.url' => 'http://your-matomo.url', 'sylvainjule.matomo.id' => 'mywebsite', 'sylvainjule.matomo.token' => 'token_auth', );
- Add this code to your footer snippet:
<?php echo snippet('matomo') ?>
- Copy this blueprint under a dedicated tab / page in the panel.
You're all set.
1. Why Matomo?
- It's open-source (who doesn't like open-source?)
- It's free (like, really free. You don't pay with your data)
- It's self-hosted (which means more control for you over your data)
- It respects your visitors privacy (IP Anonymization, automated logs deletion, data ownership)
- It now integrates smoothly with Kirby 3
Download and copy this repository to
Alternatively, you can install it with composer:
composer require sylvainjule/matomo
Here is an overview of the available options with their default values:
return array( 'sylvainjule.matomo.url' => false, #required 'sylvainjule.matomo.id' => false, #required 'sylvainjule.matomo.token' => false, #required for the panel integration 'sylvainjule.matomo.active' => true, 'sylvainjule.matomo.debug' => false, 'sylvainjule.matomo.trackUsers' => false, 'sylvainjule.matomo.disableCookies' => false, 'sylvainjule.matomo.blacklist' => ['127.0.0.1', '::1'], );
Where your matomo install is:
'sylvainjule.matomo.url' => 'https://analytics.yourdomain.com'
A single Matomo install can host multiple websites. The plugin needs to know the
id of the one to look for:
'sylvainjule.matomo.id' => 'mywebsite'
token (required for the panel integration)
The panel sections will need to make calls to your Matomo API. A
token_auth is required, you will find it in
Settings > API in the control panel. Copy-paste the string without the
Below is an example token. Please note that this token is private and shouldn't be made public. Once added, if you need to publish your code please create something like a duplicated
config.github.phpwhich will contain the non-sensitive informations, and add your real
'sylvainjule.matomo.token' => 'gQ7TQgg8EFe3h29F9t4aJqC33VQdPfFP4M'
You can deactivate the snippet by setting this value to
'sylvainjule.matomo.active' => true
Localhost is in the blacklist as default. You can change it.
'sylvainjule.matomo.blacklist' => ['127.0.0.1', '::1']
The script is only active for not logged in users by default. If you want to change it, set this option to
'sylvainjule.matomo.trackUsers' => false
If you want to always run the script (even on localhost or if you are logged in), set this option to
'sylvainjule.matomo.debug' => false
If you want to use Matomo without any tracking cookies on the user side, set this option to
true. You can read more about this setting in the Matomo FAQ.
'sylvainjule.matomo.disableCookies' => false
4. Template usage
You only need to include the snippet in your code somewhere:
<?php snippet('matomo'); ?>
5. Panel dashboard
The panel dashboard (screenshot on top of this readme) displays metrics for the whole website.
5.1. Basic blueprint example
Please make sure that you have included your
token_authin your config.
Place this snippet in a dedicated tab / blueprint:
columns: - width: 3/4 sections: main: type: matomo-main - width: 1/4 sections: sidebar: type: matomo-sidebar
There are a bunch of options to help you adjust this default panel view. Both sections have three components :
- The mainview (
- The sidebar (
You can chose to hide them like this:
columns: - width: 3/4 sections: main: type: matomo-main chart: false overview: false widgets: false - width: 1/4 sections: sidebar: type: matomo-sidebar link: false realtime: false summary: false
(Ok, there would be nothing left to work with here, but you get the idea).
Hiding and sorting widgets
Widgets can be sorted to your taste. You can also choose to display only some of them. Here's a glimpse of the option with all widgets explicitely set, change the order of its list or remove entries to filter widgets.
columns: - width: 3/4 sections: main: type: matomo-main widgets: - referrerType - websites - socials - devicesType - keywords - popularPages
Hiding period ranges
By default, all 4 ranges are displayed (This year, This month, Last 7 days, Today).
You can choose to hide some of them by explicitely excluding them from the
columns: - width: 3/4 sections: main: type: matomo-main periods: - year - month - week - day
You have acces to two default options, the
period and the widgets
periodis the default active period on first load of the section. It is a string to chose from one of the periods above. Default is
limitis the number of entries displayed within the widgets. Default is
columns: - width: 3/4 sections: main: type: matomo-main defaults: period: month limit: 5
5.3. Complete blueprint example
Here's a glimpse of how the blueprint might look with all options explicitely set:
columns: - width: 3/4 sections: main: type: matomo-main chart: true overview: true defaults: period: month limit: 5 periods: - year - month - week - day widgets: - referrerType - websites - socials - devicesType - keywords - popularPages - width: 1/4 sections: sidebar: type: matomo-sidebar link: true realtime: true summary: true
6. Panel page widget
The panel page widget displays metrics for a given page, both in single-language or multi-language websites.
Any feedback regarding this widget's behaviour is welcome. It might still need to be refined, inputs from a larger variety of live websites would be a great help. Check the potential pitfalls below.
6.1. Basic blueprint example
Please make sure that you have included your
token_authin your config.
Place this snippet in your page blueprint:
columns: - width: 1/3 sections: matomo: type: matomo-page
The section will automatically detect the page uri, and fetch its metrics for the given period.
You can choose the period displayed, which can either be
day. Default is
matomo: type: matomo-page period: month
The plugin will automatically detect if multi-language is switched on, and fetch the metrics of the current language.
Optionally, you can also display the metrics of all languages combined with the
overview option. Default is
matomo: type: matomo-page overview: false
6.3. Potential pitfalls
- Matomo receives public urls, which means that its URIs are fetched once routes have been applied. Therefore, the plugin filters Matomo's responses with a uri created from the public url of the page. If you have set up custom routes, to skip subfolders for example, please make sure to overwrite the
urlmethod for the template with a page model, otherwise the uri won't be correct.
- The metrics shown might not be accurate / complete if you have changed the default language after Matomo started its data collection.
Kirby 2 had some Piwik integration plugins:
- kirby-piwik by @schnti
- kirby-analytics by @l4ci
- kirby-piwik-widget by @mauricerenck
- A promising Piwik Suite that sadly has never been released, and was an inspiration to get started on a comprehensive and thorough plugin.