=== Admin Views Column for Matomo ===
Contributors: pushaune
Tags: matomo, analytics, admin columns, post views, statistics
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.4.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display Matomo page views in WordPress admin lists for posts, pages, and custom post types.

== Description ==

Admin Views Column for Matomo adds a **Matomo views** column to WordPress admin lists.

It helps you see how your content performs directly from the WordPress dashboard, without opening Matomo every time you want to check whether a post, page, or custom post type is being read.

The plugin can read statistics from two sources:

* The official **Matomo Analytics for WordPress** plugin installed on the same site.
* A **remote Matomo instance** (self-hosted or Matomo Cloud), using the Matomo Reporting API with a site ID and an auth token.

The plugin can display Matomo statistics for:

* Posts
* Pages
* Public custom post types visible in the WordPress admin

The views column is sortable, so you can quickly find your most viewed or least viewed content. The counts load in the background, so your admin lists stay fast even when the Matomo data is not cached yet, and each count links straight to the Matomo report for that exact page.

Every list has its own **period selector in the Screen Options panel**: posts, pages and each custom post type can report on a different period, and the choice is saved per user without changing anything for anyone else. The column header always names the period it reports on.

A **dashboard widget** lists your most viewed content for the selected period and remembers the period you picked, independently of the lists. A **Test connection** button in the settings instantly verifies your Matomo configuration and shows the exact error message when something is wrong.

You can also choose the reporting period:

* Today
* Yesterday
* Last 7 days
* Last 30 days
* Last 90 days
* Last 365 days
* Current year
* All time

The plugin supports two Matomo metrics:

* Page views (`nb_hits`)
* Unique views (`nb_visits`)

To avoid slowing down the WordPress admin, Matomo data is cached with WordPress transients. The cache duration can be changed from the plugin settings page.

The settings are organized in three tabs: **Matomo source**, **Settings**, and **301 redirects**.

If your permalinks changed over time, the plugin can keep the historical view counts: old slugs saved by WordPress are matched automatically, and 301 redirect rules can be declared in the settings — either by hand or by importing a CSV file.

= Requirements =

This plugin requires a working Matomo installation that is already tracking your website. Two setups are supported:

* **Local**: the official Matomo Analytics for WordPress plugin installed, active, and configured on the same site.
* **Remote**: a self-hosted Matomo or Matomo Cloud instance, reachable over HTTPS. You will need the site ID and a Matomo auth token (created in Matomo under Administration > Personal > Security > Auth tokens).

If Matomo is not collecting data, this plugin cannot display statistics.

= Privacy =

This plugin does not track visitors by itself.

It reads existing statistics from Matomo and displays them in the WordPress admin.

In local mode, no data is sent to an external service. In remote mode, the plugin sends API requests (including the configured auth token) to the Matomo server you configured — and to no other service. The token is sent in the request body (POST), so it does not appear in URLs.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **Settings > Matomo Columns**.
4. Choose the Matomo source: the local Matomo for WordPress plugin, or a remote Matomo instance (enter its URL, the site ID, and an auth token).
5. Choose the post types, reporting period, metric, and cache duration.

== Frequently Asked Questions ==

= Does this plugin replace Matomo? =

No. It only displays selected Matomo statistics inside WordPress admin lists. Matomo remains the analytics platform.

= Do I need the Matomo for WordPress plugin? =

Only in local mode. If your website is tracked by a self-hosted Matomo or Matomo Cloud, choose the remote source in **Settings > Matomo Columns** and enter the Matomo URL, site ID, and an auth token. In that case the Matomo for WordPress plugin is not needed.

= Where do I find the site ID and auth token for a remote Matomo? =

The site ID is listed in Matomo under **Administration > Websites > Manage**. Auth tokens are created under **Administration > Personal > Security > Auth tokens**. Create a dedicated token for this plugin.

= Does the plugin count views itself? =

No. It reads data from Matomo. It does not create a second view counter inside WordPress.

= Which Matomo metrics are supported? =

The plugin supports page views (`nb_hits`) and unique views (`nb_visits`).

= Can I use a different period for each list? =

Yes. Open the **Screen Options** panel at the top of any list and pick a period, then click **Apply**. Posts, pages and each custom post type keep their own period, and the setting belongs to your WordPress account: it does not change what other users see.

The period chosen in the plugin settings stays the default, used until you pick something else in a list. The dashboard widget keeps its own period as well.

= Where does a view count link to? =

To the Matomo **Pages** report, narrowed down to that single page with a segment on its URL — including the old URLs whose views are added to the count, so the report and the column agree.

If your Matomo instance does not process segments on the fly (a common setting on large installations), the report may take a moment to appear the first time, or show up empty until Matomo has processed the segment. That is a Matomo setting, not a plugin limitation.

Developers can change the target with the `admivico_report_url` filter, which receives the post ID and the segment.

= Can I sort posts by Matomo views? =

Yes. The Matomo views column is sortable.

When sorting by views, the plugin synchronizes a private post meta value for the displayed post type, then WordPress sorts the list using that numeric value. That value is rebuilt whenever it no longer matches the period of the list being sorted, so sorting stays correct when two users work with different periods.

= Does it work with custom post types? =

Yes. It works with custom post types that are visible in the WordPress admin.

= My permalinks changed (301 redirects). Do I lose the old view counts? =

No, but Matomo stores statistics per URL, so views recorded on the old URL are not automatically attributed to the new one.

The plugin handles this in two ways:

* When you rename a post slug, WordPress saves the old slug. The plugin automatically adds the views of the old URL to the current count (this can be disabled in the settings).
* For larger changes (permalink structure, domain migration), declare your 301 redirects in **Settings > Matomo Columns**: old structure on one side, new structure on the other, with `*` as a wildcard (for example `/blog/*` to `/*`). The views of the old URLs are then added to the current counts.
* Instead of typing the rules, you can import a CSV file with two columns (old URL, new URL). The file is read in your browser and the rules are added to the table for review before saving.

Developers can also provide additional historical URLs per post with the `admivico_url_candidates` filter.

= Why does the column show “…” for a moment? =

The Matomo statistics are fetched in the background the first time a list is displayed (or after the cache expires), so the page itself loads instantly. The counts appear as soon as Matomo responds — usually within a second or two.

= Why do I see zero views? =

The selected page may have no Matomo data for the chosen period, or Matomo may not be configured correctly.

You can also try clearing the plugin cache from **Settings > Matomo Columns**, and use the **Test connection** button in the Matomo source tab to check your configuration: it shows the exact error message returned by Matomo.

= How often are the statistics updated? =

By default, the cache lasts one hour. You can change the cache duration in the plugin settings.

You can also clear the cache manually from **Settings > Matomo Columns**.

== Screenshots ==

1. Matomo source tab: choose between the local Matomo for WordPress plugin and a remote Matomo instance (URL, site ID, auth token).
2. Settings tab: content types, reporting period, metric, cache duration, and cache clearing.
3. 301 redirects tab: declare old URL structures with wildcards, import rules from a CSV file, and include old slugs automatically.
4. The sortable Matomo Views column in the WordPress posts list.
5. The "Matomo — Top content" dashboard widget: most viewed content for the selected period, with a link to the full Matomo report.

== Changelog ==

= 1.4.0 =
* Add a period selector to the Screen Options panel of every content list: posts, pages and each custom post type can report on their own period, saved per user.
* Name the reported period in the views column header.
* Remember the period selected in the "Matomo — Top content" dashboard widget, independently of the period used by the lists.
* Link each view count to the Matomo report for that exact page (segmented on its URL, old URLs included) instead of the general Pages report. The counts in the dashboard widget are clickable too.
* Fix sorting by views serving another user's numbers when two users sorted the same list with different periods.

= 1.3.0 =
* Load the views column asynchronously: admin lists render immediately and the counts fill in as soon as Matomo responds.
* Add a Test connection button to the Matomo source tab, with the exact error message returned by Matomo when the configuration is wrong.
* Make the view counts link to the Actions > Pages report in Matomo (works with both the local Matomo for WordPress plugin and a remote instance). Developers can change the target with the `admivico_report_url` filter.
* Add a "Matomo — Top content" dashboard widget listing the most viewed content for the selected period.

= 1.2.1 =
* Redesign the settings screen: header with plugin icon and version badge, card-based tab panels, clickable cards for the Matomo source choice, and a restyled 301 redirect rules table.
* Show a confirmation notice after clearing the Matomo cache.
* Move all inline styles to a dedicated stylesheet (css/admin.css).
* Identical 301 redirect rules are now merged automatically when saving the settings (no more duplicate rows after importing a CSV file that contains existing rules).

= 1.2.0 =
* Organize the settings page in three tabs: Matomo source, Settings, and 301 redirects.
* Import 301 redirect rules from a CSV file (two columns: old URL, new URL), read in the browser and reviewed before saving.
* Load the translations bundled with the plugin, until wordpress.org language packs are available.
* Move the settings script to its own file (js/admin.js).

= 1.1.0 =
* Add support for remote Matomo instances (self-hosted or Matomo Cloud) via the Matomo Reporting API.
* Add Matomo source, remote URL, site ID, and auth token settings.
* The Matomo for WordPress plugin is no longer a hard requirement (still supported as the local source).
* Keep view counts across permalink changes: old slugs saved by WordPress are matched automatically, and 301 redirect rules can be declared in the settings.
* Add the `admivico_url_candidates` filter to provide additional historical URLs per post.

= 1.0.0 =
* Initial release.
* Add Matomo views column to posts, pages, and supported custom post types.
* Add sortable Matomo views column.
* Add reporting period selection.
* Add metric selection for page views and unique views.
* Add transient-based cache.
* Add cache clearing action.

== Upgrade Notice ==

= 1.4.0 =
Per-list reporting periods in the Screen Options panel, a dashboard widget that remembers its period, and view counts linking to the Matomo report of the page itself. No configuration change required.

= 1.3.0 =
Faster admin lists (asynchronous loading), Test connection button, clickable view counts and a new Top content dashboard widget.

= 1.2.1 =
Redesigned settings screen, and duplicate 301 redirect rules are now merged automatically when saving. No configuration change required.

= 1.2.0 =
Tabbed settings page and CSV import for 301 redirect rules. No configuration change required.

= 1.1.0 =
Adds support for remote Matomo instances (self-hosted or Matomo Cloud). Existing local setups keep working without any change.

= 1.0.0 =
Initial release.
