Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
57.60%
144 / 250
31.03%
9 / 29
 CRAP
0.00%
0 / 1
Initializer
57.60%
144 / 250
31.03%
9 / 29
 503.77
0.00%
0 / 1
 init
81.25%
13 / 16
0.00%
0 / 1
 5.16
 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
 get_content_coverage
100.00%
13 / 13
100.00%
1 / 1
 3
 count_published_with_meta
100.00%
22 / 22
100.00%
1 / 1
 2
 get_site_data
100.00%
9 / 9
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.45%
21 / 22
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.3.1';
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     * Whether the package has been initialized.
131     *
132     * @var bool
133     */
134    private static $initialized = false;
135
136    /**
137     * Initialize the package.
138     *
139     * Called from the Jetpack plugin's `late_initialization()` hook.
140     *
141     * @return void
142     */
143    public static function init() {
144        if ( self::$initialized ) {
145            return;
146        }
147        self::$initialized = true;
148
149        // Gate the entire SEO surface behind the feature flag.
150        if ( ! (bool) apply_filters( self::FEATURE_FILTER, false ) ) {
151            return;
152        }
153
154        // The opt-in endpoint must be reachable even before the surface is visible, so
155        // existing self-hosted installs can switch to the new experience from the legacy
156        // Traffic page or My Jetpack (JETPACK-1700). Registered ahead of the cohort gate.
157        add_action( 'rest_api_init', array( __CLASS__, 'register_optin_route' ) );
158
159        // Expose opt-in availability to other admin surfaces (the legacy Traffic-page
160        // banner reads it via `@automattic/jetpack-script-data`). Hooked here — after the
161        // feature flag, before the cohort gate — so a still-hidden install gets the signal.
162        add_filter( 'jetpack_admin_js_script_data', array( __CLASS__, 'inject_optin_availability' ) );
163
164        // Discoverability cohort gate: the SEO surface is auto-discoverable for fresh
165        // installs and all WordPress.com sites; existing self-hosted installs opt in via
166        // the legacy Traffic page or My Jetpack (JETPACK-1700). Until it's visible we
167        // register nothing else here and let those opt-in surfaces drive discovery.
168        if ( ! self::is_seo_surface_visible() ) {
169            return;
170        }
171
172        // The admin menu and app shell register whenever the surface is visible, even
173        // when the `seo-tools` module is inactive, so SEO stays discoverable and can be
174        // turned on from within the page itself (JETPACK-1700). When the module is off,
175        // the Overview renders only its "enable SEO tools" affordance.
176        //
177        // Priority 1: load the wp-build bundle (and define its render function)
178        // before `add_menu_item()` runs at the default priority and needs it.
179        add_action( 'admin_menu', array( __CLASS__, 'maybe_load_wp_build' ), 1 );
180        add_action( 'admin_menu', array( __CLASS__, 'add_menu_item' ), 10 );
181
182        // Read-only REST routes the dashboard hydrates its initial state from. Preloaded
183        // into the page (see inject_script_data) so a normal load resolves them with no
184        // request, and fetched by the app when that preload is missing or stale — so the
185        // dashboard recovers its data instead of dead-ending. Registered whenever the
186        // surface is visible (independent of the seo-tools module, like the Overview).
187        add_action( 'rest_api_init', array( __CLASS__, 'register_rest_reads' ) );
188
189        // The settings surface only comes online once SEO tools are active — there's
190        // nothing to configure while the module is off, so we don't register its REST
191        // endpoints until then. Expose the core `blog_public` option to the REST settings
192        // endpoint so the Settings tab can save search-engine visibility via
193        // `/wp/v2/settings` (the Jetpack settings endpoint only accepts Jetpack options).
194        // Writes are still capability-gated by the core settings controller.
195        if ( self::is_seo_tools_module_active() ) {
196            // Front-end JSON-LD schema (Article / FAQ). Self-hooks `wp_head`, so it only
197            // emits on front-end requests.
198            Schema_Builder::init();
199            add_action( 'rest_api_init', array( __CLASS__, 'register_rest_settings' ) );
200        }
201
202        /**
203         * Fires after the Jetpack SEO package is initialized.
204         *
205         * @since 0.1.0
206         */
207        do_action( 'jetpack_seo_init' );
208    }
209
210    /**
211     * Register the admin menu item.
212     *
213     * Uses Admin_Menu so the page is reachable on wp-admin across all site
214     * types. The render callback is wp-build's generated render function when
215     * the bundle is loaded (i.e. on the SEO page itself, after
216     * `maybe_load_wp_build()` ran at priority 1); otherwise it falls back to a
217     * bare mount node so the page never fatals on an unbuilt checkout.
218     *
219     * @return void
220     */
221    public static function add_menu_item() {
222        $callback = function_exists( self::WP_BUILD_RENDER_FN )
223            ? self::WP_BUILD_RENDER_FN
224            : array( __CLASS__, 'render_fallback' );
225
226        Admin_Menu::add_menu(
227            'SEO',
228            'SEO',
229            'manage_options',
230            self::MENU_SLUG,
231            $callback,
232            2
233        );
234    }
235
236    /**
237     * On the SEO admin page, load the wp-build bundle, alias the screen id so
238     * wp-build enqueues its assets, and bootstrap the app's initial state.
239     *
240     * Hooked at `admin_menu` priority 1 so polyfills register and the render
241     * function is defined before `add_menu_item()` runs at priority 10.
242     *
243     * @return void
244     */
245    public static function maybe_load_wp_build() {
246        if ( ! self::is_seo_admin_request() ) {
247            return;
248        }
249
250        self::load_wp_build();
251        add_action( 'current_screen', array( __CLASS__, 'alias_screen_id_for_wp_build' ) );
252        add_filter( 'jetpack_admin_js_script_data', array( __CLASS__, 'inject_script_data' ) );
253    }
254
255    /**
256     * Load wp-build's generated registration file and register the polyfills
257     * the bundle depends on. No-op on a fresh checkout before `pnpm build`, in
258     * which case `add_menu_item()` falls back to {@see self::render_fallback()}.
259     *
260     * @return void
261     */
262    private static function load_wp_build() {
263        $build_index = dirname( __DIR__ ) . '/build/build.php';
264
265        if ( ! file_exists( $build_index ) ) {
266            return;
267        }
268
269        require_once $build_index;
270
271        WP_Build_Polyfills::register(
272            'jetpack-seo',
273            array_merge( WP_Build_Polyfills::SCRIPT_HANDLES, WP_Build_Polyfills::MODULE_IDS )
274        );
275    }
276
277    /**
278     * Alias the current screen id to wp-build's expected slug so its
279     * auto-generated enqueue callback fires for our user-facing page.
280     *
281     * @param \WP_Screen|null $screen The current screen object (passed by WP).
282     * @return void
283     */
284    public static function alias_screen_id_for_wp_build( $screen ) {
285        if ( ! is_object( $screen ) ) {
286            return;
287        }
288
289        $screen->id = self::WP_BUILD_SLUG;
290    }
291
292    /**
293     * Bootstrap the React app's initial state onto `window.JetpackScriptData.seo`.
294     *
295     * Because wp-build pages load as ES modules, `wp_localize_script` can't
296     * attach data to them; the shared `jetpack_admin_js_script_data` filter
297     * (printed by the Script_Data package onto the `jetpack-script-data` handle
298     * the bundle already depends on) is the supported channel. The per-tab state
299     * is provided as an apiFetch *preload* (mirrors Podcast) so the app resolves
300     * it with no request on a normal load yet can re-fetch when the preload is
301     * missing or stale, rather than dead-ending on a one-shot read.
302     *
303     * @param array $data Script data being injected onto the page.
304     * @return array
305     */
306    public static function inject_script_data( $data ) {
307        if ( ! is_array( $data ) ) {
308            $data = array();
309        }
310
311        // Preload the dashboard's REST reads into the page so the app resolves them from
312        // cache on first paint with no network request — while still being able to
313        // re-fetch if that preload is ever missing or stale. This replaces injecting the
314        // raw payloads, which the app read synchronously once and couldn't recover from
315        // when momentarily absent (the load-error dead-end). See register_rest_reads() and
316        // the client readers `_inc/data/get-preloaded.ts` + `_inc/data/use-ensure-tab-data.ts`.
317        $data[ self::SCRIPT_DATA_KEY ]['preload'] = array_reduce(
318            self::rest_read_paths(),
319            'rest_preload_api_request',
320            array()
321        );
322
323        // Small synchronous reads used outside the per-tab data stores, and not part of
324        // the load-error path.
325        $data[ self::SCRIPT_DATA_KEY ]['google_verify'] = self::get_google_verify_data();
326        $data[ self::SCRIPT_DATA_KEY ]['site']          = self::get_site_data();
327
328        return $data;
329    }
330
331    /**
332     * Expose whether this install should be offered the SEO opt-in, onto
333     * `window.JetpackScriptData.seo.optin_available` for other admin surfaces (e.g. the
334     * legacy Traffic-page banner). Only hooked when the feature flag is on, so the field is
335     * simply absent otherwise.
336     *
337     * @param array $data Script data being injected onto the page.
338     * @return array
339     */
340    public static function inject_optin_availability( $data ) {
341        if ( ! is_array( $data ) ) {
342            $data = array();
343        }
344
345        $data[ self::SCRIPT_DATA_KEY ]['optin_available'] = self::is_optin_available();
346        // Read by the legacy Traffic page to hide its SEO / Sitemaps sections once the
347        // site is on the new experience (fresh install / opted-in / WordPress.com), so the
348        // two surfaces never show at once. The legacy sections stay for self-hosted installs
349        // that haven't opted in.
350        $data[ self::SCRIPT_DATA_KEY ]['surface_visible'] = self::is_seo_surface_visible();
351
352        return $data;
353    }
354
355    /**
356     * Fallback render used when the wp-build artifact is missing (unbuilt
357     * checkout). Renders a bare wrapper so the page loads without the app.
358     *
359     * @return void
360     */
361    public static function render_fallback() {
362        echo '<div class="wrap"><h1>SEO</h1></div>';
363    }
364
365    /**
366     * Whether the current request targets the SEO admin page.
367     *
368     * @return bool
369     */
370    private static function is_seo_admin_request() {
371        // phpcs:ignore WordPress.Security.NonceVerification.Recommended
372        if ( ! is_admin() || ! isset( $_GET['page'] ) ) {
373            return false;
374        }
375
376        // phpcs:ignore WordPress.Security.NonceVerification.Recommended
377        return self::MENU_SLUG === sanitize_text_field( wp_unslash( $_GET['page'] ) );
378    }
379
380    /**
381     * Whether the `seo-tools` Jetpack module is currently active.
382     *
383     * @return bool
384     */
385    private static function is_seo_tools_module_active() {
386        if ( ! class_exists( 'Automattic\\Jetpack\\Modules' ) ) {
387            return false;
388        }
389        return ( new Modules() )->is_active( 'seo-tools' );
390    }
391
392    /**
393     * Whether sitemap generation is enabled.
394     *
395     * Reads the durable {@see self::SITEMAP_ENABLED_OPTION} flag. The default is only
396     * used when the option is absent (for example before the Jetpack plugin's migration
397     * has run on a freshly upgraded site), in which case it falls back to the live
398     * `sitemaps` module state so behavior is unchanged in that gap.
399     *
400     * @param Modules $modules Modules instance to read live module state from.
401     * @return bool
402     */
403    private static function is_sitemap_enabled( Modules $modules ) {
404        $enabled = get_option( self::SITEMAP_ENABLED_OPTION, null );
405
406        // Only fall back to the live module state when the durable option is absent.
407        // Passing it as get_option()'s default would evaluate it on every call, since
408        // PHP resolves function arguments eagerly even when the option exists.
409        if ( null === $enabled ) {
410            $enabled = $modules->is_active( 'sitemaps' );
411        }
412
413        return (bool) $enabled;
414    }
415
416    /**
417     * The public URL of the generated XML sitemap, or an empty string when none
418     * is currently reachable.
419     *
420     * A sitemap is only reachable when generation is enabled, the site is public
421     * (Jetpack does not load the Sitemaps module on sites that discourage search
422     * engines), and the master sitemap has actually been generated — the Jetpack
423     * plugin builds it via cron 1–15 minutes after activation, so the URL 404s
424     * until then. Callers treat an empty string as "not yet reachable" and skip
425     * linking to it.
426     *
427     * {@see Jetpack_Sitemap_Librarian} and jetpack_sitemap_uri() live in the
428     * Jetpack plugin's Sitemaps module (loaded only for an active module on a
429     * public site), so both are guarded; in the package-only context they are
430     * absent and the sitemap is reported as not reachable.
431     *
432     * @param bool $sitemap_active Whether sitemap generation is enabled.
433     * @return string The sitemap URL, or '' when not reachable.
434     */
435    private static function get_reachable_sitemap_url( $sitemap_active ) {
436        // Jetpack only serves sitemaps when generation is on and the site is public.
437        if ( ! $sitemap_active || (int) get_option( 'blog_public', 1 ) !== 1 ) {
438            return '';
439        }
440
441        // The Sitemaps module (the librarian class, the `JP_MASTER_SITEMAP_TYPE`
442        // constant, and the `jp_sitemap_filename()` / `jetpack_sitemap_uri()`
443        // helpers) all live together in plugins/jetpack and load as a unit, so this
444        // single guard covers every symbol used below.
445        if (
446            ! class_exists( 'Jetpack_Sitemap_Librarian' )
447            || ! defined( 'JP_MASTER_SITEMAP_TYPE' )
448            || ! function_exists( 'jp_sitemap_filename' )
449            || ! function_exists( 'jetpack_sitemap_uri' )
450        ) {
451            return '';
452        }
453
454        // The master sitemap is stored as a post once the cron generation run
455        // completes; until then there is nothing to link to.
456        // `jp_sitemap_filename( JP_MASTER_SITEMAP_TYPE )` is the master file name
457        // ('sitemap.xml'); inlined so this stays one (untestable-in-package) line.
458        // @phan-suppress-next-line PhanUndeclaredFunction,PhanUndeclaredClassMethod -- guarded above; symbols live in plugins/jetpack.
459        $master = ( new Jetpack_Sitemap_Librarian() )->read_sitemap_data( jp_sitemap_filename( JP_MASTER_SITEMAP_TYPE ), JP_MASTER_SITEMAP_TYPE );
460        if ( null === $master ) {
461            return '';
462        }
463
464        // esc_url_raw (not esc_url): the value is transported via script data and
465        // rendered by React, so it must not be HTML-entity-encoded (e.g. the
466        // plain-permalink `?jetpack-sitemap=` form keeps its raw `&`).
467        // @phan-suppress-next-line PhanUndeclaredFunction -- jp_sitemap_filename()/jetpack_sitemap_uri() live in plugins/jetpack, guarded by function_exists.
468        return esc_url_raw( (string) jetpack_sitemap_uri( jp_sitemap_filename( JP_MASTER_SITEMAP_TYPE ) ) );
469    }
470
471    /**
472     * Whether canonical URLs are enabled.
473     *
474     * Reads the durable {@see self::CANONICAL_ENABLED_OPTION} flag. The default is only
475     * used when the option is absent (for example before the Jetpack plugin's migration
476     * has run on a freshly upgraded site), in which case it falls back to the live
477     * `canonical-urls` module state so behavior is unchanged in that gap.
478     *
479     * @param Modules $modules Modules instance to read live module state from.
480     * @return bool
481     */
482    private static function is_canonical_enabled( Modules $modules ) {
483        $enabled = get_option( self::CANONICAL_ENABLED_OPTION, null );
484
485        // Only fall back to the live module state when the durable option is absent.
486        // Passing it as get_option()'s default would evaluate it on every call, since
487        // PHP resolves function arguments eagerly even when the option exists.
488        if ( null === $enabled ) {
489            $enabled = $modules->is_active( 'canonical-urls' );
490        }
491
492        return (bool) $enabled;
493    }
494
495    /**
496     * Whether the Jetpack SEO surface should be discoverable (admin menu registered).
497     *
498     * WordPress.com sites (Simple + Atomic) are always discoverable — how SEO presents
499     * there is a Dotcom decision, independent of the self-hosted rollout. On self-hosted
500     * sites the durable {@see self::VISIBILITY_OPTION} cohort flag decides: fresh installs
501     * are seeded visible, existing installs stay hidden until they opt in. Defaults to
502     * hidden when the option is absent (e.g. before the plugin's seed has run), so an
503     * existing site is never surprised by the new surface before its cohort is recorded.
504     *
505     * @return bool
506     */
507    public static function is_seo_surface_visible() {
508        if ( class_exists( 'Automattic\\Jetpack\\Status\\Host' ) && ( new Host() )->is_wpcom_platform() ) {
509            return true;
510        }
511
512        return (bool) get_option( self::VISIBILITY_OPTION, false );
513    }
514
515    /**
516     * Whether to offer an existing install the chance to opt into the new SEO experience.
517     *
518     * The single source of truth for the opt-in surfaces (legacy Traffic-page banner, My
519     * Jetpack card). True only when the SEO product is available (the {@see self::FEATURE_FILTER}
520     * flag is on) and the surface isn't visible yet — and since {@see self::is_seo_surface_visible()}
521     * already returns true for WordPress.com and for self-hosted installs that have opted in,
522     * "not visible" cleanly means "a self-hosted install that hasn't opted in".
523     *
524     * @return bool
525     */
526    public static function is_optin_available() {
527        return (bool) apply_filters( self::FEATURE_FILTER, false ) && ! self::is_seo_surface_visible();
528    }
529
530    /**
531     * Build the aggregated Overview state the dashboard renders.
532     *
533     * @return array
534     */
535    public static function get_overview_data() {
536        $modules = new Modules();
537        // @phan-suppress-next-line PhanUndeclaredClassMethod -- Jetpack_SEO_Utils lives in plugins/jetpack and is guarded by class_exists.
538        $seo_enabled = class_exists( 'Jetpack_SEO_Utils' ) && Jetpack_SEO_Utils::is_enabled_jetpack_seo();
539
540        $codes = get_option( 'verification_services_codes', array() );
541        if ( ! is_array( $codes ) ) {
542            $codes = array();
543        }
544
545        return array(
546            'site_visibility'   => array(
547                'search_engines_visible' => (int) get_option( 'blog_public', 1 ) === 1,
548                // Read the durable SEO option (seeded/synced from the `sitemaps` module
549                // by the Jetpack plugin) so the state survives the module's removal. The
550                // reachable sitemap URL + "View" link live on the Settings tab.
551                'sitemap_active'         => self::is_sitemap_enabled( $modules ),
552                'seo_tools_active'       => $modules->is_active( 'seo-tools' ),
553            ),
554            // Per-service booleans (a code is set or not) for the Overview's
555            // Site verification card.
556            'site_verification' => array(
557                'google'    => ! empty( $codes['google'] ),
558                'bing'      => ! empty( $codes['bing'] ),
559                'pinterest' => ! empty( $codes['pinterest'] ),
560                'yandex'    => ! empty( $codes['yandex'] ),
561                'facebook'  => ! empty( $codes['facebook'] ),
562            ),
563            'content_coverage'  => self::get_content_coverage(),
564            'plan'              => array(
565                'seo_enabled_for_site' => $seo_enabled,
566            ),
567        );
568    }
569
570    /**
571     * Factual content-coverage counts for the Overview card: how many published
572     * posts/pages have each SEO field set. State, not a score — the card shows
573     * proportions + raw counts and lets the admin decide what matters.
574     *
575     * @return array{total:int,with_schema:int,with_title:int,with_description:int,with_search_visible:int}
576     */
577    private static function get_content_coverage() {
578        $post_types = array( 'post', 'page' );
579
580        $total = 0;
581        foreach ( $post_types as $post_type ) {
582            $counts = wp_count_posts( $post_type );
583            $total += isset( $counts->publish ) ? (int) $counts->publish : 0;
584        }
585
586        // Search-engine visibility is the inverse of the per-post noindex meta: a
587        // post is visible unless it's explicitly set to noindex (stored as '1'), so
588        // most posts (no meta row) count as visible.
589        $noindexed = self::count_published_with_meta( $post_types, self::META_NOINDEX, '1' );
590
591        return array(
592            'total'               => $total,
593            'with_schema'         => self::count_published_with_meta( $post_types, self::META_SCHEMA_TYPE ),
594            'with_title'          => self::count_published_with_meta( $post_types, self::META_TITLE ),
595            'with_description'    => self::count_published_with_meta( $post_types, self::META_DESCRIPTION ),
596            'with_search_visible' => max( 0, $total - $noindexed ),
597        );
598    }
599
600    /**
601     * Count published posts/pages whose meta is set. With no `$value`, counts a
602     * non-empty string meta; with a `$value`, counts an exact match.
603     *
604     * @param string[]    $post_types Post types to count across.
605     * @param string      $meta_key   Meta key to test.
606     * @param string|null $value      Exact value to match, or null for "non-empty".
607     * @return int
608     */
609    private static function count_published_with_meta( $post_types, $meta_key, $value = null ) {
610        $clause = null === $value
611            ? array(
612                'key'     => $meta_key,
613                'value'   => '',
614                'compare' => '!=',
615            )
616            : array(
617                'key'   => $meta_key,
618                'value' => $value,
619            );
620
621        $query = new \WP_Query(
622            array(
623                'post_type'              => $post_types,
624                'post_status'            => 'publish',
625                'posts_per_page'         => 1,
626                'fields'                 => 'ids',
627                'update_post_meta_cache' => false,
628                'update_post_term_cache' => false,
629                // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query -- Overview snapshot; one count query per metric on the SEO page only.
630                'meta_query'             => array( $clause ),
631            )
632        );
633
634        return (int) $query->found_posts;
635    }
636
637    /**
638     * Site identity used to render the homepage search/social previews on the
639     * Settings tab: title, URL, and representative images. The front-page
640     * description that completes the preview is read from the Settings form
641     * (it's editable there), not bootstrapped here.
642     *
643     * @return array
644     */
645    public static function get_site_data() {
646        $icon_url = (string) get_site_icon_url();
647
648        $logo_id  = (int) get_theme_mod( 'custom_logo' );
649        $logo_url = $logo_id ? (string) wp_get_attachment_image_url( $logo_id, 'full' ) : '';
650
651        return array(
652            'title' => (string) get_bloginfo( 'name' ),
653            'url'   => (string) home_url(),
654            'icon'  => $icon_url,
655            'image' => $logo_url ? $logo_url : $icon_url,
656        );
657    }
658
659    /**
660     * Expose the core `blog_public` option to the REST settings endpoint.
661     *
662     * Search-engine visibility is a WordPress core option, not a Jetpack one,
663     * so the Settings tab saves it through `/wp/v2/settings` — which only
664     * round-trips settings registered with `show_in_rest`. The core settings
665     * controller enforces the `manage_options` capability on writes.
666     *
667     * @return void
668     */
669    public static function register_rest_settings() {
670        register_setting(
671            'reading',
672            'blog_public',
673            array(
674                'show_in_rest' => true,
675                'type'         => 'integer',
676                'default'      => 1,
677            )
678        );
679    }
680
681    /**
682     * Register the opt-in REST route that switches an existing self-hosted install over to
683     * the new SEO experience.
684     *
685     * Lives on the `jetpack/v4` namespace and is registered ahead of the cohort gate, so a
686     * site whose SEO surface is still hidden can reach it from the legacy Traffic page or
687     * My Jetpack. See {@see self::handle_optin()}.
688     *
689     * @return void
690     */
691    public static function register_optin_route() {
692        register_rest_route(
693            'jetpack/v4',
694            '/seo/opt-in',
695            array(
696                'methods'             => \WP_REST_Server::CREATABLE,
697                'callback'            => array( __CLASS__, 'handle_optin' ),
698                'permission_callback' => function () {
699                    return current_user_can( 'manage_options' );
700                },
701            )
702        );
703    }
704
705    /**
706     * Opt an existing install into the new SEO experience: mark the surface visible and
707     * activate the `seo-tools` module, then hand back the dashboard URL to redirect to.
708     *
709     * Idempotent — re-opting-in is harmless. `Modules::activate()` is called with
710     * `$exit = false, $redirect = false`; the defaults would `exit()` and send a 302,
711     * which break a REST response.
712     *
713     * @return \WP_REST_Response
714     */
715    public static function handle_optin() {
716        update_option( self::VISIBILITY_OPTION, true );
717
718        if ( class_exists( 'Automattic\\Jetpack\\Modules' ) ) {
719            ( new Modules() )->activate( 'seo-tools', false, false );
720        }
721
722        return rest_ensure_response(
723            array(
724                'success'  => true,
725                'redirect' => admin_url( 'admin.php?page=' . self::MENU_SLUG ),
726            )
727        );
728    }
729
730    /**
731     * Map of read-only dashboard routes: tab slug => data-builder callable. The
732     * single source of truth for both the registered routes and the paths
733     * preloaded onto the page, so the two can't drift.
734     *
735     * @return array<string, callable>
736     */
737    private static function rest_reads() {
738        return array(
739            'overview' => array( __CLASS__, 'get_overview_data' ),
740            'settings' => array( __CLASS__, 'get_settings_data' ),
741            'ai'       => array( __CLASS__, 'get_ai_data' ),
742        );
743    }
744
745    /**
746     * REST paths the dashboard reads its initial state from, preloaded into the
747     * page (see {@see self::inject_script_data()}) and fetched by the app.
748     *
749     * @return string[]
750     */
751    private static function rest_read_paths() {
752        return array_map(
753            static function ( $slug ) {
754                return '/jetpack/v4/seo/' . $slug;
755            },
756            array_keys( self::rest_reads() )
757        );
758    }
759
760    /**
761     * Register the read-only REST routes the dashboard hydrates from — one per
762     * data-backed tab, each returning the same builder payload previously injected
763     * synchronously onto the page. Read-only and gated to the page's own
764     * `manage_options`; writes still go through their existing endpoints.
765     *
766     * @return void
767     */
768    public static function register_rest_reads() {
769        foreach ( self::rest_reads() as $slug => $builder ) {
770            register_rest_route(
771                'jetpack/v4',
772                '/seo/' . $slug,
773                array(
774                    'methods'             => \WP_REST_Server::READABLE,
775                    'callback'            => static function () use ( $builder ) {
776                        return rest_ensure_response( call_user_func( $builder ) );
777                    },
778                    'permission_callback' => array( __CLASS__, 'reads_permission_check' ),
779                )
780            );
781        }
782    }
783
784    /**
785     * Capability gate for the dashboard's read routes — the same `manage_options`
786     * the SEO admin page itself requires.
787     *
788     * @return bool
789     */
790    public static function reads_permission_check() {
791        return current_user_can( 'manage_options' );
792    }
793
794    /**
795     * Build the editable Settings state the Settings tab hydrates from.
796     *
797     * Read-only bootstrap only. Writes go through the existing
798     * `/jetpack/v4/settings` REST endpoint, which already validates and
799     * sanitizes each of these fields — this package registers no settings
800     * endpoint of its own. The reads here mirror the options/helpers that
801     * endpoint round-trips so the form hydrates without a request.
802     *
803     * @return array
804     */
805    public static function get_settings_data() {
806        $modules = new Modules();
807
808        // @phan-suppress-next-line PhanUndeclaredClassMethod -- Jetpack_SEO_Titles lives in plugins/jetpack and is guarded by class_exists.
809        $title_formats = class_exists( 'Jetpack_SEO_Titles' ) ? Jetpack_SEO_Titles::get_custom_title_formats() : array();
810        // @phan-suppress-next-line PhanUndeclaredClassMethod -- Jetpack_SEO_Utils lives in plugins/jetpack and is guarded by class_exists.
811        $front_page_desc = class_exists( 'Jetpack_SEO_Utils' ) ? Jetpack_SEO_Utils::get_front_page_meta_description() : '';
812
813        $codes = get_option( 'verification_services_codes', array() );
814        if ( ! is_array( $codes ) ) {
815            $codes = array();
816        }
817
818        $sitemap_active = self::is_sitemap_enabled( $modules );
819
820        return array(
821            'search_engines_visible' => (int) get_option( 'blog_public', 1 ) === 1,
822            // Read the durable SEO option (seeded/synced from the `sitemaps` module
823            // by the Jetpack plugin) so the state survives the module's removal.
824            'sitemap_active'         => $sitemap_active,
825            // Empty until the sitemap is genuinely reachable, so the Settings tab can
826            // link to it only once it won't 404 (it's built by cron after activation).
827            'sitemap_url'            => self::get_reachable_sitemap_url( $sitemap_active ),
828            // Read the durable SEO option (seeded/synced from the `canonical-urls` module
829            // by the Jetpack plugin) so the state survives the module's removal.
830            'canonical_active'       => self::is_canonical_enabled( $modules ),
831            // Cast to object so an empty format set serializes as `{}`, not `[]`.
832            'title_formats'          => (object) $title_formats,
833            'front_page_description' => (string) $front_page_desc,
834            'verification'           => array(
835                'google'    => isset( $codes['google'] ) ? (string) $codes['google'] : '',
836                'bing'      => isset( $codes['bing'] ) ? (string) $codes['bing'] : '',
837                'pinterest' => isset( $codes['pinterest'] ) ? (string) $codes['pinterest'] : '',
838                'yandex'    => isset( $codes['yandex'] ) ? (string) $codes['yandex'] : '',
839                'facebook'  => isset( $codes['facebook'] ) ? (string) $codes['facebook'] : '',
840            ),
841        );
842    }
843
844    /**
845     * Build the Google site-verification state for the Settings tab.
846     *
847     * The Settings verification card lets a connected user verify with Google via a
848     * WordPress.com keyring OAuth popup (in addition to pasting a meta-tag code). This
849     * bootstraps the keyring connect URL and whether the current user is connected —
850     * the live verified status is fetched client-side from `/jetpack/v4/verify-site/google`
851     * (a wpcom round-trip we don't want to make on every page load).
852     *
853     * Both `Keyring_Helper` (Publicize package) and the connection `Manager` are provided
854     * by the host Jetpack plugin, so they're guarded with `class_exists` like the
855     * `Jetpack_SEO_*` helpers. On a disconnected self-hosted site `is_connected` is false
856     * and the UI falls back to manual code entry only.
857     *
858     * @return array
859     */
860    public static function get_google_verify_data() {
861        $connect_url = '';
862        if ( class_exists( 'Automattic\\Jetpack\\Publicize\\Keyring_Helper' ) ) {
863            // @phan-suppress-next-line PhanUndeclaredClassMethod -- guarded; Publicize package is provided by the host plugin.
864            $connect_url = (string) \Automattic\Jetpack\Publicize\Keyring_Helper::connect_url( 'google_site_verification', 'other' );
865        }
866
867        $is_connected = false;
868        if ( class_exists( 'Automattic\\Jetpack\\Connection\\Manager' ) ) {
869            // @phan-suppress-next-line PhanUndeclaredClassMethod -- guarded; Connection package is provided by the host plugin.
870            $is_connected = ( new \Automattic\Jetpack\Connection\Manager() )->is_user_connected();
871        }
872
873        return array(
874            'connect_url'  => $connect_url,
875            'is_connected' => (bool) $is_connected,
876        );
877    }
878
879    /**
880     * Build the AI tab's initial state.
881     *
882     * The AI SEO Enhancer auto-generates SEO titles/descriptions/alt-text in the
883     * editor (the generation itself is wpcom/AI-Assistant side); this exposes only
884     * its persisted on/off toggle and whether it's available. Availability mirrors
885     * the legacy Traffic page: the `ai_seo_enhancer_enabled` feature filter must be
886     * on (it still depends on AI being available) AND the site's plan must support
887     * the `ai-seo-enhancer` feature. The toggle writes through the existing
888     * `/jetpack/v4/settings` endpoint (`ai_seo_enhancer_enabled`).
889     *
890     * @return array
891     */
892    public static function get_ai_data() {
893        $filter_on = (bool) apply_filters( 'ai_seo_enhancer_enabled', true );
894
895        // Current_Plan is provided by the host Jetpack plugin, not a package
896        // dependency — guard like the Jetpack_SEO_* helpers above.
897        $plan_supports = class_exists( 'Automattic\\Jetpack\\Current_Plan' )
898            // @phan-suppress-next-line PhanUndeclaredClassMethod -- guarded by class_exists; host plugin provides the class.
899            && \Automattic\Jetpack\Current_Plan::supports( 'ai-seo-enhancer' );
900
901        return array(
902            'enhancer' => array(
903                'available' => $filter_on && $plan_supports,
904                'enabled'   => (bool) get_option( 'ai_seo_enhancer_enabled', false ),
905            ),
906        );
907    }
908}