activitypub / includes / cli / class-stats-command.php

class-stats-command.php in ActivityPub 8.2.0, at includes/cli/class-stats-command.php

231 lines 7.3 KB

Raw Download Zip

1	<?php
2	/**
3	* Stats CLI Command.
4	*
5	* @package Activitypub
6	*/
7
8	namespace Activitypub\Cli;
9
10	use Activitypub\Scheduler\Statistics as Statistics_Scheduler;
11	use Activitypub\Statistics;
12
13	/**
14	* Manage ActivityPub statistics.
15	*
16	* @package Activitypub
17	*/
18	class Stats_Command extends \WP_CLI_Command {
19
20	/**
21	* Collect monthly statistics.
22	*
23	* Gathers statistics for a given month including post counts, follower
24	* changes, engagement metrics, and top content.
25	*
26	* ## OPTIONS
27	*
28	* [--user_id=<user_id>]
29	* : The user ID to collect stats for. Omit to collect for all active users.
30	*
31	* [--year=<year>]
32	* : The year to collect stats for. Defaults to current year.
33	*
34	* [--month=<month>]
35	* : The month to collect stats for (1-12). Defaults to current month.
36	* When --year is provided without --month, all months of that year
37	* are collected (up to the current month for the current year).
38	*
39	* [--force]
40	* : Force recollection even if stats already exist.
41	*
42	* ## EXAMPLES
43	*
44	* # Collect real stats for current month
45	* $ wp activitypub stats collect
46	*
47	* # Collect stats for a specific month
48	* $ wp activitypub stats collect --year=2024 --month=6
49	*
50	* # Collect all months of a year
51	* $ wp activitypub stats collect --year=2024
52	*
53	* # Force recollect stats for a specific user
54	* $ wp activitypub stats collect --user_id=1 --force
55	*
56	* @subcommand collect
57	*
58	* @param array $args The positional arguments (unused).
59	* @param array $assoc_args The associative arguments.
60	*/
61	public function collect( $args, $assoc_args ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
62	$user_id = isset( $assoc_args['user_id'] ) ? (int) $assoc_args['user_id'] : null;
63	$year = isset( $assoc_args['year'] ) ? (int) $assoc_args['year'] : (int) \gmdate( 'Y' );
64	$has_month = isset( $assoc_args['month'] );
65	$force = isset( $assoc_args['force'] );
66	$current_year = (int) \gmdate( 'Y' );
67	$current_month = (int) \gmdate( 'n' );
68
69	if ( $year < 2000 \|\| $year > $current_year + 1 ) {
70	\WP_CLI::error( "Invalid year: {$year}." );
71	}
72
73	/*
74	* When --month is provided, collect that single month.
75	* When only --year is provided, collect all months of the year
76	* (up to the current month for the current year).
77	*/
78	if ( $has_month ) {
79	$months = array( (int) $assoc_args['month'] );
80
81	if ( $months[0] < 1 \|\| $months[0] > 12 ) {
82	\WP_CLI::error( "Invalid month: {$months[0]}. Must be between 1 and 12." );
83	}
84	} elseif ( isset( $assoc_args['year'] ) ) {
85	$last_month = ( $year === $current_year ) ? $current_month : 12;
86	$months = \range( 1, $last_month );
87	} else {
88	$months = array( $current_month );
89	}
90
91	$user_ids = $user_id ? array( $user_id ) : Statistics::get_active_user_ids();
92
93	foreach ( $months as $month ) {
94	foreach ( $user_ids as $uid ) {
95	if ( $force ) {
96	$option_name = Statistics::get_monthly_option_name( $uid, $year, $month );
97	\delete_option( $option_name );
98	}
99	Statistics::collect_monthly_stats( $uid, $year, $month );
100	}
101
102	$count = \count( $user_ids );
103	\WP_CLI::log( "Collected {$year}-{$month} for {$count} user(s)." );
104	}
105
106	$total_months = \count( $months );
107	\WP_CLI::success( "Monthly stats collected for {$total_months} month(s)." );
108	}
109
110	/**
111	* Compile annual statistics.
112	*
113	* Aggregates monthly statistics into an annual summary including totals,
114	* averages, and highlights for the year.
115	*
116	* ## OPTIONS
117	*
118	* [--user_id=<user_id>]
119	* : The user ID to compile stats for. Omit to compile for all active users.
120	*
121	* [--year=<year>]
122	* : The year to compile stats for. Defaults to previous year.
123	*
124	* ## EXAMPLES
125	*
126	* # Compile annual stats for previous year
127	* $ wp activitypub stats compile
128	*
129	* # Compile annual stats for a specific year
130	* $ wp activitypub stats compile --year=2024
131	*
132	* # Compile for a specific user
133	* $ wp activitypub stats compile --user_id=1 --year=2024
134	*
135	* @subcommand compile
136	*
137	* @param array $args The positional arguments (unused).
138	* @param array $assoc_args The associative arguments.
139	*/
140	public function compile( $args, $assoc_args ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
141	$user_id = isset( $assoc_args['user_id'] ) ? (int) $assoc_args['user_id'] : null;
142	$year = isset( $assoc_args['year'] ) ? (int) $assoc_args['year'] : ( (int) \gmdate( 'Y' ) - 1 );
143
144	$user_ids = $user_id ? array( $user_id ) : Statistics::get_active_user_ids();
145
146	foreach ( $user_ids as $uid ) {
147	Statistics::compile_annual_summary( $uid, $year );
148	}
149
150	$count = count( $user_ids );
151	\WP_CLI::success( "Annual stats compiled for {$count} user(s) ({$year})." );
152	}
153
154	/**
155	* Send the stats report email.
156	*
157	* Without --month, sends the annual Fediverse Year in Review.
158	* With --month, sends the monthly stats report for that month.
159	*
160	* ## OPTIONS
161	*
162	* [--user_id=<user_id>]
163	* : The user ID to send the email for. Omit to send for all active users.
164	*
165	* [--year=<year>]
166	* : The year. Defaults to previous year (annual) or current year (monthly).
167	*
168	* [--month=<month>]
169	* : The month (1-12). If provided, sends a monthly report instead of annual.
170	*
171	* ## EXAMPLES
172	*
173	* # Send annual report for previous year
174	* $ wp activitypub stats send
175	*
176	* # Send annual report for a specific year
177	* $ wp activitypub stats send --year=2025
178	*
179	* # Send monthly report for a specific month
180	* $ wp activitypub stats send --year=2025 --month=6
181	*
182	* # Send monthly report for a specific user
183	* $ wp activitypub stats send --user_id=1 --year=2025 --month=6
184	*
185	* @subcommand send
186	*
187	* @param array $args The positional arguments (unused).
188	* @param array $assoc_args The associative arguments.
189	*/
190	public function send( $args, $assoc_args ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
191	$user_id = isset( $assoc_args['user_id'] ) ? (int) $assoc_args['user_id'] : null;
192	$is_monthly = isset( $assoc_args['month'] );
193
194	if ( $is_monthly ) {
195	$month = (int) $assoc_args['month'];
196	$year = isset( $assoc_args['year'] ) ? (int) $assoc_args['year'] : (int) \gmdate( 'Y' );
197
198	if ( $month < 1 \|\| $month > 12 ) {
199	\WP_CLI::error( "Invalid month: {$month}. Must be between 1 and 12." );
200	}
201	} else {
202	$year = isset( $assoc_args['year'] ) ? (int) $assoc_args['year'] : ( (int) \gmdate( 'Y' ) - 1 );
203	}
204
205	$user_ids = $user_id ? array( $user_id ) : Statistics::get_active_user_ids();
206
207	$sent = 0;
208	foreach ( $user_ids as $uid ) {
209	if ( $is_monthly ) {
210	Statistics_Scheduler::send_monthly_email( $uid, $year, $month, true );
211	\WP_CLI::log( "Monthly report email sent for user {$uid} ({$year}-{$month})." );
212	} else {
213	$summary = Statistics::compile_annual_summary( $uid, $year );
214
215	if ( empty( $summary ) ) {
216	\WP_CLI::warning( "No stats found for user {$uid} ({$year}), skipping." );
217	continue;
218	}
219
220	Statistics_Scheduler::send_annual_email( $uid, $year, $summary, true );
221	\WP_CLI::log( "Annual report email sent for user {$uid} ({$year})." );
222	}
223	++$sent;
224	}
225
226	$type = $is_monthly ? 'Monthly' : 'Annual';
227	$period = $is_monthly ? "{$year}-{$month}" : "{$year}";
228	\WP_CLI::success( "{$type} report email sent for {$sent} user(s) ({$period})." );
229	}
230	}
231