Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
64.07%
189 / 295
45.95%
17 / 37
 CRAP
0.00%
0 / 1
Initializer
64.07%
189 / 295
45.95%
17 / 37
 503.93
0.00%
0 / 1
 init
84.21%
16 / 19
0.00%
0 / 1
 5.10
 add_menu_item
0.00%
0 / 11
0.00%
0 / 1
 6
 maybe_load_wp_build
0.00%
0 / 5
0.00%
0 / 1
 6
 load_wp_build
0.00%
0 / 8
0.00%
0 / 1
 6
 alias_screen_id_for_wp_build
0.00%
0 / 3
0.00%
0 / 1
 6
 inject_script_data
0.00%
0 / 10
0.00%
0 / 1
 6
 inject_optin_availability
100.00%
5 / 5
100.00%
1 / 1
 2
 render_fallback
0.00%
0 / 1
0.00%
0 / 1
 2
 is_seo_admin_request
0.00%
0 / 3
0.00%
0 / 1
 12
 is_seo_tools_module_active
66.67%
2 / 3
0.00%
0 / 1
 2.15
 is_sitemap_enabled
100.00%
4 / 4
100.00%
1 / 1
 2
 get_reachable_sitemap_url
63.64%
7 / 11
0.00%
0 / 1
 11.08
 is_canonical_enabled
100.00%
4 / 4
100.00%
1 / 1
 2
 is_seo_surface_visible
100.00%
3 / 3
100.00%
1 / 1
 3
 is_optin_available
100.00%
1 / 1
100.00%
1 / 1
 2
 get_overview_data
95.65%
22 / 23
0.00%
0 / 1
 3
 coverage_post_types
100.00%
1 / 1
100.00%
1 / 1
 1
 coverage_meta_keys
100.00%
6 / 6
100.00%
1 / 1
 1
 get_content_coverage
100.00%
6 / 6
100.00%
1 / 1
 2
 is_content_coverage
100.00%
6 / 6
100.00%
1 / 1
 5
 compute_content_coverage
100.00%
40 / 40
100.00%
1 / 1
 2
 register_coverage_invalidation
100.00%
4 / 4
100.00%
1 / 1
 2
 invalidate_content_coverage_on_status_change
100.00%
5 / 5
100.00%
1 / 1
 5
 invalidate_content_coverage_on_delete
100.00%
3 / 3
100.00%
1 / 1
 3
 invalidate_content_coverage_on_meta_change
100.00%
3 / 3
100.00%
1 / 1
 2
 invalidate_content_coverage
100.00%
1 / 1
100.00%
1 / 1
 1
 get_site_data
100.00%
10 / 10
100.00%
1 / 1
 3
 register_rest_settings
0.00%
0 / 9
0.00%
0 / 1
 2
 register_optin_route
0.00%
0 / 11
0.00%
0 / 1
 2
 handle_optin
0.00%
0 / 9
0.00%
0 / 1
 6
 rest_reads
0.00%
0 / 5
0.00%
0 / 1
 2
 rest_read_paths
0.00%
0 / 6
0.00%
0 / 1
 2
 register_rest_reads
0.00%
0 / 12
0.00%
0 / 1
 6
 reads_permission_check
0.00%
0 / 1
0.00%
0 / 1
 2
 get_settings_data
95.65%
22 / 23
0.00%
0 / 1
 9
 get_google_verify_data
80.00%
8 / 10
0.00%
0 / 1
 3.07
 get_ai_data
100.00%
10 / 10
100.00%
1 / 1
 3
1<?php
2/**
3 * Jetpack SEO — the visibility command center for WordPress sites.
4 *
5 * Registers the `admin.php?page=jetpack-seo` screen via Admin_Menu so it is
6 * reachable on self-hosted, Atomic/WoW, and Simple sites alike, and loads the
7 * `@wordpress/build` (wp-build) dashboard bundle that renders it.
8 *
9 * @package automattic/jetpack-seo-package
10 */
11
12namespace Automattic\Jetpack\SEO;
13
14use Automattic\Jetpack\Admin_UI\Admin_Menu;
15use Automattic\Jetpack\Modules;
16use Automattic\Jetpack\Status\Host;
17use Automattic\Jetpack\WP_Build_Polyfills\WP_Build_Polyfills;
18use Jetpack_SEO_Titles;
19use Jetpack_SEO_Utils;
20use Jetpack_Sitemap_Librarian;
21
22/**
23 * The main Initializer class. Registers the admin menu and loads the wp-build
24 * dashboard, bootstrapping the React app's initial state onto the page.
25 */
26class Initializer {
27
28    /**
29     * Jetpack SEO package version.
30     *
31     * @var string
32     */
33    const PACKAGE_VERSION = '0.6.0';
34
35    /**
36     * Filter name that gates the entire Jetpack SEO surface.
37     *
38     * When this filter returns true, the package registers its admin menu and
39     * loads the wp-build dashboard. Default false before release - when the
40     * filter is off the package registers no admin menu and no assets, and
41     * changes nothing about the existing Jetpack UI.
42     *
43     * @var string
44     */
45    const FEATURE_FILTER = 'rsm_jetpack_seo';
46
47    /**
48     * URL-facing menu slug (`admin.php?page=jetpack-seo`).
49     */
50    const MENU_SLUG = 'jetpack-seo';
51
52    /**
53     * Slug emitted by `@wordpress/build` (`wpPlugin.pages[0]`). wp-build's
54     * auto-generated enqueue callback only fires when `$screen->id` matches
55     * this value, so we alias the screen id to it via `current_screen` without
56     * changing the user-facing URL.
57     */
58    const WP_BUILD_SLUG = 'jetpack-seo-dashboard';
59
60    /**
61     * Render function generated by `@wordpress/build` into
62     * `build/pages/jetpack-seo-dashboard/page-wp-admin.php`. Naming convention:
63     * `{wpPlugin.name}_{page-with-underscores}_wp_admin_render_page`.
64     */
65    const WP_BUILD_RENDER_FN = 'jetpack_seo_jetpack_seo_dashboard_wp_admin_render_page';
66
67    /**
68     * Key under `window.JetpackScriptData` the React app reads its state from
69     * (`window.JetpackScriptData.seo`). Must match the JS-side reader in
70     * `_inc/data/get-overview.ts`.
71     */
72    const SCRIPT_DATA_KEY = 'seo';
73
74    /**
75     * Post-meta keys mirrored from `Jetpack_SEO_Posts` (in plugins/jetpack).
76     * Duplicated here as literals on purpose: that plugin class is NOT reliably
77     * loaded in this package's admin context (the `Jetpack_SEO_Utils`
78     * `class_exists` guard in `get_overview_data()` is there for the same
79     * reason), so referencing its constants would fatal. Content-coverage
80     * counting only needs the key strings, which are stable.
81     */
82    const META_DESCRIPTION = 'advanced_seo_description';
83    const META_SCHEMA_TYPE = 'jetpack_seo_schema_type';
84    const META_TITLE       = 'jetpack_seo_html_title';
85    const META_NOINDEX     = 'jetpack_seo_noindex';
86
87    /**
88     * Option recording whether sitemap generation is enabled.
89     *
90     * Read in place of the standalone `sitemaps` module's active state. Module-active
91     * state is filtered against the modules present on disk, so once that module is
92     * removed it would read as inactive even for sites that had it on. A one-time
93     * migration in the Jetpack plugin seeds this option from the site's existing module
94     * state and keeps it in sync while the legacy module still exists. See
95     * `Jetpack::migrate_sitemaps_module_to_seo_option()`.
96     *
97     * @var string
98     */
99    const SITEMAP_ENABLED_OPTION = 'jetpack_seo_sitemap_enabled';
100
101    /**
102     * Option recording whether canonical URLs are enabled.
103     *
104     * Read in place of the standalone `canonical-urls` module's active state. Module-active
105     * state is filtered against the modules present on disk, so once that module is
106     * removed it would read as inactive even for sites that had it on. A one-time
107     * migration in the Jetpack plugin seeds this option from the site's existing module
108     * state and keeps it in sync while the legacy module still exists. See
109     * `Jetpack::migrate_canonical_urls_module_to_seo_option()`.
110     *
111     * @var string
112     */
113    const CANONICAL_ENABLED_OPTION = 'jetpack_seo_canonical_urls_enabled';
114
115    /**
116     * Option recording whether the Jetpack SEO surface is discoverable on this site.
117     *
118     * Gates whether the SEO admin menu registers on self-hosted sites. Seeded once by the
119     * Jetpack plugin on install/upgrade: fresh installs default to visible, existing
120     * installs default to hidden and opt in via the legacy Traffic page or My Jetpack.
121     * WordPress.com (Simple + Atomic) bypasses this option entirely and is always visible.
122     * Absent until seeded, in which case self-hosted defaults to hidden (the non-disruptive
123     * default). See {@see self::is_seo_surface_visible()}.
124     *
125     * @var string
126     */
127    const VISIBILITY_OPTION = 'jetpack_seo_surface_visible';
128
129    /**
130     * Transient holding the Overview's content-coverage counts.
131     *
132     * Versioned, so a future change to the payload's shape can't read a stale array
133     * written by an older version of this code.
134     *
135     * @var string
136     */
137    const COVERAGE_COUNTS_TRANSIENT = 'jetpack_seo_content_coverage_counts_v1';
138
139    /**
140     * How long the content-coverage counts survive without being invalidated.
141     *
142     * @var int
143     */
144    const COVERAGE_COUNTS_TTL = HOUR_IN_SECONDS;
145
146    /**
147     * Whether the package has been initialized.
148     *
149     * @var bool
150     */
151    private static $initialized = false;
152
153    /**
154     * Initialize the package.
155     *
156     * Called from the Jetpack plugin's `late_initialization()` hook.
157     *
158     * @return void
159     */
160    public static function init() {
161        if ( self::$initialized ) {
162            return;
163        }
164        self::$initialized = true;
165
166        // Gate the entire SEO surface behind the feature flag.
167        if ( ! (bool) apply_filters( self::FEATURE_FILTER, false ) ) {
168            return;
169        }
170
171        // The opt-in endpoint must be reachable even before the surface is visible, so
172        // existing self-hosted installs can switch to the new experience from the legacy
173        // Traffic page or My Jetpack (JETPACK-1700). Registered ahead of the cohort gate.
174        add_action( 'rest_api_init', array( __CLASS__, 'register_optin_route' ) );
175
176        // Expose opt-in availability to other admin surfaces (the legacy Traffic-page
177        // banner reads it via `@automattic/jetpack-script-data`). Hooked here — after the
178        // feature flag, before the cohort gate — so a still-hidden install gets the signal.
179        add_filter( 'jetpack_admin_js_script_data', array( __CLASS__, 'inject_optin_availability' ) );
180
181        // Discoverability cohort gate: the SEO surface is auto-discoverable for fresh
182        // installs and all WordPress.com sites; existing self-hosted installs opt in via
183        // the legacy Traffic page or My Jetpack (JETPACK-1700). Until it's visible we
184        // register nothing else here and let those opt-in surfaces drive discovery.
185        if ( ! self::is_seo_surface_visible() ) {
186            return;
187        }
188
189        // The admin menu and app shell register whenever the surface is visible, even
190        // when the `seo-tools` module is inactive, so SEO stays discoverable and can be
191        // turned on from within the page itself (JETPACK-1700). When the module is off,
192        // the Overview renders only its "enable SEO tools" affordance.
193        //
194        // Priority 1: load the wp-build bundle (and define its render function)
195        // before `add_menu_item()` runs at the default priority and needs it.
196        add_action( 'admin_menu', array( __CLASS__, 'maybe_load_wp_build' ), 1 );
197        add_action( 'admin_menu', array( __CLASS__, 'add_menu_item' ), 10 );
198
199        // Read-only REST routes the dashboard hydrates its initial state from. Preloaded
200        // into the page (see inject_script_data) so a normal load resolves them with no
201        // request, and fetched by the app when that preload is missing or stale — so the
202        // dashboard recovers its data instead of dead-ending. Registered whenever the
203        // surface is visible (independent of the seo-tools module, like the Overview).
204        add_action( 'rest_api_init', array( __CLASS__, 'register_rest_reads' ) );
205
206        // Keep the Overview's cached content-coverage counts honest. Hooked here rather than
207        // alongside the admin surface above because posts are written from everywhere — the
208        // block editor (REST), the classic editor, wp-cli, cron, other plugins — and the
209        // cache has to be dropped wherever that happens, not just where it's read.
210        self::register_coverage_invalidation();
211
212        // The settings surface only comes online once SEO tools are active — there's
213        // nothing to configure while the module is off, so we don't register its REST
214        // endpoints until then. Expose the core `blog_public` option to the REST settings
215        // endpoint so the Settings tab can save search-engine visibility via
216        // `/wp/v2/settings` (the Jetpack settings endpoint only accepts Jetpack options).
217        // Writes are still capability-gated by the core settings controller.
218        if ( self::is_seo_tools_module_active() ) {
219            // Front-end JSON-LD schema output and author profile schema fields.
220            Schema_Builder::init();
221            Author_Schema_Node::init();
222            add_action( 'rest_api_init', array( __CLASS__, 'register_rest_settings' ) );
223            // Package-owned route for the site-level Schema settings (see the controller).
224            add_action( 'rest_api_init', array( Schema_Settings_Controller::class, 'register_routes' ) );
225        }
226
227        /**
228         * Fires after the Jetpack SEO package is initialized.
229         *
230         * @since 0.1.0
231         */
232        do_action( 'jetpack_seo_init' );
233    }
234
235    /**
236     * Register the admin menu item.
237     *
238     * Uses Admin_Menu so the page is reachable on wp-admin across all site
239     * types. The render callback is wp-build's generated render function when
240     * the bundle is loaded (i.e. on the SEO page itself, after
241     * `maybe_load_wp_build()` ran at priority 1); otherwise it falls back to a
242     * bare mount node so the page never fatals on an unbuilt checkout.
243     *
244     * @return void
245     */
246    public static function add_menu_item() {
247        $callback = function_exists( self::WP_BUILD_RENDER_FN )
248            ? self::WP_BUILD_RENDER_FN
249            : array( __CLASS__, 'render_fallback' );
250
251        Admin_Menu::add_menu(
252            'SEO',
253            'SEO',
254            'manage_options',
255            self::MENU_SLUG,
256            $callback,
257            2
258        );
259    }
260
261    /**
262     * On the SEO admin page, load the wp-build bundle, alias the screen id so
263     * wp-build enqueues its assets, and bootstrap the app's initial state.
264     *
265     * Hooked at `admin_menu` priority 1 so polyfills register and the render
266     * function is defined before `add_menu_item()` runs at priority 10.
267     *
268     * @return void
269     */
270    public static function maybe_load_wp_build() {
271        if ( ! self::is_seo_admin_request() ) {
272            return;
273        }
274
275        self::load_wp_build();
276        add_action( 'current_screen', array( __CLASS__, 'alias_screen_id_for_wp_build' ) );
277        add_filter( 'jetpack_admin_js_script_data', array( __CLASS__, 'inject_script_data' ) );
278    }
279
280    /**
281     * Load wp-build's generated registration file and register the polyfills
282     * the bundle depends on. No-op on a fresh checkout before `pnpm build`, in
283     * which case `add_menu_item()` falls back to {@see self::render_fallback()}.
284     *
285     * @return void
286     */
287    private static function load_wp_build() {
288        $build_index = dirname( __DIR__ ) . '/build/build.php';
289
290        if ( ! file_exists( $build_index ) ) {
291            return;
292        }
293
294        require_once $build_index;
295
296        WP_Build_Polyfills::register(
297            'jetpack-seo',
298            array_merge( WP_Build_Polyfills::SCRIPT_HANDLES, WP_Build_Polyfills::MODULE_IDS )
299        );
300    }
301
302    /**
303     * Alias the current screen id to wp-build's expected slug so its
304     * auto-generated enqueue callback fires for our user-facing page.
305     *
306     * @param \WP_Screen|null $screen The current screen object (passed by WP).
307     * @return void
308     */
309    public static function alias_screen_id_for_wp_build( $screen ) {
310        if ( ! is_object( $screen ) ) {
311            return;
312        }
313
314        $screen->id = self::WP_BUILD_SLUG;
315    }
316
317    /**
318     * Bootstrap the React app's initial state onto `window.JetpackScriptData.seo`.
319     *
320     * Because wp-build pages load as ES modules, `wp_localize_script` can't
321     * attach data to them; the shared `jetpack_admin_js_script_data` filter
322     * (printed by the Script_Data package onto the `jetpack-script-data` handle
323     * the bundle already depends on) is the supported channel. The per-tab state
324     * is provided as an apiFetch *preload* (mirrors Podcast) so the app resolves
325     * it with no request on a normal load yet can re-fetch when the preload is
326     * missing or stale, rather than dead-ending on a one-shot read.
327     *
328     * @param array $data Script data being injected onto the page.
329     * @return array
330     */
331    public static function inject_script_data( $data ) {
332        if ( ! is_array( $data ) ) {
333            $data = array();
334        }
335
336        // Preload the dashboard's REST reads into the page so the app resolves them from
337        // cache on first paint with no network request — while still being able to
338        // re-fetch if that preload is ever missing or stale. This replaces injecting the
339        // raw payloads, which the app read synchronously once and couldn't recover from
340        // when momentarily absent (the load-error dead-end). See register_rest_reads() and
341        // the client readers `_inc/data/get-preloaded.ts` + `_inc/data/use-ensure-tab-data.ts`.
342        $data[ self::SCRIPT_DATA_KEY ]['preload'] = array_reduce(
343            self::rest_read_paths(),
344            'rest_preload_api_request',
345            array()
346        );
347
348        // Small synchronous reads used outside the per-tab data stores, and not part of
349        // the load-error path.
350        $data[ self::SCRIPT_DATA_KEY ]['google_verify'] = self::get_google_verify_data();
351        $data[ self::SCRIPT_DATA_KEY ]['site']          = self::get_site_data();
352
353        return $data;
354    }
355
356    /**
357     * Expose whether this install should be offered the SEO opt-in, onto
358     * `window.JetpackScriptData.seo.optin_available` for other admin surfaces (e.g. the
359     * legacy Traffic-page banner). Only hooked when the feature flag is on, so the field is
360     * simply absent otherwise.
361     *
362     * @param array $data Script data being injected onto the page.
363     * @return array
364     */
365    public static function inject_optin_availability( $data ) {
366        if ( ! is_array( $data ) ) {
367            $data = array();
368        }
369
370        $data[ self::SCRIPT_DATA_KEY ]['optin_available'] = self::is_optin_available();
371        // Read by the legacy Traffic page to hide its SEO / Sitemaps sections once the
372        // site is on the new experience (fresh install / opted-in / WordPress.com), so the
373        // two surfaces never show at once. The legacy sections stay for self-hosted installs
374        // that haven't opted in.
375        $data[ self::SCRIPT_DATA_KEY ]['surface_visible'] = self::is_seo_surface_visible();
376
377        return $data;
378    }
379
380    /**
381     * Fallback render used when the wp-build artifact is missing (unbuilt
382     * checkout). Renders a bare wrapper so the page loads without the app.
383     *
384     * @return void
385     */
386    public static function render_fallback() {
387        echo '<div class="wrap"><h1>SEO</h1></div>';
388    }
389
390    /**
391     * Whether the current request targets the SEO admin page.
392     *
393     * @return bool
394     */
395    private static function is_seo_admin_request() {
396        // phpcs:ignore WordPress.Security.NonceVerification.Recommended
397        if ( ! is_admin() || ! isset( $_GET['page'] ) ) {
398            return false;
399        }
400
401        // phpcs:ignore WordPress.Security.NonceVerification.Recommended
402        return self::MENU_SLUG === sanitize_text_field( wp_unslash( $_GET['page'] ) );
403    }
404
405    /**
406     * Whether the `seo-tools` Jetpack module is currently active.
407     *
408     * @return bool
409     */
410    private static function is_seo_tools_module_active() {
411        if ( ! class_exists( 'Automattic\\Jetpack\\Modules' ) ) {
412            return false;
413        }
414        return ( new Modules() )->is_active( 'seo-tools' );
415    }
416
417    /**
418     * Whether sitemap generation is enabled.
419     *
420     * Reads the durable {@see self::SITEMAP_ENABLED_OPTION} flag. The default is only
421     * used when the option is absent (for example before the Jetpack plugin's migration
422     * has run on a freshly upgraded site), in which case it falls back to the live
423     * `sitemaps` module state so behavior is unchanged in that gap.
424     *
425     * @param Modules $modules Modules instance to read live module state from.
426     * @return bool
427     */
428    private static function is_sitemap_enabled( Modules $modules ) {
429        $enabled = get_option( self::SITEMAP_ENABLED_OPTION, null );
430
431        // Only fall back to the live module state when the durable option is absent.
432        // Passing it as get_option()'s default would evaluate it on every call, since
433        // PHP resolves function arguments eagerly even when the option exists.
434        if ( null === $enabled ) {
435            $enabled = $modules->is_active( 'sitemaps' );
436        }
437
438        return (bool) $enabled;
439    }
440
441    /**
442     * The public URL of the generated XML sitemap, or an empty string when none
443     * is currently reachable.
444     *
445     * A sitemap is only reachable when generation is enabled, the site is public
446     * (Jetpack does not load the Sitemaps module on sites that discourage search
447     * engines), and the master sitemap has actually been generated — the Jetpack
448     * plugin builds it via cron 1–15 minutes after activation, so the URL 404s
449     * until then. Callers treat an empty string as "not yet reachable" and skip
450     * linking to it.
451     *
452     * {@see Jetpack_Sitemap_Librarian} and jetpack_sitemap_uri() live in the
453     * Jetpack plugin's Sitemaps module (loaded only for an active module on a
454     * public site), so both are guarded; in the package-only context they are
455     * absent and the sitemap is reported as not reachable.
456     *
457     * @param bool $sitemap_active Whether sitemap generation is enabled.
458     * @return string The sitemap URL, or '' when not reachable.
459     */
460    private static function get_reachable_sitemap_url( $sitemap_active ) {
461        // Jetpack only serves sitemaps when generation is on and the site is public.
462        if ( ! $sitemap_active || (int) get_option( 'blog_public', 1 ) !== 1 ) {
463            return '';
464        }
465
466        // The Sitemaps module (the librarian class, the `JP_MASTER_SITEMAP_TYPE`
467        // constant, and the `jp_sitemap_filename()` / `jetpack_sitemap_uri()`
468        // helpers) all live together in plugins/jetpack and load as a unit, so this
469        // single guard covers every symbol used below.
470        if (
471            ! class_exists( 'Jetpack_Sitemap_Librarian' )
472            || ! defined( 'JP_MASTER_SITEMAP_TYPE' )
473            || ! function_exists( 'jp_sitemap_filename' )
474            || ! function_exists( 'jetpack_sitemap_uri' )
475        ) {
476            return '';
477        }
478
479        // The master sitemap is stored as a post once the cron generation run
480        // completes; until then there is nothing to link to.
481        // `jp_sitemap_filename( JP_MASTER_SITEMAP_TYPE )` is the master file name
482        // ('sitemap.xml'); inlined so this stays one (untestable-in-package) line.
483        // @phan-suppress-next-line PhanUndeclaredFunction,PhanUndeclaredClassMethod -- guarded above; symbols live in plugins/jetpack.
484        $master = ( new Jetpack_Sitemap_Librarian() )->read_sitemap_data( jp_sitemap_filename( JP_MASTER_SITEMAP_TYPE ), JP_MASTER_SITEMAP_TYPE );
485        if ( null === $master ) {
486            return '';
487        }
488
489        // esc_url_raw (not esc_url): the value is transported via script data and
490        // rendered by React, so it must not be HTML-entity-encoded (e.g. the
491        // plain-permalink `?jetpack-sitemap=` form keeps its raw `&`).
492        // @phan-suppress-next-line PhanUndeclaredFunction -- jp_sitemap_filename()/jetpack_sitemap_uri() live in plugins/jetpack, guarded by function_exists.
493        return esc_url_raw( (string) jetpack_sitemap_uri( jp_sitemap_filename( JP_MASTER_SITEMAP_TYPE ) ) );
494    }
495
496    /**
497     * Whether canonical URLs are enabled.
498     *
499     * Reads the durable {@see self::CANONICAL_ENABLED_OPTION} flag. The default is only
500     * used when the option is absent (for example before the Jetpack plugin's migration
501     * has run on a freshly upgraded site), in which case it falls back to the live
502     * `canonical-urls` module state so behavior is unchanged in that gap.
503     *
504     * @param Modules $modules Modules instance to read live module state from.
505     * @return bool
506     */
507    private static function is_canonical_enabled( Modules $modules ) {
508        $enabled = get_option( self::CANONICAL_ENABLED_OPTION, null );
509
510        // Only fall back to the live module state when the durable option is absent.
511        // Passing it as get_option()'s default would evaluate it on every call, since
512        // PHP resolves function arguments eagerly even when the option exists.
513        if ( null === $enabled ) {
514            $enabled = $modules->is_active( 'canonical-urls' );
515        }
516
517        return (bool) $enabled;
518    }
519
520    /**
521     * Whether the Jetpack SEO surface should be discoverable (admin menu registered).
522     *
523     * WordPress.com sites (Simple + Atomic) are always discoverable — how SEO presents
524     * there is a Dotcom decision, independent of the self-hosted rollout. On self-hosted
525     * sites the durable {@see self::VISIBILITY_OPTION} cohort flag decides: fresh installs
526     * are seeded visible, existing installs stay hidden until they opt in. Defaults to
527     * hidden when the option is absent (e.g. before the plugin's seed has run), so an
528     * existing site is never surprised by the new surface before its cohort is recorded.
529     *
530     * @return bool
531     */
532    public static function is_seo_surface_visible() {
533        if ( class_exists( 'Automattic\\Jetpack\\Status\\Host' ) && ( new Host() )->is_wpcom_platform() ) {
534            return true;
535        }
536
537        return (bool) get_option( self::VISIBILITY_OPTION, false );
538    }
539
540    /**
541     * Whether to offer an existing install the chance to opt into the new SEO experience.
542     *
543     * The single source of truth for the opt-in surfaces (legacy Traffic-page banner, My
544     * Jetpack card). True only when the SEO product is available (the {@see self::FEATURE_FILTER}
545     * flag is on) and the surface isn't visible yet — and since {@see self::is_seo_surface_visible()}
546     * already returns true for WordPress.com and for self-hosted installs that have opted in,
547     * "not visible" cleanly means "a self-hosted install that hasn't opted in".
548     *
549     * @return bool
550     */
551    public static function is_optin_available() {
552        return (bool) apply_filters( self::FEATURE_FILTER, false ) && ! self::is_seo_surface_visible();
553    }
554
555    /**
556     * Build the aggregated Overview state the dashboard renders.
557     *
558     * @return array
559     */
560    public static function get_overview_data() {
561        $modules = new Modules();
562        // @phan-suppress-next-line PhanUndeclaredClassMethod -- Jetpack_SEO_Utils lives in plugins/jetpack and is guarded by class_exists.
563        $seo_enabled = class_exists( 'Jetpack_SEO_Utils' ) && Jetpack_SEO_Utils::is_enabled_jetpack_seo();
564
565        $codes = get_option( 'verification_services_codes', array() );
566        if ( ! is_array( $codes ) ) {
567            $codes = array();
568        }
569
570        return array(
571            'site_visibility'   => array(
572                'search_engines_visible' => (int) get_option( 'blog_public', 1 ) === 1,
573                // Read the durable SEO option (seeded/synced from the `sitemaps` module
574                // by the Jetpack plugin) so the state survives the module's removal. The
575                // reachable sitemap URL + "View" link live on the Settings tab.
576                'sitemap_active'         => self::is_sitemap_enabled( $modules ),
577                'seo_tools_active'       => $modules->is_active( 'seo-tools' ),
578            ),
579            // Per-service booleans (a code is set or not) for the Overview's
580            // Site verification card.
581            'site_verification' => array(
582                'google'    => ! empty( $codes['google'] ),
583                'bing'      => ! empty( $codes['bing'] ),
584                'pinterest' => ! empty( $codes['pinterest'] ),
585                'yandex'    => ! empty( $codes['yandex'] ),
586                'facebook'  => ! empty( $codes['facebook'] ),
587            ),
588            'content_coverage'  => self::get_content_coverage(),
589            'plan'              => array(
590                'seo_enabled_for_site' => $seo_enabled,
591            ),
592        );
593    }
594
595    /**
596     * Post types the content-coverage counts span.
597     *
598     * @return string[]
599     */
600    private static function coverage_post_types() {
601        return array( 'post', 'page' );
602    }
603
604    /**
605     * The SEO post-meta keys the content-coverage counts read.
606     *
607     * @return string[]
608     */
609    private static function coverage_meta_keys() {
610        return array(
611            self::META_SCHEMA_TYPE,
612            self::META_TITLE,
613            self::META_DESCRIPTION,
614            self::META_NOINDEX,
615        );
616    }
617
618    /**
619     * Factual content-coverage counts for the Overview card: how many published
620     * posts/pages have each SEO field set. State, not a score — the card shows
621     * proportions + raw counts and lets the admin decide what matters.
622     *
623     * Served from {@see self::COVERAGE_COUNTS_TRANSIENT} when it's warm. The counts are read on
624     * every load of the SEO page — and by every tab of it, since the dashboard preloads
625     * all of its REST reads at once — so without a cache a plain reload pays for the
626     * query again having changed nothing.
627     *
628     * @return array{total:int,with_schema:int,with_title:int,with_description:int,with_search_visible:int}
629     */
630    private static function get_content_coverage() {
631        $cached = get_transient( self::COVERAGE_COUNTS_TRANSIENT );
632
633        if ( self::is_content_coverage( $cached ) ) {
634            return $cached;
635        }
636
637        $coverage = self::compute_content_coverage();
638
639        set_transient( self::COVERAGE_COUNTS_TRANSIENT, $coverage, self::COVERAGE_COUNTS_TTL );
640
641        return $coverage;
642    }
643
644    /**
645     * Whether a value read back from the cache is a coverage payload this code can use.
646     *
647     * @param mixed $value Value read from the transient.
648     * @return bool
649     */
650    private static function is_content_coverage( $value ) {
651        if ( ! is_array( $value ) ) {
652            return false;
653        }
654
655        foreach ( array( 'total', 'with_schema', 'with_title', 'with_description', 'with_search_visible' ) as $key ) {
656            if ( ! isset( $value[ $key ] ) || ! is_int( $value[ $key ] ) ) {
657                return false;
658            }
659        }
660
661        return true;
662    }
663
664    /**
665     * Count the coverage metrics straight from the database.
666     *
667     * @return array{total:int,with_schema:int,with_title:int,with_description:int,with_search_visible:int}
668     */
669    private static function compute_content_coverage() {
670        global $wpdb;
671
672        $post_types = self::coverage_post_types();
673        $meta_keys  = self::coverage_meta_keys();
674
675        $meta_key_placeholders  = implode( ', ', array_fill( 0, count( $meta_keys ), '%s' ) );
676        $post_type_placeholders = implode( ', ', array_fill( 0, count( $post_types ), '%s' ) );
677
678        /*
679         * Driven from `wp_postmeta`, not `wp_posts`: most sites have far more published
680         * posts than SEO fields set, so the join starts from the small side, where the
681         * `meta_key` index serves `meta_key IN (…)` directly.
682         *
683         * The aggregate has no GROUP BY, so it still returns its single row — counts at
684         * zero, `total` intact — on a site with no SEO meta at all.
685         *
686         * COUNT( DISTINCT p.ID ) because a post can carry more than one row for the same
687         * meta key. `<> ''` counts a field as set; noindex alone is an exact `= '1'`.
688         */
689        // phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber
690        $sql = $wpdb->prepare(
691            "SELECT
692                (
693                    SELECT COUNT(*)
694                    FROM {$wpdb->posts}
695                    WHERE post_status = 'publish' AND post_type IN ( {$post_type_placeholders} )
696                ) AS total,
697                COUNT( DISTINCT CASE WHEN pm.meta_key = %s AND pm.meta_value <> '' THEN p.ID END ) AS with_schema,
698                COUNT( DISTINCT CASE WHEN pm.meta_key = %s AND pm.meta_value <> '' THEN p.ID END ) AS with_title,
699                COUNT( DISTINCT CASE WHEN pm.meta_key = %s AND pm.meta_value <> '' THEN p.ID END ) AS with_description,
700                COUNT( DISTINCT CASE WHEN pm.meta_key = %s AND pm.meta_value = '1' THEN p.ID END ) AS noindexed
701            FROM {$wpdb->postmeta} pm
702            INNER JOIN {$wpdb->posts} p
703                ON p.ID = pm.post_id
704                AND p.post_status = 'publish'
705                AND p.post_type IN ( {$post_type_placeholders} )
706            WHERE pm.meta_key IN ( {$meta_key_placeholders} )",
707            array_merge(
708                $post_types,
709                // The CASE arms above, in the order they appear.
710                array( self::META_SCHEMA_TYPE, self::META_TITLE, self::META_DESCRIPTION, self::META_NOINDEX ),
711                $post_types,
712                $meta_keys
713            )
714        );
715        // phpcs:enable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber
716
717        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.NotPrepared -- Aggregate count with no core API equivalent; $sql is the prepared statement built directly above. The result is cached in self::COVERAGE_COUNTS_TRANSIENT by the get_content_coverage() wrapper, which is the only caller — the sniff just can't see across the two methods.
718        $row = $wpdb->get_row( $sql, ARRAY_A );
719
720        // Defaults, so a query that returns nothing at all reads as an empty site rather
721        // than fataling on a missing key.
722        $counts = array_map(
723            'intval',
724            array_merge(
725                array(
726                    'total'            => 0,
727                    'with_schema'      => 0,
728                    'with_title'       => 0,
729                    'with_description' => 0,
730                    'noindexed'        => 0,
731                ),
732                is_array( $row ) ? $row : array()
733            )
734        );
735
736        return array(
737            'total'               => $counts['total'],
738            'with_schema'         => $counts['with_schema'],
739            'with_title'          => $counts['with_title'],
740            'with_description'    => $counts['with_description'],
741            // Search-engine visibility is the inverse of the per-post noindex meta: a
742            // post is visible unless it's explicitly set to noindex (stored as '1'), so
743            // most posts (no meta row) count as visible.
744            'with_search_visible' => max( 0, $counts['total'] - $counts['noindexed'] ),
745        );
746    }
747
748    /**
749     * Hook the writes that can move the content-coverage counts.
750     *
751     * @return void
752     */
753    public static function register_coverage_invalidation() {
754        // Covers publish, unpublish, trash, untrash and scheduled posts going live — every
755        // route by which a post enters or leaves the published set.
756        add_action( 'transition_post_status', array( __CLASS__, 'invalidate_content_coverage_on_status_change' ), 10, 3 );
757        add_action( 'deleted_post', array( __CLASS__, 'invalidate_content_coverage_on_delete' ), 10, 2 );
758
759        foreach ( array( 'added_post_meta', 'updated_post_meta', 'deleted_post_meta' ) as $hook ) {
760            add_action( $hook, array( __CLASS__, 'invalidate_content_coverage_on_meta_change' ), 10, 3 );
761        }
762    }
763
764    /**
765     * Drop the cached counts when a post enters or leaves the published set.
766     *
767     * Known limitation: this hook only ever sees the post's new type, so converting a
768     * published post to an uncounted post type (or the reverse) isn't caught here and
769     * leaves `total` stale until the next tracked write or the transient's TTL expiry.
770     * A direct `set_post_type()` bypasses every hook anyway, so the TTL backstop is what
771     * ultimately bounds that staleness.
772     *
773     * @param string        $new_status Status the post is moving to.
774     * @param string        $old_status Status the post is moving from.
775     * @param \WP_Post|null $post       The post being transitioned.
776     * @return void
777     */
778    public static function invalidate_content_coverage_on_status_change( $new_status, $old_status, $post ) {
779        if ( ! $post instanceof \WP_Post || ! in_array( $post->post_type, self::coverage_post_types(), true ) ) {
780            return;
781        }
782
783        // Draft to draft, pending to draft, and the like never touch the counts.
784        if ( 'publish' !== $new_status && 'publish' !== $old_status ) {
785            return;
786        }
787
788        self::invalidate_content_coverage();
789    }
790
791    /**
792     * Drop the cached counts when a post is deleted outright.
793     *
794     * Trashing already goes through `transition_post_status`; this catches a hard delete,
795     * which for an already-trashed post transitions nothing.
796     *
797     * @param int           $post_id Deleted post ID.
798     * @param \WP_Post|null $post    The post that was deleted.
799     * @return void
800     */
801    public static function invalidate_content_coverage_on_delete( $post_id, $post = null ) {
802        if ( ! $post instanceof \WP_Post || ! in_array( $post->post_type, self::coverage_post_types(), true ) ) {
803            return;
804        }
805
806        self::invalidate_content_coverage();
807    }
808
809    /**
810     * Drop the cached counts when one of the SEO fields they count is written.
811     *
812     * @param int|int[] $meta_id   Meta row ID, or IDs on delete. Unused.
813     * @param int       $object_id Post the meta belongs to. Unused.
814     * @param string    $meta_key  Meta key written.
815     * @return void
816     */
817    public static function invalidate_content_coverage_on_meta_change( $meta_id, $object_id, $meta_key ) {
818        if ( ! in_array( $meta_key, self::coverage_meta_keys(), true ) ) {
819            return;
820        }
821
822        self::invalidate_content_coverage();
823    }
824
825    /**
826     * Drop the cached counts.
827     *
828     * @return void
829     */
830    private static function invalidate_content_coverage() {
831        delete_transient( self::COVERAGE_COUNTS_TRANSIENT );
832    }
833
834    /**
835     * Site identity used to render the homepage search/social previews on the
836     * Settings tab: title, tagline, URL, and representative images. The front-page
837     * description that completes the preview is read from the Settings form
838     * (it's editable there), not bootstrapped here.
839     *
840     * @return array
841     */
842    public static function get_site_data() {
843        $icon_url = (string) get_site_icon_url();
844
845        $logo_id  = (int) get_theme_mod( 'custom_logo' );
846        $logo_url = $logo_id ? (string) wp_get_attachment_image_url( $logo_id, 'full' ) : '';
847
848        return array(
849            'title'   => (string) get_bloginfo( 'name' ),
850            'tagline' => (string) get_bloginfo( 'description' ),
851            'url'     => (string) home_url(),
852            'icon'    => $icon_url,
853            'image'   => $logo_url ? $logo_url : $icon_url,
854        );
855    }
856
857    /**
858     * Expose the core `blog_public` option to the REST settings endpoint.
859     *
860     * Search-engine visibility is a WordPress core option, not a Jetpack one,
861     * so the Settings tab saves it through `/wp/v2/settings` — which only
862     * round-trips settings registered with `show_in_rest`. The core settings
863     * controller enforces the `manage_options` capability on writes.
864     *
865     * @return void
866     */
867    public static function register_rest_settings() {
868        register_setting(
869            'reading',
870            'blog_public',
871            array(
872                'show_in_rest' => true,
873                'type'         => 'integer',
874                'default'      => 1,
875            )
876        );
877    }
878
879    /**
880     * Register the opt-in REST route that switches an existing self-hosted install over to
881     * the new SEO experience.
882     *
883     * Lives on the `jetpack/v4` namespace and is registered ahead of the cohort gate, so a
884     * site whose SEO surface is still hidden can reach it from the legacy Traffic page or
885     * My Jetpack. See {@see self::handle_optin()}.
886     *
887     * @return void
888     */
889    public static function register_optin_route() {
890        register_rest_route(
891            'jetpack/v4',
892            '/seo/opt-in',
893            array(
894                'methods'             => \WP_REST_Server::CREATABLE,
895                'callback'            => array( __CLASS__, 'handle_optin' ),
896                'permission_callback' => function () {
897                    return current_user_can( 'manage_options' );
898                },
899            )
900        );
901    }
902
903    /**
904     * Opt an existing install into the new SEO experience: mark the surface visible and
905     * activate the `seo-tools` module, then hand back the dashboard URL to redirect to.
906     *
907     * Idempotent — re-opting-in is harmless. `Modules::activate()` is called with
908     * `$exit = false, $redirect = false`; the defaults would `exit()` and send a 302,
909     * which break a REST response.
910     *
911     * @return \WP_REST_Response
912     */
913    public static function handle_optin() {
914        update_option( self::VISIBILITY_OPTION, true );
915
916        if ( class_exists( 'Automattic\\Jetpack\\Modules' ) ) {
917            ( new Modules() )->activate( 'seo-tools', false, false );
918        }
919
920        return rest_ensure_response(
921            array(
922                'success'  => true,
923                'redirect' => admin_url( 'admin.php?page=' . self::MENU_SLUG ),
924            )
925        );
926    }
927
928    /**
929     * Map of read-only dashboard routes: tab slug => data-builder callable. The
930     * single source of truth for both the registered routes and the paths
931     * preloaded onto the page, so the two can't drift.
932     *
933     * @return array<string, callable>
934     */
935    private static function rest_reads() {
936        return array(
937            'overview' => array( __CLASS__, 'get_overview_data' ),
938            'settings' => array( __CLASS__, 'get_settings_data' ),
939            'ai'       => array( __CLASS__, 'get_ai_data' ),
940        );
941    }
942
943    /**
944     * REST paths the dashboard reads its initial state from, preloaded into the
945     * page (see {@see self::inject_script_data()}) and fetched by the app.
946     *
947     * @return string[]
948     */
949    private static function rest_read_paths() {
950        return array_map(
951            static function ( $slug ) {
952                return '/jetpack/v4/seo/' . $slug;
953            },
954            array_keys( self::rest_reads() )
955        );
956    }
957
958    /**
959     * Register the read-only REST routes the dashboard hydrates from — one per
960     * data-backed tab, each returning the same builder payload previously injected
961     * synchronously onto the page. Read-only and gated to the page's own
962     * `manage_options`; writes still go through their existing endpoints.
963     *
964     * @return void
965     */
966    public static function register_rest_reads() {
967        foreach ( self::rest_reads() as $slug => $builder ) {
968            register_rest_route(
969                'jetpack/v4',
970                '/seo/' . $slug,
971                array(
972                    'methods'             => \WP_REST_Server::READABLE,
973                    'callback'            => static function () use ( $builder ) {
974                        return rest_ensure_response( call_user_func( $builder ) );
975                    },
976                    'permission_callback' => array( __CLASS__, 'reads_permission_check' ),
977                )
978            );
979        }
980    }
981
982    /**
983     * Capability gate for the dashboard's read routes — the same `manage_options`
984     * the SEO admin page itself requires.
985     *
986     * @return bool
987     */
988    public static function reads_permission_check() {
989        return current_user_can( 'manage_options' );
990    }
991
992    /**
993     * Build the editable Settings state the Settings tab hydrates from.
994     *
995     * Read-only bootstrap only. Most writes go through the existing
996     * `/jetpack/v4/settings` REST endpoint, which already validates and
997     * sanitizes those flat fields. Nested Schema writes use the package's
998     * schema-settings route; bootstrapping them here keeps the Settings UI
999     * hydrated without a second request.
1000     *
1001     * @return array
1002     */
1003    public static function get_settings_data() {
1004        $modules = new Modules();
1005
1006        // @phan-suppress-next-line PhanUndeclaredClassMethod -- Jetpack_SEO_Titles lives in plugins/jetpack and is guarded by class_exists.
1007        $title_formats = class_exists( 'Jetpack_SEO_Titles' ) ? Jetpack_SEO_Titles::get_custom_title_formats() : array();
1008        // @phan-suppress-next-line PhanUndeclaredClassMethod -- Jetpack_SEO_Utils lives in plugins/jetpack and is guarded by class_exists.
1009        $front_page_desc = class_exists( 'Jetpack_SEO_Utils' ) ? Jetpack_SEO_Utils::get_front_page_meta_description() : '';
1010
1011        $codes = get_option( 'verification_services_codes', array() );
1012        if ( ! is_array( $codes ) ) {
1013            $codes = array();
1014        }
1015
1016        $sitemap_active = self::is_sitemap_enabled( $modules );
1017
1018        return array(
1019            'search_engines_visible' => (int) get_option( 'blog_public', 1 ) === 1,
1020            // Read the durable SEO option (seeded/synced from the `sitemaps` module
1021            // by the Jetpack plugin) so the state survives the module's removal.
1022            'sitemap_active'         => $sitemap_active,
1023            // Empty until the sitemap is genuinely reachable, so the Settings tab can
1024            // link to it only once it won't 404 (it's built by cron after activation).
1025            'sitemap_url'            => self::get_reachable_sitemap_url( $sitemap_active ),
1026            // Read the durable SEO option (seeded/synced from the `canonical-urls` module
1027            // by the Jetpack plugin) so the state survives the module's removal.
1028            'canonical_active'       => self::is_canonical_enabled( $modules ),
1029            // Cast to object so an empty format set serializes as `{}`, not `[]`.
1030            'title_formats'          => (object) $title_formats,
1031            'front_page_description' => (string) $front_page_desc,
1032            'verification'           => array(
1033                'google'    => isset( $codes['google'] ) ? (string) $codes['google'] : '',
1034                'bing'      => isset( $codes['bing'] ) ? (string) $codes['bing'] : '',
1035                'pinterest' => isset( $codes['pinterest'] ) ? (string) $codes['pinterest'] : '',
1036                'yandex'    => isset( $codes['yandex'] ) ? (string) $codes['yandex'] : '',
1037                'facebook'  => isset( $codes['facebook'] ) ? (string) $codes['facebook'] : '',
1038            ),
1039            'schema'                 => Schema_Settings::get_editable(),
1040        );
1041    }
1042
1043    /**
1044     * Build the Google site-verification state for the Settings tab.
1045     *
1046     * The Settings verification card lets a connected user verify with Google via a
1047     * WordPress.com keyring OAuth popup (in addition to pasting a meta-tag code). This
1048     * bootstraps the keyring connect URL and whether the current user is connected —
1049     * the live verified status is fetched client-side from `/jetpack/v4/verify-site/google`
1050     * (a wpcom round-trip we don't want to make on every page load).
1051     *
1052     * Both `Keyring_Helper` (Publicize package) and the connection `Manager` are provided
1053     * by the host Jetpack plugin, so they're guarded with `class_exists` like the
1054     * `Jetpack_SEO_*` helpers. On a disconnected self-hosted site `is_connected` is false
1055     * and the UI falls back to manual code entry only.
1056     *
1057     * @return array
1058     */
1059    public static function get_google_verify_data() {
1060        $connect_url = '';
1061        if ( class_exists( 'Automattic\\Jetpack\\Publicize\\Keyring_Helper' ) ) {
1062            // @phan-suppress-next-line PhanUndeclaredClassMethod -- guarded; Publicize package is provided by the host plugin.
1063            $connect_url = (string) \Automattic\Jetpack\Publicize\Keyring_Helper::connect_url( 'google_site_verification', 'other' );
1064        }
1065
1066        $is_connected = false;
1067        if ( class_exists( 'Automattic\\Jetpack\\Connection\\Manager' ) ) {
1068            // @phan-suppress-next-line PhanUndeclaredClassMethod -- guarded; Connection package is provided by the host plugin.
1069            $is_connected = ( new \Automattic\Jetpack\Connection\Manager() )->is_user_connected();
1070        }
1071
1072        return array(
1073            'connect_url'  => $connect_url,
1074            'is_connected' => (bool) $is_connected,
1075        );
1076    }
1077
1078    /**
1079     * Build the AI tab's initial state.
1080     *
1081     * The AI SEO Enhancer auto-generates SEO titles/descriptions/alt-text in the
1082     * editor (the generation itself is wpcom/AI-Assistant side); this exposes only
1083     * its persisted on/off toggle and whether it's available. Availability mirrors
1084     * the legacy Traffic page: the `ai_seo_enhancer_enabled` feature filter must be
1085     * on (it still depends on AI being available) AND the site's plan must support
1086     * the `ai-seo-enhancer` feature. The toggle writes through the existing
1087     * `/jetpack/v4/settings` endpoint (`ai_seo_enhancer_enabled`).
1088     *
1089     * @return array
1090     */
1091    public static function get_ai_data() {
1092        $filter_on = (bool) apply_filters( 'ai_seo_enhancer_enabled', true );
1093
1094        // Current_Plan is provided by the host Jetpack plugin, not a package
1095        // dependency — guard like the Jetpack_SEO_* helpers above.
1096        $plan_supports = class_exists( 'Automattic\\Jetpack\\Current_Plan' )
1097            // @phan-suppress-next-line PhanUndeclaredClassMethod -- guarded by class_exists; host plugin provides the class.
1098            && \Automattic\Jetpack\Current_Plan::supports( 'ai-seo-enhancer' );
1099
1100        return array(
1101            'enhancer' => array(
1102                'available' => $filter_on && $plan_supports,
1103                'enabled'   => (bool) get_option( 'ai_seo_enhancer_enabled', false ),
1104            ),
1105        );
1106    }
1107}