Skip to content
4 changes: 4 additions & 0 deletions .github/changelog/add-stats-email-dashboard-link
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Significance: minor
Type: added

Your monthly and annual Fediverse stats emails now include a link that takes you straight to the Fediverse Stats widget on your dashboard.
10 changes: 10 additions & 0 deletions includes/scheduler/class-statistics.php
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,7 @@ public static function send_annual_email( $user_id, $year, $summary, $force = fa
'most_active_month_name' => $most_active_month_name,
'followers_text' => $followers_text,
'supporter_text' => $supporter_text,
'stats_url' => \admin_url( 'index.php#activitypub_stats' ),
'user_id' => $user_id,
)
);
Expand Down Expand Up @@ -196,6 +197,10 @@ public static function send_annual_email( $user_id, $year, $summary, $force = fa
$alt_body .= \sprintf( \__( "Most active month: %s\n", 'activitypub' ), $most_active_month_name );
}

$alt_body .= "\n";
/* translators: %s: URL of the Fediverse Stats dashboard widget */
$alt_body .= \sprintf( \__( "View your stats: %s\n", 'activitypub' ), $args['stats_url'] );

Mailer::send( $user_id, $subject, 'stats-report', $args, $alt_body );
}

Expand Down Expand Up @@ -268,6 +273,7 @@ public static function send_monthly_email( $user_id, $year, $month, $force = fal
'closing' => \__( 'Keep sharing great content on the Fediverse!', 'activitypub' ),
'followers_text' => $followers_text,
'supporter_text' => $supporter_text,
'stats_url' => \admin_url( 'index.php#activitypub_stats' ),
'user_id' => $user_id,
)
);
Expand All @@ -293,6 +299,10 @@ public static function send_monthly_email( $user_id, $year, $month, $force = fal
$alt_body .= \sprintf( \__( "New followers: %+d\n", 'activitypub' ), $stats['followers_count'] );
}

$alt_body .= "\n";
/* translators: %s: URL of the Fediverse Stats dashboard widget */
$alt_body .= \sprintf( \__( "View your stats: %s\n", 'activitypub' ), $args['stats_url'] );

Mailer::send( $user_id, $subject, 'stats-report', $args, $alt_body );
}

Expand Down
10 changes: 10 additions & 0 deletions templates/emails/stats-report.php
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
* - followers_start (int) Followers at period start (annual only).
* - followers_end (int) Followers at period end (annual only).
* - followers_text (string) The follower detail text (HTML allowed).
* - stats_url (string) URL of the Fediverse Stats dashboard widget, empty to omit the link.
* - most_active_month_name (string) Most active month (annual only).
* - {type}_count (int) Per-engagement-type counts.
*
Expand All @@ -42,6 +43,7 @@
'top_posts' => array(),
'top_multiplicator' => null,
'supporter_text' => '',
'stats_url' => '',
'user_id' => 0,
)
);
Expand Down Expand Up @@ -207,6 +209,14 @@

<p><?php echo esc_html( $args['closing'] ?? '' ); ?></p>

<?php if ( ! empty( $args['stats_url'] ) ) : ?>
<p>
<a class="button" href="<?php echo esc_url( $args['stats_url'] ); ?>">
<?php esc_html_e( 'View your stats', 'activitypub' ); ?>
</a>
</p>
<?php endif; ?>

<?php
/**
* Fires at the bottom of the stats report email.
Expand Down
179 changes: 175 additions & 4 deletions tests/phpunit/tests/includes/scheduler/class-test-statistics.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@

namespace Activitypub\Tests\Scheduler;

use Activitypub\Collection\Actors;
use Activitypub\Scheduler\Statistics as Statistics_Scheduler;
use Activitypub\Statistics as Statistics_Collector;
use WP_UnitTestCase;
Expand Down Expand Up @@ -42,33 +43,84 @@ public static function wpSetUpBeforeClass( $factory ) {
*/
protected $sent_count = 0;

/**
* HTML message of the last sent email.
*
* @var string
*/
protected $sent_message = '';

/**
* Plain text alternative of the last sent email.
*
* @var string
*/
protected $sent_alt_body = '';

/**
* Reset email counter and short-circuit wp_mail before each test.
*/
public function set_up() {
parent::set_up();
$this->sent_count = 0;
\add_filter( 'pre_wp_mail', array( $this, 'short_circuit_wp_mail' ) );
$this->sent_count = 0;
$this->sent_message = '';
$this->sent_alt_body = '';
\add_filter( 'pre_wp_mail', array( $this, 'short_circuit_wp_mail' ), 10, 2 );
}

/**
* Remove the test mail filter so it doesn't leak across tests.
*/
public function tear_down() {
\remove_filter( 'pre_wp_mail', array( $this, 'short_circuit_wp_mail' ) );
\remove_filter( 'pre_wp_mail', array( $this, 'short_circuit_wp_mail' ), 10 );
\remove_action( 'phpmailer_init', array( $this, 'capture_alt_body' ), 11 );
parent::tear_down();
}

/**
* Count sent emails and short-circuit wp_mail during tests.
*
* @param null|bool $short_circuit Short-circuit return value.
* @param array $atts The wp_mail() arguments.
*
* @return bool Always true to short-circuit wp_mail.
*/
public function short_circuit_wp_mail() {
public function short_circuit_wp_mail( $short_circuit, $atts = array() ) {
++$this->sent_count;
$this->sent_message = $atts['message'] ?? '';

return true;
}

/**
* Capture the plain text alternative body set by the mailer.
*
* Runs after `Mailer::send()`'s own `phpmailer_init` callback, which assigns AltBody.
*
* @param \PHPMailer\PHPMailer\PHPMailer $mailer The mailer instance.
*/
public function capture_alt_body( $mailer ) {
$this->sent_alt_body = $mailer->{'AltBody'};
}

/**
* Seed a month of stats with meaningful activity.
*
* @param int $user_id The user ID.
* @param int $year The year.
* @param int $month The month.
*/
protected function seed_monthly_stats( $user_id, $year, $month ) {
\update_option(
Statistics_Collector::get_monthly_option_name( $user_id, $year, $month ),
array(
'posts_count' => 3,
'followers_count' => 5,
'followers_total' => 10,
)
);
}

/**
* Test that send_monthly_email only sends once per (user, year, month).
*
Expand Down Expand Up @@ -191,4 +243,123 @@ public function test_send_annual_email_force_records_email_sent() {

$this->assertSame( 2, $this->sent_count, 'Forced send should bypass the email-sent check and still send.' );
}

/**
* Test that the monthly report links to the Fediverse Stats dashboard widget.
*
* @covers ::send_monthly_email
*/
public function test_send_monthly_email_links_to_stats_widget() {
$year = 2026;
$month = 5;
$this->seed_monthly_stats( self::$user_id, $year, $month );

Statistics_Scheduler::send_monthly_email( self::$user_id, $year, $month );

$this->assertSame( 1, $this->sent_count, 'Monthly email should be sent.' );
$this->assertStringContainsString(
\esc_url( \admin_url( 'index.php#activitypub_stats' ) ),
$this->sent_message,
'Monthly email should link to the stats dashboard widget.'
);
$this->assertStringContainsString( 'View your stats', $this->sent_message, 'Monthly email should show the stats link label.' );
}

/**
* Test that the annual report links to the Fediverse Stats dashboard widget.
*
* @covers ::send_annual_email
*/
public function test_send_annual_email_links_to_stats_widget() {
\update_user_option( self::$user_id, 'activitypub_mailer_annual_report', '1' );

Statistics_Scheduler::send_annual_email( self::$user_id, 2024, array( 'posts_count' => 8 ) );

$this->assertSame( 1, $this->sent_count, 'Annual email should be sent.' );
$this->assertStringContainsString(
\esc_url( \admin_url( 'index.php#activitypub_stats' ) ),
$this->sent_message,
'Annual email should link to the stats dashboard widget.'
);
}

/**
* Test that the blog actor's report links to the stats widget.
*
* @covers ::send_monthly_email
*/
public function test_send_monthly_email_links_to_stats_widget_for_blog_actor() {
$year = 2026;
$month = 6;
$this->seed_monthly_stats( Actors::BLOG_USER_ID, $year, $month );

Statistics_Scheduler::send_monthly_email( Actors::BLOG_USER_ID, $year, $month );

$this->assertSame( 1, $this->sent_count, 'Blog actor monthly email should be sent.' );
$this->assertStringContainsString(
\esc_url( \admin_url( 'index.php#activitypub_stats' ) ),
$this->sent_message,
'Blog actor email should link to the stats dashboard widget.'
);
}

/**
* Test that the plain text alternative also carries the stats URL.
*
* @covers ::send_monthly_email
*/
public function test_send_monthly_email_adds_stats_url_to_alt_body() {
$year = 2026;
$month = 8;
$this->seed_monthly_stats( self::$user_id, $year, $month );

// Let wp_mail run so Mailer's phpmailer_init callback assigns AltBody. The default
// From address (wordpress@localhost) has no TLD, which PHPMailer rejects.
\remove_filter( 'pre_wp_mail', array( $this, 'short_circuit_wp_mail' ), 10 );
\add_filter( 'wp_mail_from', array( $this, 'valid_mail_from' ) );
\add_action( 'phpmailer_init', array( $this, 'capture_alt_body' ), 11 );

Statistics_Scheduler::send_monthly_email( self::$user_id, $year, $month );

\remove_filter( 'wp_mail_from', array( $this, 'valid_mail_from' ) );

$this->assertStringContainsString(
\admin_url( 'index.php#activitypub_stats' ),
$this->sent_alt_body,
'Plain text body should include the stats dashboard URL.'
);
}

/**
* Test that the annual report's plain text alternative also carries the stats URL.
*
* @covers ::send_annual_email
*/
public function test_send_annual_email_adds_stats_url_to_alt_body() {
\update_user_option( self::$user_id, 'activitypub_mailer_annual_report', '1' );

// Let wp_mail run so Mailer's phpmailer_init callback assigns AltBody.
\remove_filter( 'pre_wp_mail', array( $this, 'short_circuit_wp_mail' ), 10 );
\add_filter( 'wp_mail_from', array( $this, 'valid_mail_from' ) );
\add_action( 'phpmailer_init', array( $this, 'capture_alt_body' ), 11 );

Statistics_Scheduler::send_annual_email( self::$user_id, 2023, array( 'posts_count' => 8 ) );

\remove_filter( 'wp_mail_from', array( $this, 'valid_mail_from' ) );

$this->assertStringContainsString(
\admin_url( 'index.php#activitypub_stats' ),
$this->sent_alt_body,
'Annual plain text body should include the stats dashboard URL.'
);
}

/**
* Provide a From address PHPMailer accepts.
*
* @return string The From address.
*/
public function valid_mail_from() {
return 'wordpress@example.org';
}
}
Loading