class-jetpack-ai-settings.php — Jetpack – WP Security, Backup, Speed, & Growth 16.2-a.1

jetpack / _inc / lib / class-jetpack-ai-settings.php

jetpack / _inc / lib Last commit date

class-jetpack-ai-settings.php

328 lines

1	<?php
2	/**
3	* Jetpack AI feature settings.
4	*
5	* Central registry for the Jetpack AI master switch and per-feature toggles,
6	* implementing the layered AI gate contract:
7	*
8	* 1. the host allows AI — WP_AI_SUPPORT, via wp_supports_ai()
9	* 2. the plan includes AI — connection + plan checks (owned by each feature)
10	* 3. AI is on for the whole site — the jetpack_ai_enabled option (master switch)
11	* 4. the feature's own switch — per-feature options surfaced on the AI settings page
12	*
13	* Gates 1 and 3 are enforced by is_ai_enabled(), which plugin load points call
14	* instead of applying `jetpack_ai_enabled` directly: the gates AND in after the
15	* filter chain, so no later-priority callback can override them. The gates also
16	* ride the filter itself for package consumers that cannot reference this class.
17	* Gate 4 options are registered here and consulted at each feature's registration
18	* or enqueue point — a disabled feature must stop loading, not just hide.
19	*
20	* @package automattic/jetpack
21	*/
22
23	use Automattic\Jetpack\Modules;
24	use Automattic\Jetpack\Status\Host;
25
26	if ( ! defined( 'ABSPATH' ) ) {
27	exit( 0 );
28	}
29
30	// All consumers require this canonical file once. A class_exists() guard here
31	// would be true on the first load because PHP registers unconditional classes
32	// before executing the file, returning before the self-initialization below.
33
34	/**
35	* Registers the Jetpack AI master switch and per-feature toggle options, and
36	* enforces the host (WP_AI_SUPPORT) and master gates on the AI filters.
37	*/
38	class Jetpack_AI_Settings {
39
40	/**
41	* Master switch option. Named after the pre-existing `jetpack_ai_enabled`
42	* filter it backs, following the `reader_chat` option/filter precedent.
43	*
44	* @var string
45	*/
46	const MASTER_OPTION = 'jetpack_ai_enabled';
47
48	/**
49	* Slug of the `ai` module that acts as the site-wide master switch off
50	* WordPress.com Simple (self-hosted and Atomic), where modules run.
51	*
52	* @var string
53	*/
54	const AI_MODULE = 'ai';
55
56	/**
57	* Feature key => option name for every toggle on the AI settings page.
58	*
59	* `seo_enhancer` and `ai_search` reuse options owned by the SEO/Search
60	* surfaces; the rest are registered by this class.
61	*
62	* @var array
63	*/
64	const FEATURE_OPTIONS = array(
65	'writing_assistant' => 'jetpack_ai_writing_assistant_enabled',
66	'image_editor' => 'jetpack_ai_image_editor_enabled',
67	'feature_clip' => 'jetpack_ai_feature_clip_enabled',
68	'seo_enhancer' => 'ai_seo_enhancer_enabled',
69	'ai_search' => 'jetpack_search_ai_answers_enabled',
70	);
71
72	/**
73	* Option defaults. The reused SEO/Search options keep their established
74	* opt-in defaults; the new per-feature toggles default to on.
75	*
76	* @var array
77	*/
78	const FEATURE_DEFAULTS = array(
79	'writing_assistant' => true,
80	'image_editor' => true,
81	'feature_clip' => true,
82	'seo_enhancer' => false,
83	'ai_search' => false,
84	);
85
86	/**
87	* Feature keys whose options this class registers and syncs (the reused
88	* SEO/Search options are registered by their owning surfaces).
89	*
90	* @var array
91	*/
92	const OWNED_FEATURES = array( 'writing_assistant', 'image_editor', 'feature_clip' );
93
94	/**
95	* Whether init() has already run.
96	*
97	* @var bool
98	*/
99	private static $initialized = false;
100
101	/**
102	* Hook everything up. Must run on every request (front-end, editor, REST):
103	* the filters attached here gate feature loading.
104	*
105	* @return void
106	*/
107	public static function init() {
108	if ( self::$initialized ) {
109	return;
110	}
111	self::$initialized = true;
112
113	add_action( 'init', array( __CLASS__, 'register_settings' ) );
114	add_filter( 'jetpack_sync_options_whitelist', array( __CLASS__, 'add_sync_options_whitelist' ) );
115
116	// Plugin call sites use is_ai_enabled(), which applies gates 1 (host) and
117	// 3 (master) after the filter chain. This in-chain registration stays for
118	// the package consumers that cannot reference this plugin class
119	// (external-media, my-jetpack): there the gates keep their pre-helper,
120	// priority-10 behavior.
121	add_filter( 'jetpack_ai_enabled', array( __CLASS__, 'apply_master_gates' ) );
122
123	// AI surfaces that do not flow through jetpack_ai_enabled.
124	add_filter( 'jetpack_search_ai_answers_enabled', array( __CLASS__, 'apply_master_gates' ) );
125	add_filter( 'jetpack_ai_sidebar_enabled', array( __CLASS__, 'apply_master_gates' ) );
126	}
127
128	/**
129	* Register the master switch and the per-feature options this class owns.
130	*
131	* @return void
132	*/
133	public static function register_settings() {
134	$show_in_rest = ! ( new Host() )->is_wpcom_simple();
135
136	$options = array(
137	self::MASTER_OPTION => __( 'Whether Jetpack AI is enabled on this site.', 'jetpack' ),
138	self::FEATURE_OPTIONS['writing_assistant'] => __( 'Whether the Jetpack AI writing assistant is enabled.', 'jetpack' ),
139	self::FEATURE_OPTIONS['image_editor'] => __( 'Whether the Jetpack AI image editor is enabled.', 'jetpack' ),
140	self::FEATURE_OPTIONS['feature_clip'] => __( 'Whether Jetpack AI video clip generation is enabled.', 'jetpack' ),
141	);
142
143	foreach ( $options as $option => $description ) {
144	register_setting(
145	'general',
146	$option,
147	array(
148	'type' => 'boolean',
149	'description' => $description,
150	'sanitize_callback' => 'rest_sanitize_boolean',
151	// The master option is never exposed over core settings REST:
152	// off-Simple the `ai` module is the master and the option only
153	// holds the legacy pre-module opt-out (a core-REST write would
154	// clobber it without touching the real master); on Simple the
155	// dedicated feature-settings endpoint is the writable surface.
156	'show_in_rest' => self::MASTER_OPTION === $option ? false : $show_in_rest,
157	'default' => true,
158	)
159	);
160	}
161	}
162
163	/**
164	* Add the per-feature AI options to Jetpack Sync's option whitelist.
165	*
166	* Atomic and self-hosted sites write these locally; syncing them lets
167	* WordPress.com (Calypso, the multi-site dashboard) read toggle state and
168	* is the prerequisite for mirroring the dashboard AI toggle later.
169	*
170	* The master switch is deliberately absent: off-Simple the `ai` module is
171	* the master, and module state already reaches WordPress.com through the
172	* synced `active_modules` callable — syncing the option as well would add
173	* a second, driftable source of truth for the same bit.
174	*
175	* @param array $options Option names allowed to sync.
176	* @return array Updated option names.
177	*/
178	public static function add_sync_options_whitelist( $options ) {
179	$options = (array) $options;
180	foreach ( self::OWNED_FEATURES as $feature ) {
181	$options[] = self::FEATURE_OPTIONS[ $feature ];
182	}
183	return array_values( array_unique( $options ) );
184	}
185
186	/**
187	* Fold the host (gate 1) and master switch (gate 3) into an AI enabled filter.
188	*
189	* Restrictive-only on purpose: `jetpack_ai_enabled` is applied with different
190	* defaults at different call sites (Jetpack_AI_Helper passes false on plain
191	* self-hosted sites; the editor extension hub passes true), so this callback
192	* may only ever turn a yes into a no — returning the option value directly
193	* would flip self-hosted defaults to enabled.
194	*
195	* @param bool $enabled The value the call site computed so far.
196	* @return bool
197	*/
198	public static function apply_master_gates( $enabled ) {
199	return (bool) $enabled && self::host_allows_ai() && self::is_master_enabled();
200	}
201
202	/**
203	* Whether Jetpack AI is enabled on this site, with the host (gate 1) and
204	* master switch (gate 3) as final, non-overridable checks.
205	*
206	* Runs the `jetpack_ai_enabled` filter with the call site's default — the
207	* chain may still enable or disable as before — then ANDs the host and
208	* master gates after it, so no late-priority callback can turn AI back on
209	* once either gate says no. Plugin call sites use this helper; the filter
210	* registration in init() stays for the package consumers that cannot
211	* reference this class.
212	*
213	* @since 16.2
214	*
215	* @param bool $default The call site's computed default. Defaults differ
216	* between call sites — see apply_master_gates().
217	* @return bool
218	*/
219	public static function is_ai_enabled( $default = true ) {
220	/**
221	* Filter whether the AI features are enabled in the Jetpack plugin.
222	*
223	* @since 11.8
224	*
225	* @param bool $default Are AI features enabled? The default varies by call site.
226	*/
227	$enabled = (bool) apply_filters( 'jetpack_ai_enabled', $default );
228
229	return $enabled && self::host_allows_ai() && self::is_master_enabled();
230	}
231
232	/**
233	* Gate 1: whether the host allows AI at all.
234	*
235	* Defers to core's wp_supports_ai(), which is backed by the WP_AI_SUPPORT
236	* constant and its own filter. This is a server-owner decision: when it is
237	* off, no AI settings should be shown and no upgrade should ever be offered.
238	*
239	* @return bool
240	*/
241	public static function host_allows_ai() {
242	return wp_supports_ai();
243	}
244
245	/**
246	* Gate 3: whether the site-wide AI master switch is on.
247	*
248	* The master lives in a different place depending on the platform. On
249	* WordPress.com Simple no Jetpack modules run, so the `jetpack_ai_enabled`
250	* option is the master. Everywhere else (self-hosted and Atomic) the `ai`
251	* module is the real master switch, toggled through the standard Jetpack
252	* module machinery; there the option only carries the legacy pre-module
253	* value the one-time opt-out migration reads, and is never written again.
254	*
255	* @return bool
256	*/
257	public static function is_master_enabled() {
258	if ( ( new Host() )->is_wpcom_simple() ) {
259	return (bool) get_option( self::MASTER_OPTION, true );
260	}
261
262	return ( new Modules() )->is_active( self::AI_MODULE );
263	}
264
265	/**
266	* Set the site-wide AI master switch, writing to whichever store backs it on
267	* this platform (see {@see self::is_master_enabled()}).
268	*
269	* On WordPress.com Simple the `jetpack_ai_enabled` option is the master, so
270	* we update it. Off-Simple the `ai` module is the master, so we activate or
271	* deactivate it. The no-exit / no-redirect arguments are passed to
272	* `Modules::update_status()` so this is safe to call outside a request that
273	* expects to terminate (REST handlers, migrations, CLI).
274	*
275	* @param bool $enabled Whether AI should be enabled site-wide.
276	* @return void
277	*/
278	public static function set_master_enabled( bool $enabled ) {
279	if ( ( new Host() )->is_wpcom_simple() ) {
280	update_option( self::MASTER_OPTION, $enabled );
281	return;
282	}
283
284	// The module alone is the master off-Simple. The option is deliberately NOT
285	// written here: WordPress.com derives the master state from the synced
286	// `active_modules` callable, and the stored option must keep its legacy
287	// pre-module value so Jetpack::reconcile_ai_master_optout() can read an
288	// explicit opt-out on sites that upgrade later.
289	( new Modules() )->update_status( self::AI_MODULE, $enabled, false, false );
290	}
291
292	/**
293	* Gate 4: whether an individual feature's switch is on.
294	*
295	* Checks only the feature's own toggle — callers remain responsible for the
296	* outer gates (most already consult the jetpack_ai_enabled filter, which
297	* carries host + master). Only the matching option is read: a code-level
298	* override belongs on the option itself, through core's own option filters.
299	*
300	* @param string $feature Feature key (see FEATURE_OPTIONS).
301	* @return bool False for unknown features.
302	*/
303	public static function is_feature_enabled( $feature ) {
304	if ( ! isset( self::FEATURE_OPTIONS[ $feature ] ) ) {
305	return false;
306	}
307
308	// WordPress.com Simple has no per-feature toggles. It keeps the existing
309	// wp.com settings contract, so the features Jetpack owns stay on there and
310	// the host and master gates remain the only controls. The reused SEO and
311	// Search options are deliberately excluded: they have their own settings
312	// surfaces on Simple and must keep honoring their stored values.
313	if ( in_array( $feature, self::OWNED_FEATURES, true ) && ( new Host() )->is_wpcom_simple() ) {
314	return true;
315	}
316
317	$option = self::FEATURE_OPTIONS[ $feature ];
318
319	return (bool) get_option( $option, self::FEATURE_DEFAULTS[ $feature ] );
320	}
321	}
322
323	// Self-initialize on load. The consuming AI extension files require this file
324	// directly (__DIR__-relative) because on WordPress.com Simple the plugin's
325	// extension files load through wpcom's own loader and load-jetpack.php never
326	// runs. This keeps filter registration identical in both bootstrap paths.
327	Jetpack_AI_Settings::init();
328