imagify / classes / Tracking / McpTracking.php

McpTracking.php in Imagify Image Optimization: Optimize Images | Compress & Convert to WebP/AVIF 2.3.1, at classes/Tracking/McpTracking.php

160 lines 5.3 KB

Raw Download Zip

1	<?php
2	declare(strict_types=1);
3
4	namespace Imagify\Tracking;
5
6	/**
7	* Tracking class for Imagify MCP ability events.
8	*
9	* Fires the same Mixpanel events as the UI path but with context `wp_plugin_mcp`
10	* so Mixpanel can aggregate across both surfaces or filter by source.
11	*
12	* @since 2.3.0
13	*/
14	class McpTracking extends BaseTracking {
15
16	/**
17	* Returns the default event properties shared by every MCP tracked event.
18	*
19	* Overrides context to `wp_plugin_mcp` so Mixpanel can distinguish MCP
20	* executions from UI-initiated ones.
21	*
22	* @return array<string, mixed>
23	*/
24	protected function get_default_event_properties(): array {
25	$defaults = parent::get_default_event_properties();
26	$defaults['context'] = 'wp_plugin_mcp';
27	return $defaults;
28	}
29
30	/**
31	* Track a "Media Optimized" event triggered via the MCP ability.
32	*
33	* Only fires for the `imagify/optimize-media` ability and only on success.
34	*
35	* @param string $ability_id Ability slug, e.g. `imagify/optimize-media`.
36	* @param array $result Return value of OptimizeMedia::execute().
37	* @param float $start_time microtime(true) captured before execute() ran.
38	* @param array $input_params Raw input params passed to execute().
39	* @return void
40	*/
41	public function track_media_optimized( string $ability_id, array $result, float $start_time, array $input_params ): void {
42	if ( ! $this->can_track() ) {
43	return;
44	}
45
46	if ( 'imagify/optimize-media' !== $ability_id ) {
47	return;
48	}
49
50	if ( 'success' !== ( $result['status'] ?? '' ) ) {
51	return;
52	}
53
54	$media_id = isset( $input_params['media_id'] ) ? (int) $input_params['media_id'] : 0;
55	$execution_time_ms = round( ( microtime( true ) - $start_time ) * 1000, 2 );
56
57	$optimization_level = isset( $input_params['optimization_level'] )
58	? (int) $input_params['optimization_level']
59	: (int) get_imagify_option( 'optimization_level' );
60
61	$event_data = array_merge(
62	$this->get_default_event_properties(),
63	[
64	'initiated_via' => 'mcp',
65	'optimization_level' => $optimization_level,
66	'media_type' => $media_id > 0 ? (string) get_post_mime_type( $media_id ) : '',
67	'original_size' => null !== $result['original_size'] ? (int) $result['original_size'] : null,
68	'optimized_size' => null !== $result['optimized_size'] ? (int) $result['optimized_size'] : null,
69	'savings_percent' => null !== $result['savings_percent'] ? (float) $result['savings_percent'] : null,
70	'next_gen_format' => $this->resolve_next_gen_format(),
71	'execution_time_ms' => $execution_time_ms,
72	]
73	);
74
75	$this->mixpanel->track_direct( 'Media Optimized', $event_data );
76	}
77
78	/**
79	* Track a generic "MCP Ability Executed" event for any ability invocation.
80	*
81	* Fires for every ability (including optimize-media) so Mixpanel dashboards
82	* can aggregate all MCP calls by ability_id regardless of outcome.
83	*
84	* @param string $ability_id Ability slug, e.g. `imagify/get-stats`.
85	* @param string $ability_name Human-readable ability label.
86	* @param float $start_time microtime(true) captured before execute() ran.
87	* @param bool $is_preview True when the call was a credit-consumption preview
88	* (`confirmation_required`/`insufficient_quota`/`invalid_api_key`)
89	* rather than a real execution. Defaults to false so
90	* non-quota-sensitive abilities keep their current behavior.
91	* @return void
92	*/
93	public function track_ability_executed( string $ability_id, string $ability_name, float $start_time, bool $is_preview = false ): void {
94	if ( ! $this->can_track() ) {
95	return;
96	}
97
98	$event_data = array_merge(
99	$this->get_default_event_properties(),
100	[
101	'ability_id' => $ability_id,
102	'ability_name' => $ability_name,
103	'execution_time_ms' => round( ( microtime( true ) - $start_time ) * 1000, 2 ),
104	'is_preview' => $is_preview,
105	]
106	);
107
108	$this->mixpanel->track_direct( 'MCP Ability Executed', $event_data );
109	}
110
111	/**
112	* Track an "MCP Ability Permission Denied" event.
113	*
114	* @param string $ability_id Ability slug.
115	* @param string $ability_name Human-readable ability label.
116	* @param string $required_capability The capability that was missing.
117	* @return void
118	*/
119	public function track_permission_denied( string $ability_id, string $ability_name, string $required_capability ): void {
120	if ( ! $this->can_track() ) {
121	return;
122	}
123
124	$user = wp_get_current_user();
125	$user_role = ! empty( $user->roles ) ? (string) $user->roles[0] : '';
126
127	$event_data = array_merge(
128	$this->get_default_event_properties(),
129	[
130	'ability_id' => $ability_id,
131	'ability_name' => $ability_name,
132	'required_capability' => $required_capability,
133	'user_role' => $user_role,
134	]
135	);
136
137	$this->mixpanel->track_direct( 'MCP Ability Permission Denied', $event_data );
138	}
139
140	/**
141	* Resolve the next-gen format from the site's conversion settings.
142	*
143	* Returns 'avif' when AVIF conversion is enabled (highest priority), 'webp'
144	* when only WebP is enabled, or null when next-gen conversion is off.
145	*
146	* @return string\|null
147	*/
148	protected function resolve_next_gen_format(): ?string {
149	if ( (bool) get_imagify_option( 'convert_to_avif' ) ) {
150	return 'avif';
151	}
152
153	if ( (bool) get_imagify_option( 'convert_to_webp' ) ) {
154	return 'webp';
155	}
156
157	return null;
158	}
159	}
160