=== Admin Views Column for Matomo ===
Contributors: pushaune
Tags: matomo, analytics, admin columns, post views, statistics
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.2.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.

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 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.

= 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 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**.

= 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.

== Changelog ==

= 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.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.
