Try: Fediverse Wrapped statistics feature by pfefferle · Pull Request #2633 · Automattic/wordpress-activitypub

pfefferle · 2025-12-15T15:27:33Z

Fixes #2597

Proposed changes:

Implements Fediverse statistics dashboard widget using React/TypeScript
Statistics class for collecting engagement metrics (likes, reposts, comments)
REST API endpoint for fetching statistics data
Dashboard widget showing:
- Stat highlights (followers, posts, likes, reposts) with year-over-year comparison
- Interactive line chart for monthly engagement
- Chart legend showing engagement types
- Top supporter section
- Top posts section
Support for stored monthly stats (for historical data)
CLI command for populating demo data (local dev only)

Removed from original scope:

Shareable HTML wrapped card (will be a separate block later)
Annual email template

Other information:

Have you written new tests for your changes, if applicable?

Testing instructions:

Setup demo data (optional):

npx wp-env run cli wp activitypub stats populate

Dashboard Widget:

Go to WordPress Dashboard (/wp-admin/)
Look for "Fediverse Stats" widget
If multiple actors enabled, use the selector to switch between user/blog stats
Verify:
- Stat highlights show followers, posts, likes, reposts counts
- Line chart displays monthly engagement data
- Legend shows engagement types with colors
- Top supporter section (if data exists)
- Top posts section (if data exists)

Clear demo data:

npx wp-env run cli wp activitypub stats clear

Changelog entry

Automatically create a changelog entry from the details below.

Changelog Entry Details

Significance

Patch
Minor
Major

Type

Added - for new features
Changed - for changes in existing functionality
Deprecated - for soon-to-be removed features
Removed - for now removed features
Fixed - for any bug fixes
Security - in case of vulnerabilities

Message

Add Fediverse statistics dashboard widget with engagement metrics and charts.

Implements monthly/annual statistics collection and display: - Core Statistics class for collecting engagement metrics - Scheduler for monthly stats collection and annual compilation - Dashboard widget showing stats with charts - Annual email template for year-end summaries - Shareable wrapped card for public sharing Known issues: - URL rewrite rules for wrapped card need debugging (year parameter not captured) - Stats display shows 0 values on HTTP requests despite correct query var registration Related to #2597

Eliminated the Fediverse Wrapped shareable card functionality by deleting the template, removing related rewrite rules, query vars, and rendering logic from Statistics, and cleaning up associated JavaScript and dashboard UI elements.

- Replace jQuery-based widget with React components - Add REST API endpoint for statistics data - Add TypeScript types for stats data structures - Add chart legend showing engagement types - Support stored monthly stats for demo/historical data - Add CLI command for populating demo data (local dev only)

- Make StatHighlights display engagement types dynamically from API - Add period label "This month vs. last year" to clarify comparison - Draw individual lines for each engagement type in the chart - Use WordPress default color palette CSS variables with fallbacks - Remove hardcoded comment types - all types now dynamic - Move demo data generation from Statistics class to local CLI

obenland

Keeping it to structure, I'd see if there are stats we can bump as they occur instead of aggregating monthly. I reckon that'll probably be more accurate, especially for things we can't or are hard to query after the fact.

One of the reasons Jetpack is so powerful is because it can store large amounts of data, process them remotely, and aggregate them. It might be worth considering making this a jetpack integration instead of hoping an option is enough?

The dashboard widget is neat, is there something we can do to make that a bit more interactive?

includes/wp-admin/class-statistics-dashboard.php

includes/scheduler/class-statistics.php

pfefferle · 2025-12-18T07:50:43Z

@obenland thanks for your feedback! 🫶

pfefferle · 2025-12-18T07:54:04Z

One of the reasons Jetpack is so powerful is because it can store large amounts of data, process them remotely, and aggregate them. It might be worth considering making this a jetpack integration instead of hoping an option is enough?

I somehow agree, that we might be able to have a collab, but you checked the number of folks that have both installed an that is quite low. So I would love to have at least a basic stats feature in the plugin, to maybe motivate users to interact a bit more!?

- Move cron schedule methods (add_cron_schedules, register_schedules, deregister_schedules) from Scheduler\Statistics to main Scheduler - Move helper methods (get_next_first_of_month, get_next_january_first) to main Scheduler - Update dashboard stats widget to get actors on JS side like the reader - Use @wordpress/core-data to check actor mode and capabilities - Remove PHP-passed actors from Statistics_Dashboard

@obenland

Resolved conflicts: - includes/class-migration.php: Added both emoji migration and stats backfill callbacks - includes/class-scheduler.php: Combined SCHEDULES constant loop with stats scheduling Additional changes based on PR feedback: - Changed annual stats notification from January 1st to December 1st (per @obenland) - Fixed CSS linting issues in dashboard-stats stylesheet

@obenland

- Changed compile_and_send_annual_stats to get current year instead of previous year (since it now runs December 1st, not January 1st) - Updated docblock to reflect the December timing - Added TODO for shareable landing page feature (per @obenland feedback)

- Use WordPress admin color palette (#2c3338, #646970, #f6f7f7, etc.) - Add dashicons for stat types (followers, posts, likes, reposts, comments) - Match padding and spacing from #dashboard_right_now widget - Use border-top separators instead of background color blocks - Style top supporter section like WordPress admin notices - Style top posts section like activity widget list items - Add responsive breakpoint for mobile

- Make chart container full width with background extending to edges - Better align icons with text using flex-start and margin adjustments - Simplify stat-content to inline display for natural text flow

Change all section headlines from h4 to h3 for proper heading hierarchy. Move the "Engagement Over Time" title outside the grey background area by applying the background only to the chart container.

Change "This month vs. last year" from p to h3 for consistent heading hierarchy across all widget sections.

Match WordPress admin dashboard CSS patterns: - Centralize h3 styles (14px, font-weight 400) - Use WordPress admin color palette (#50575e, #82878c) - Match padding patterns from #dashboard_right_now - Simplify section styling for cleaner appearance

- Use float layout for stat items (matches #dashboard_right_now li) - Icon styling exactly matches WordPress: font, padding, display, vertical-align - Activity block pattern for sections with negative margins - Exact padding values from WordPress dashboard CSS - h3 margins match #dashboard-widgets h3 pattern

- Current month stats are now always queried live to include recent engagement (likes, reposts, comments) - Backfill migration now skips the current month since it's in progress - Previous months use stored stats for performance - Add delete_monthly_stats() and recollect_monthly_stats() methods - Add force option to trigger_monthly_collection() scheduler method This fixes an issue where new reposts wouldn't show in stats because the current month data was being served from cached options.

Expose the scheduler's trigger_monthly_collection() and trigger_annual_compilation() methods via the local development CLI: - stats collect: Trigger monthly stats collection - stats compile: Trigger annual stats compilation Options include --year, --month, --force, and --no-email for flexibility.

- Remove get_yearly_monthly_breakdown() (replaced by get_rolling_monthly_breakdown) - Remove deprecated get_year_comparison() (use get_period_comparison instead)

- Remove trigger_monthly_collection() from scheduler - Remove trigger_annual_compilation() from scheduler - Remove delete_monthly_stats() and recollect_monthly_stats() from Statistics - Implement collect and compile logic directly in local CLI class

The queries were defaulting to only 'post' type, missing engagement on pages and custom post types enabled for ActivityPub. Now uses activitypub_support_post_types option in all queries: - count_engagement_in_range() - get_top_posts() - get_top_multiplicator() - get_earliest_data_year()

Copilot

Pull request overview

This PR implements a "Fediverse Wrapped" statistics feature for the ActivityPub plugin, providing users with engagement analytics similar to Spotify Wrapped. The feature includes a React-based dashboard widget displaying follower growth, post metrics, and engagement statistics with month-over-month comparisons and trend visualization.

Changes:

Adds comprehensive statistics collection and storage system with monthly/annual aggregation
Implements REST API endpoint for fetching statistics data with permission checks
Creates interactive React dashboard widget with stat highlights, line charts, top posts, and top supporter sections
Adds WP-CLI commands for demo data population and statistics management
Includes scheduled jobs for automatic monthly statistics collection and annual compilation
Provides email notification system for annual "wrapped" summary

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 21 comments.

Show a summary per file

File	Description
includes/class-statistics.php	Core statistics collection class with methods for aggregating engagement metrics, follower counts, and top content
includes/rest/class-statistics-controller.php	REST API controller providing authenticated endpoint for retrieving statistics data
includes/wp-admin/class-statistics-dashboard.php	Dashboard widget registration and asset enqueuing for the statistics display
includes/scheduler/class-statistics.php	Scheduled task handlers for monthly/annual statistics collection and email notifications
includes/class-scheduler.php	Cron schedule registration for monthly and annual statistics compilation
includes/class-migration.php	Migration hook to backfill historical statistics data on plugin update
includes/collection/class-followers.php	Added count_in_range method to support follower growth tracking
local/class-cli.php	WP-CLI commands for statistics management including populate, clear, collect, and compile actions
activitypub.php	Plugin initialization updates to register new statistics classes and REST controller
src/dashboard-stats/	Complete React/TypeScript implementation of the dashboard widget UI with components for highlights, charts, top posts, and supporters
templates/emails/annual-wrapped.php	HTML email template for annual statistics summary notifications
build/dashboard-stats/	Compiled JavaScript and CSS assets for the dashboard widget

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

includes/rest/admin/class-statistics-controller.php

src/dashboard-stats/components/stat-highlights/index.tsx

includes/class-statistics.php

src/dashboard-stats/components/line-chart/index.tsx

includes/wp-admin/class-statistics-dashboard.php

templates/emails/annual-wrapped.php

includes/class-scheduler.php

src/dashboard-stats/components/stats-widget/index.tsx

src/dashboard-stats/components/top-posts/index.tsx

includes/class-statistics.php

- Fix annual email guard to check all registered comment types dynamically instead of hardcoded plural keys (likes_count vs like_count) - Fix follower growth calculation to use followers_count (gained) instead of non-existent followers_gained/followers_lost keys - Add comment date filter to get_top_posts() to only count engagement within the specified date range - Use get_comment_types_for_stats() in count_engagement_in_range() and get_period_comparison() to include federated comments in totals - Fix dashboard widget to fall back to user stats when blog stats are forbidden (non-admin users) - Fix December scheduling to correctly check if past Dec 1st 3:00 AM

- Add generic Mailer::send() method for email dispatching - Change "Followers" to "New Followers" in dashboard highlights (clarity) - Add SVG accessibility (role="img", aria-labelledby, title element) - Add aria-label for external links (opens in new tab indicator) - Use deterministic color assignment via djb2 hash for chart lines - Delay statistics backfill by 1 hour to avoid immediate load after upgrade

Move subject generation to caller instead of determining it internally based on template name. This simplifies the Mailer class and gives callers more control over email subjects.

Register collect and compile as proper subcommands following the existing CLI structure pattern.

Move the stats endpoint under the admin subfolder and update the rest_base to admin/stats to match the admin controller pattern.

@param

- Register Scheduler\Statistics::init() so cron callbacks work - Add import section comments to all dashboard-stats TSX files - Fix auto-generated @param root0 JSDoc with proper annotations - Add ReactNode return type to all component functions - Fix missing backslash on current_user_can in dashboard template

…I send command - Make Mailer::send() accept an optional $alt_body parameter; auto-generate plain text from HTML via wp_strip_all_tags() when not provided - Remove tightly-coupled get_plain_text_body() from Mailer; move plain text generation into the Statistics scheduler caller - Add activitypub_mailer_annual_report user/blog preference with checkbox in both user profile and blog settings notification fieldsets - Fix esc_html() misuse on %d format specifier in annual-wrapped template - Add `wp activitypub stats send` CLI subcommand for testing the annual report email without waiting for cron - Make Statistics::send_annual_email() public for CLI access

- Cast user_id to int in Statistics_Controller to fix strict comparison with BLOG_USER_ID that broke blog actor stats - Replace unbounded get_posts(-1) with SQL subqueries to prevent OOM on large sites; extract get_post_ids_subquery() helper - Add 15-minute transient caching to stats REST endpoint - Fix email template using esc_html__() with HTML arguments (wp_kses) - Fix timezone mismatch in date construction (gmmktime instead of strtotime/gmdate mix) - Reschedule monthly cron to exact first-of-month to prevent 30-day drift - Sanitize template path in Mailer::send() to prevent path traversal - Guard against duplicate 'comment' key in get_comment_types_for_stats()

pfefferle added the Skip Changelog Disables the "Changelog Updated" action for PRs where changelog entries are not necessary. label Dec 15, 2025

pfefferle self-assigned this Dec 15, 2025

pfefferle added the Skip Changelog Disables the "Changelog Updated" action for PRs where changelog entries are not necessary. label Dec 15, 2025

pfefferle requested a review from a team December 15, 2025 15:27

github-actions bot added [Feature] WP Admin [Status] In Progress labels Dec 15, 2025

pfefferle added 5 commits December 15, 2025 17:37

Merge branch 'trunk' into try/fediverse-wrapped-statistics

5f05e27

Merge branch 'trunk' into try/fediverse-wrapped-statistics

2a43028

Merge branch 'trunk' into try/fediverse-wrapped-statistics

c8c9fd1

Remove Fediverse Wrapped shareable card feature

c3a6831

Eliminated the Fediverse Wrapped shareable card functionality by deleting the template, removing related rewrite rules, query vars, and rendering logic from Statistics, and cleaning up associated JavaScript and dashboard UI elements.

github-actions bot added [Feature] REST API [Focus] Editor Changes to the ActivityPub experience in the block editor labels Dec 17, 2025

pfefferle added 3 commits December 17, 2025 12:42

Merge branch 'trunk' into try/fediverse-wrapped-statistics

b374e75

Merge branch 'trunk' into try/fediverse-wrapped-statistics

65191d7

obenland reviewed Dec 17, 2025

View reviewed changes

Merge branch 'trunk' into try/fediverse-wrapped-statistics

4a7b589

pfefferle added 9 commits December 18, 2025 18:14

Improve dashboard stats styling

86f2c70

- Make chart container full width with background extending to edges - Better align icons with text using flex-start and margin adjustments - Simplify stat-content to inline display for natural text flow

Use h3 for section headlines and move chart title outside grey box

628d98b

Change all section headlines from h4 to h3 for proper heading hierarchy. Move the "Engagement Over Time" title outside the grey background area by applying the background only to the chart container.

Use h3 for stats period heading

18beb7d

Change "This month vs. last year" from p to h3 for consistent heading hierarchy across all widget sections.

github-actions bot added the [Feature] Collections label Jan 27, 2026

pfefferle added 5 commits January 27, 2026 16:56

Remove unused Statistics methods

163a5db

- Remove get_yearly_monthly_breakdown() (replaced by get_rolling_monthly_breakdown) - Remove deprecated get_year_comparison() (use get_period_comparison instead)

pfefferle requested review from a team and Copilot January 27, 2026 16:15

Copilot started reviewing on behalf of pfefferle January 27, 2026 16:16 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

pfefferle added 2 commits January 27, 2026 17:58

github-actions bot added the [Feature] Notifications label Jan 27, 2026

pfefferle added 9 commits January 27, 2026 18:17

Fix translators comment placement in Mailer

febdfc7

Refactor get_active_user_ids to use Actors::get_all_ids

b3493b6

Add federated comments directly in get_comment_types_for_stats

b12712e

Remove unused Statistics::init method

e7172cb

Consolidate all dashboard widgets into dedicated Dashboard class

7d82ea7

Remove orphaned Statistics::init call

a599516

Fix annual wrapped email template name

3a0d109

Refactor Mailer::send() to accept subject as parameter

9eb291b

Move subject generation to caller instead of determining it internally based on template name. This simplifies the Mailer class and gives callers more control over email subjects.

Merge branch 'trunk' into try/fediverse-wrapped-statistics

20369f4

pfefferle mentioned this pull request Feb 10, 2026

Add Fediverse Stats dashboard widget #2904

Closed

11 tasks

pfefferle added 2 commits February 11, 2026 11:32

Merge branch 'trunk' into try/fediverse-wrapped-statistics

08952db

Add Stats_Command to production CLI

fe2cccd

Register collect and compile as proper subcommands following the existing CLI structure pattern.

github-actions bot added the [Feature] CLI label Feb 11, 2026

pfefferle added 4 commits February 11, 2026 11:44

Move Statistics_Controller to admin REST namespace

1f4017d

Move the stats endpoint under the admin subfolder and update the rest_base to admin/stats to match the admin controller pattern.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Try: Fediverse Wrapped statistics feature#2633

Try: Fediverse Wrapped statistics feature#2633
pfefferle wants to merge 55 commits intotrunkfrom
try/fediverse-wrapped-statistics

pfefferle commented Dec 15, 2025 •

edited

Loading

Uh oh!

obenland left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pfefferle commented Dec 18, 2025

Uh oh!

pfefferle commented Dec 18, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

pfefferle commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes:

Other information:

Testing instructions:

Changelog entry

Significance

Type

Message

Uh oh!

obenland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pfefferle commented Dec 18, 2025

Uh oh!

pfefferle commented Dec 18, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pfefferle commented Dec 15, 2025 •

edited

Loading