Add support for client IP address blocking and a blocking cookie

[OliverO2]

This pull request adds the following capabilities:

• Block Matomo tracking for configurable client IP addresses and/or IPv4/IPv6 address ranges.
• Block Matomo tracking via a blocking cookie.

These features already exist in the Google Analytics plugin for Grav (introduced via my pull request there) and have been in production use for quite some time.

Rationale

Why block client IP address ranges?

If your Matomo plugin is configured to send tracking events to a production Matomo server on the Internet, it will also send tracking events there when you use it with a Grav testing server on your local network. This is usually undesirable.

The following (default) setting disables tracking when a client connects to the server via local networks, while leaving it on for production installations:

blockedIpRanges: ["private", "loopback", "link-local"]

You may also specify your testing client address or your testing client's IPv4 or IPv6 address range in blockedIpAddresses or blockedIpRanges respectively.

Why use an additional blocking cookie?

Two reasons:

1. To allow users to opt out from PHP tracking. Unfortunately, Matomo's opt-out cookie works for JavaScript tracking only. It does not disable PHP tracking.

2. To test a production site without changing its configuration. The cookie can be used to exclude test clients from tracking, while leaving it enabled for everyone else.

How to set a blocking cookie?

Use this PHP script as is or adapt it to your needs: setGravMatomoTrackingPreferences.php

[NicoHood]

Hey Oliver, thanks for opening this Pull request.

Your ideas sound really good, I just got a few questions:

Currently I disable local/development tracking by using a dedicated config for localhost/development server. I simply disable the plugin or I use a different site config to track the hits on a different pool. I guess your solution is simpler, as it make no sense to track hits from localhost in most cases, was this the intention?

About the cookie: Currently you can honor the do not track setting of the browser. I understand that the cookie is just another option which is all good. But do we really need it? Just asking, cause you might not be aware of that setting.

[NicoHood]

I've got a question regarding this: https://github.com/escopecz/grav-ganalytics/pull/11/files#diff-37ce1af37fc02da4245eb958206ab395307b33f55b31256f202cc1631af6a972L86

I also stumbled across this. Can we use https also for matomo? Do you have any knowledge about that? Cause the usual tracking code of matomo use no https, I was wondering if it makes sense to add that here. I am always pro https!

[NicoHood]

I like the idea about adding an inline js blocking reason. Would you mind adding that as well? This looks like a good debugging idea to me. We could also use this here instead of throwing an exception. What do you think? https://github.com/NicoHood/grav-plugin-matomo/blob/develop/matomo.php#L109

[OliverO2]

Thanks for the quick reaction. Your questions are welcome, as to prevent bloat, a useful strategy is "no use case, so feature". ;-)

Considering the alternatives to a separate cookie:

1. Controlling tracking via the site configuration

   • This is an option I am using as well: A separate localhost configuration directs tracking to an internal Matomo test server. In this configuration I also change the default setting to:

     blockedIpRanges: []  # allow connections within the local network

   • However, I also like to do final tests on production sites with an unchanged configuration. That's where I use the cookie. (I use a version-controlled automated build and installation process for production sites, and I do not use Grav's Admin plugin, so it's important for me not to change anything once in production.)

2. Using "Do not track"

   • This affects all sites. If I want to be tracked by my internal Matomo test server but not by the production server, DNT does not help.
   • You have to remember to set it back. Now I just set the cookie once for production sites and then forget about it.
   • DNT is harder to manage (deeply buried in browser settings).

So in my view the extra cookie is necessary as the alternatives require extra manual intervention and increase the error potential.

Regarding the use of https: In the grav-ganalytics plugin, I simply added a previously missing https: scheme to the Google script link in that plugin's JS snippet. As far as I know, Matomo is already using https if possible (see getCurrentScheme() in vendor/matomo/matomo-php-tracker/MatomoTracker.php) so I'm not aware of any need to changes here.

I had thought about adding the blocking reason here as well. I initially decided against this to keep output clean, because with PHP-only tracking, no code will be injected into the page at all. In conjunction with a separate debug configuration setting we can have both.

I have addressed your suggestions in my recent commit.

[NicoHood]

I've tagged a new release. Thanks for your patch, corrections and time :-)

[OliverO2]

Thanks for your reviews and your quick integration!