Hooks Viewer

See every event hook Matomo dispatches, in which order and with which arguments, to find the right hook when you build a Matomo plugin.

Never install this plugin on a production instance. It is a development tool: it shows internal hook arguments (configuration values, visitor data, request parameters) and writes a log file on every request. HooksViewer stays idle unless Matomo runs in development mode.

Features

• Every event, discovered automatically: the plugin scans core/ and plugins/ for Piwik::postEvent() call sites and subscribes to every hook it finds, including the hooks of third-party plugins. The list is cached in tmp/cache/hooksviewer-catalog.php and rebuilt when the source tree changes.
• Inline panel, for super users: every HTML response gets a collapsible HooksViewer panel with the hooks fired while it was built, in order. Full pages show it at the top, each widget and AJAX HTML fragment shows its own. Open a hook to read a pretty-printed, multi-line dump of its arguments.
• Log file at tmp/logs/hooksviewer.log: every hook of every request, including API calls, tracker hits and console commands, with a timestamp, a request id and the arguments. Rotated above 10 MB.
• Safe for Matomo responses: the panel is written once the response is complete, and only into HTML responses, never inside a <script> block. API calls, exports, images, redirects and tracker hits stay byte-exact. Use the log file to observe their hooks.
• Theme-aware: the panel and the argument dumps follow the light or dark Matomo theme.

The search field and the hook catalog page are only available in HooksViewer 6.x, for Matomo 6.

Requirements

• Matomo 5.0.0 or higher (>=5.0.0,<6.0.0-b1)

For Matomo 6, use HooksViewer 6.x.

Installation / Configuration

1. Install the plugin from the Matomo Marketplace (Administration > Marketplace), on a development instance only, and activate it.
2. Enable the Matomo development mode with ./console development:enable (or enabled = 1 in the [Development] section of config/config.ini.php). Without it, the plugin captures nothing and warns super users on every page.
3. Browse the page or trigger the workflow you care about, then expand the HooksViewer panel, or run tail -f tmp/logs/hooksviewer.log.
4. Deactivate the plugin when you are done.

Sensitive values (tokens, passwords, secrets, cookies, sessions, API keys, visitor identifiers and IPs) are masked in the panel and in the log file. To show them, add this to config/config.ini.php:

[HooksViewer]
show_sensitive_values = 1

Privacy and data

• The panel is only visible to super users, but the log file records the hooks of every request, including those of other users, with their arguments.
• Nothing is captured or logged unless Matomo runs in development mode. Outside development mode, and when the plugin is deactivated or uninstalled, the log files are deleted.
• Sensitive values are masked by default, see above.
• Nothing is sent outside your server.
• The log file and the catalog cache stay in Matomo's tmp/ directory. The log file is rotated to hooksviewer.log.1 above 10 MB.

Need help with Matomo?

Openmost is an official Matomo Implementation Partner. If you would rather hand over the build, we develop custom Matomo plugins from a written spec, tested on the Matomo versions you run, published on the Marketplace or delivered privately.

• Inline panel with hook arguments

  

HooksViewer is a development tool that subscribes to every Matomo event and surfaces them while you are browsing the Matomo UI or exercising the API.

Two outputs

Inline panel: for super users, HTML pages and widget AJAX requests (format=html) get a collapsible HooksViewer panel listing every event fired while the response was built, in order. Open a hook to see a clean, indented dump of its arguments.

Log file: tmp/logs/hooksviewer.log receives one line per fired event from every request, including JSON API calls, tracker hits, and CLI commands. Each line carries a timestamp, a short request id so you can correlate concurrent requests, an event index, the hook name, and a compact view of the args.

tail -f tmp/logs/hooksviewer.log

The log is rotated to hooksviewer.log.1 once it grows above 10 MB.

Where the hook list comes from

The plugin does not ship a hand-maintained list. On the first request after activation it scans core/ and plugins/ for every Piwik::postEvent('…') call site, resolves same-file constant references, and persists the result to tmp/cache/hooksviewer-catalog.php. The cache is invalidated whenever the source tree changes, so new events introduced by a Matomo upgrade or by a third-party plugin appear automatically.

Wildcard event names (those containing PHP variables or sprintf placeholders, e.g. Controller.$module.$action) are skipped because they cannot be subscribed to as a single static name.

Response safety

Some Matomo responses cannot tolerate any extra bytes:

• module=API (JSON / XML / CSV / TSV / RSS)
• matomo.php and piwik.php (tracker hits and image responses)
• CLI commands

For these, HooksViewer does not inject anything into the response. Use the log file (tmp/logs/hooksviewer.log) to observe their hooks.

For HTML pages and widget AJAX (format=html), the panel is written once the response is complete, right after the opening <body> tag (or at the top of a fragment), never inside a <script> block, and is styled to follow the light or dark Matomo theme.

Useful references

• Event guide: https://developer.matomo.org/guides/events
• Core event reference: https://developer.matomo.org/api-reference/events

Development mode and masked values

HooksViewer only runs when Matomo is in development mode (./console development:enable, or enabled = 1 in the [Development] section of config/config.ini.php). Outside development mode it captures and logs nothing, deletes its log files, and super users see a warning on every page asking to enable development mode or to uninstall the plugin.

Tokens, passwords, secrets, cookies, sessions, API keys, visitor identifiers and IPs are masked in the panel and in the log file, including inside URLs. To see them on a development instance:

[HooksViewer]
show_sensitive_values = 1

Reminder

This plugin exposes internal arguments (including configuration values and visitor data) and writes a log file on every request while development mode is on. Never install it on a production instance.

How do I install the plugin?

It is published on the official Matomo Marketplace, like any other plugin:

• Open the administration panel.
• Go to Marketplace.
• Search for HooksViewer, install it, then activate it.

Which Matomo versions are supported?

HooksViewer 5.x runs on Matomo 5.0.0 or higher. For Matomo 6, use HooksViewer 6.x, which adds a search field in the panel and a hook catalog page.

Why "never install in production"?

The plugin renders internal hook arguments into the page (database configuration, visitor IPs, request parameters, etc.) and writes a log file on every request. Both are useful while debugging and unacceptable in production.

The plugin is activated but shows nothing.

HooksViewer only works when Matomo runs in development mode. Enable it with ./console development:enable, or set enabled = 1 in the [Development] section of config/config.ini.php. Until then, no hook is captured or logged, and super users see a warning on every page. On a production instance, uninstall the plugin instead.

Why are some values shown as *** (masked)?

Tokens, passwords, secrets, cookies, sessions, API keys, visitor identifiers and IPs are masked in the panel and in the log file, also when they appear as URL parameters. To see them on your development instance, add show_sensitive_values = 1 to a [HooksViewer] section of config/config.ini.php.

Where do I see the hooks?

Two places, at the same time:

1. In the HooksViewer panel, for super users: a collapsible panel at the top of each HTML page, and at the top of each widget AJAX fragment (format=html), listing the hooks fired while it was built, in order, each one with its arguments.
2. In the log file at tmp/logs/hooksviewer.log. This catches every hook from every request, including JSON API calls, tracker hits, and CLI commands, where the plugin cannot safely inject markup. Tail it with tail -f tmp/logs/hooksviewer.log.

I activated the plugin but my CSS still looks unstyled.

Matomo caches the merged stylesheet bundle on disk. The plugin clears that cache on activation. If you somehow get out of sync, deactivate the plugin and reactivate it: the next request will rebuild the bundle.

How does the plugin keep up with new Matomo events?

The list of subscribed hooks is not hand-maintained. The plugin scans core/ and plugins/ for Piwik::postEvent('…') calls and caches the discovered list under tmp/cache/. The cache is rebuilt whenever the source tree changes, so new events appear automatically the next time the cache is invalidated.

Does the plugin break Matomo's API or tracker?

No. The panel is written once the response is complete, and only into HTML responses (regular pages and widget AJAX with format=html), never inside a <script> block. API JSON, CSV exports, XML, image responses, and tracker hits are left untouched. Use the log file to observe hooks fired during those requests.

Some hooks I expected to see are missing.

A few things to check:

• Is the event a wildcard (e.g. Controller.$module.$action)? Those are skipped because they have no fixed name to subscribe to.
• Did the event fire at all on this request? Check tmp/logs/hooksviewer.log: if it's not there either, the code path was not reached.
• Was the hook fired during a JSON API call? The panel is intentionally disabled for those; check the log file.

Is the plugin active for everyone in my Matomo instance?

The panel is only shown to super users. The log file, however, records the hooks of every request from every user while the plugin is activated. Deactivate it as soon as you are done debugging.

Will the log file fill my disk?

No. It is rotated to hooksviewer.log.1 once it grows above 10 MB, so at most about 20 MB are kept.

How can I contribute?

Open an issue or a pull request on https://github.com/openmost/HooksViewer.

How long will it be maintained?

As long as I keep using Matomo across projects, which is the foreseeable future. I'm the first user of this plugin: if it breaks on a Matomo upgrade I'll see it before you do.