=== Comments Analytics – Dashboard & Commenter Profiles ===
Contributors: slaFFik
Tags: comments, analytics, comment-dashboard, commenter-profiles, comment-insights
Requires at least: 6.5
Tested up to: 6.9
Stable tag: 1.3.1
Requires PHP: 7.4
License: GNU General Public License v2.0 or later

Analyze WordPress comments in one dashboard. Track comment stats, identify top commenters, and gain engagement insights.

== Description ==

**CommentsWP** transforms your WordPress comments section into a powerful analytics and insights hub.
Instead of just collecting comments, it helps moderators and site owners **analyze engagement**, **track trends**, and **discover their most active commenters** — all in one beautiful dashboard.

### 💡 Why Use CommentsWP

CommentsWP aggregates data already stored in your WordPress database and presents it in clear, actionable widgets and tables.
You'll gain a new understanding of how your readers engage and how comment activity evolves over time.

**Key benefits:**
- Instantly see comment statistics and engagement patterns
- Identify your top commenters and active discussions
- Detect anomalies and potential manual spam attempts
- Compare posts with and without comments
- Analyze response speed and comment types
- Get meaningful, visual insights without complex setup

### 🧭 Dashboard Overview

#### Comments Card Widgets

Quickly access aggregated data from your WordPress comments database.
Each card displays a specific metric:

* 4 default comment statuses: **Approved, Pending, Spam, Trashed**
* **Average Time To First Comment** (e.g., 1m 3d 8h 35min 18s)
* **Fastest Time To First Comment** (e.g., 1d 20h 38min 53s)
* **Posts with vs. without comments** (totals and percentages)
* **Logged-in vs. Guest comments** (totals and percentages)
* **Top-level vs. Threaded replies** (totals and percentages)
* **Pingbacks and Trackbacks** (totals and percentages)

Each card links to detailed documentation on the [CommentsWP website](https://commentswp.com/docs/).

### 📊 Table Widgets

Not all useful data fits into a single number. That's why CommentsWP also provides **data table widgets**.

#### Total by User
See how many comments were left by your most prolific commenters.
Group users by **email** or **IP address** to spot patterns:
- Same person using different names or IPs
- Different people using the same email

#### Anomalies Table
Identify "manual spammers" or hyper-active users who leave large volumes of comments, possibly using multiple emails or IP addresses.

#### Total by Time Period
Track how comment activity changes over time — by **year, month, week, or day**.
Quickly detect engagement trends across your site's history.

### 👥 Commenter Profiles

The **Profiles** page lists all comment authors along with:
- Total number of comments
- Date of first and last comment
- Known names and aliases

This feature gives you a clear view of your active audience.
Future versions will include more behavioral insights and interaction data.

### ⚙️ How CommentsWP Works

CommentsWP runs all analytics **server-side** and **caches results** automatically.
Complex SQL queries are executed only when new comments are added, updated, or deleted — ensuring **fast performance** and **minimal load** on your database.

Data is calculated and displayed **only** in the WordPress admin area, on the **Comments → Dashboard** page.
It does **not** affect your site's frontend or your visitors' browsing experience.

### 🔐 Access Control

Only logged-in users with the `moderate_comments` capability can access the CommentsWP Dashboard.
By default, this includes **Administrators** and **Editors**.

### 🌍 Translation & Compatibility

CommentsWP is **translation-ready** and uses the `commentswp` text domain.
It works seamlessly with **Loco Translate**, **WPML**, and most caching or performance plugins.

### 🧠 How To Use CommentsWP

1. Install and activate the plugin.
2. Navigate to **Comments → Dashboard** in your WordPress admin.
3. Review your analytics cards for quick insights.
4. Explore the **Profiles** page to learn more about your commenters.
5. Use the **comment type filter** (comments, pingbacks, trackbacks) to refine your view.
6. Visit the [documentation](https://commentswp.com/docs/) for detailed explanations of each card.

### 🧩 Troubleshooting

**Dashboard shows old data**
→ The plugin caches results. Add or update a comment to refresh all stats automatically.

**Performance concerns on large sites**
→ CommentsWP runs heavy queries only when cache refreshes, not on every page load.

**No data in tables**
→ Ensure your site has approved comments. Some widgets only display data for approved entries.

**Can I export this data?**
→ Not yet, but export tools will be implemented in future versions if enough users request them.

== Frequently Asked Questions ==

### Is the data cached?
Yes. CommentsWP caches its aggregated data, updating automatically when new comments are **Added**, deleted, or modified.

### Does it affect frontend performance?
No. All calculations occur only inside the WordPress admin dashboard.

### Who can see the dashboard?
Users with the `moderate_comments` capability (Administrators and Editors by default).

### Can I filter analytics by comment type?
Yes. You can filter dashboard cards by type — comments, pingbacks, trackbacks, etc.

### Does it work with multisite installations?
Yes. Make sure to activate the plugin on each of your subsites.

### Can I customize which cards appear on the dashboard?
Future versions will allow custom card visibility and arrangement.

### How accurate are the time metrics?
Times are calculated down to the second using precise WordPress timestamps and sophisticated SQL queries.

### Is it translation-ready?
Yes, fully translation-ready. Compatible with Loco Translate and WPML.

### Does it collect or send data externally?
No. All processing happens locally in your WordPress database.

### How do I clear the cache manually?
You can simply trigger a new comment or delete one; the cache clears automatically.

== Screenshots ==

1. CommentsWP Dashboard.
1. CommentsWP Profiles.

== Installation ==

**Install through your backend**:

1. Search for "commentswp" on the "Add Plugins" page.
1. Click the "Install Now" button, and then - "Activate".

**Install manually**:

1. Download and unzip the plugin.
1. Upload the `commentswp` directory to the `/wp-content/plugins/` directory.
1. Activate the plugin through the 'Plugins' menu in WordPress.

**Next**:

Now you can open your CommentsWP Dashboard by doing one of these actions:

1. click on the "Comments" top level menu item in your wp-admin sidebar navigation
1. use the "Dashboard" link under the plugin name in the list of Plugins

== Changelog ==

### 1.3.1
- **Fixed**: Do not enforce type to strings that are coming from WordPress filters to avoid fatal errors.
- **Fixed**: Adjust the styling of WordPress notices that have the ".updated" class (in addition to currently supported ".notice").

### 1.3.0
- **IMPORTANT**: This version requires WordPress 6.5 or higher.
- **Added**: The "Total by Time Period" card now has a new "Group by Day" option.
- **Added**: The "Total by Time Period" card now has a "Newest First" and "Oldest First" option. It affects the order of time periods displayed in the card.
- **Changed**: Visual refresh of the plugin admin area.
- **Changed**: The plugin supports the latest WordPress 6.9.
- **Fixed**: The plugin was generating the PHP notice "Function _load_textdomain_just_in_time was called incorrectly" on the front-end in cases when an AJAX request was sent to `wp-admin/admin-ajax.php` by any other 3rd-party plugin.
- **Fixed**: Improve the performance of the Dashboard cards a bit by preventing double population.
- **Fixed**: Improve the performance of AJAX requests for all 3rd-party plugins by preventing CommentsWP from loading its Dashboard cards on each AJAX request.
- **Fixed**: The comment type dropdown on the Dashboard page was empty in case there was no data in the comments table.
- **Fixed**: Removed unused functions which are leftovers from development.
- **Fixed**: A lot of PHP code style improvements.

### 1.2.0
- **IMPORTANT**: This version requires PHP 7.4 or higher and WordPress 6.4 or higher.
- **Added**: Now you can filter the dashboard cards by comment type: Comments, Pingbacks, Trackbacks, etc.
- **Added**: New Profiles page that lists the commenter authors with their total number of comments, last and first comment date, and also their known names.
- **Changed**: Much more intelligent caching logic: old internal cache is no longer hard-coded for a certain amount of time. Now it is being generated and lives until the new comment is being posted on a site, deleted, updated or changed its status.
- **Fixed**: Various performance improvements.
- **Fixed**: There was a PHP warning in the "Total by Time Period" card on Dashboard when there were no approved comments.

### 1.1.0
- **IMPORTANT**: This version requires PHP 7.2 or higher and WordPress 5.5 or higher.
- **Added**: Each Dashboard Card now has its own link to a dedicated documentation page with more information about the card.
- **Added**: Display the actual dates next to week numbers in the "Total by Time Period" card for improved readability.
- **Added**: All Comments Date range support: the "Total by Time Period" card when grouped by month or week now has links that filter comments on the "All Comments" page accordingly.
- **Fixed**: In certain screen sizes, the double cards labels were not fitting in the block and were overlapping with each other. Now ellipsis is displayed when the label is too long.

### 1.0.0
- **Initial release** containing 13 cards, 2 dashboard-wide filters, and a bunch of cards-specific filters.