← All changes | jetpack_vendor/automattic/jetpack-admin-ui/src/class-admin-menu.php +1029 -0 16.2-beta → 16.3 View file →

		@@ -1,0 +1,1029 @@
	1	+<?php
	2	+/**
	3	+ * Admin Menu Registration
	4	+ *
	5	+ * @package automattic/jetpack-admin-ui
	6	+ */
	7	+
	8	+namespace Automattic\Jetpack\Admin_UI;
	9	+
	10	+use Automattic\Jetpack\Feature_Policy;
	11	+use Automattic\Jetpack\Tracking;
	12	+use Jetpack_Options;
	13	+use Jetpack_Tracks_Client;
	14	+
	15	+/**
	16	+ * This class offers a wrapper to add_submenu_page and makes sure stand-alone plugin's menu items are always added under the Jetpack top level menu.
	17	+ * If the Jetpack top level was not previously registered by other plugin, it will be registered here.
	18	+ */
	19	+class Admin_Menu {
	20	+
	21	+ const PACKAGE_VERSION = '0.14.3';
	22	+
	23	+ /**
	24	+ * Slug used for the upgrade menu item and redirect URL.
	25	+ *
	26	+ * Keep the slug in sync with `$upgrade-menu-slug` at admin-ui-upgrade-menu.scss
	27	+ *
	28	+ * @var string
	29	+ */
	30	+ const UPGRADE_MENU_SLUG = 'jetpack-wpadmin-sidebar-free-plan-upsell-menu-item';
	31	+
	32	+ /**
	33	+ * Fallback upgrade URL when the Redirect class is unavailable.
	34	+ *
	35	+ * @var string
	36	+ */
	37	+ const UPGRADE_MENU_FALLBACK_URL = 'https://jetpack.com/upgrade/';
	38	+
	39	+ /*
	40	+ * The sidebar's position tiers. Items sharing a tier sort alphabetically by menu title, so a
	41	+ * product should pass no position and land in POSITION_DEFAULT. add_menu() treats any value
	42	+ * that is not a tier below as omitted, so an int of your own cannot opt an item out.
	43	+ */
	44	+
	45	+ /**
	46	+ * Owns the top-level Jetpack link, since WordPress points it at whichever item sorts first.
	47	+ *
	48	+ * @var int
	49	+ */
	50	+ const POSITION_FIRST = -10;
	51	+
	52	+ /**
	53	+ * Takes the first slot when nothing claims POSITION_FIRST, as in offline mode.
	54	+ *
	55	+ * @var int
	56	+ */
	57	+ const POSITION_FIRST_FALLBACK = -5;
	58	+
	59	+ /**
	60	+ * Products, in alphabetical order. Pass no position rather than this.
	61	+ *
	62	+ * @var int
	63	+ */
	64	+ const POSITION_DEFAULT = 0;
	65	+
	66	+ /**
	67	+ * Links that leave wp-admin, grouped below the products.
	68	+ *
	69	+ * @var int
	70	+ */
	71	+ const POSITION_EXTERNAL = 100;
	72	+
	73	+ /**
	74	+ * Site-level items that belong under everything else.
	75	+ *
	76	+ * @var int
	77	+ */
	78	+ const POSITION_LAST = 998;
	79	+
	80	+ /**
	81	+ * The upgrade item this package adds, below every tier a caller can use.
	82	+ *
	83	+ * @var int
	84	+ */
	85	+ const POSITION_UPGRADE = 999;
	86	+
	87	+ /**
	88	+ * The tiers add_menu() accepts. POSITION_UPGRADE is left out: only this class claims it.
	89	+ *
	90	+ * @var int[]
	91	+ */
	92	+ private const CALLER_POSITIONS = array(
	93	+ self::POSITION_FIRST,
	94	+ self::POSITION_FIRST_FALLBACK,
	95	+ self::POSITION_DEFAULT,
	96	+ self::POSITION_EXTERNAL,
	97	+ self::POSITION_LAST,
	98	+ );
	99	+
	100	+ /**
	101	+ * Handle for the bundled WPDS design-tokens stylesheet.
	102	+ *
	103	+ * Fallback when Core/Gutenberg has not registered the `wp-theme` style.
	104	+ *
	105	+ * @var string
	106	+ */
	107	+ const DESIGN_TOKENS_HANDLE = 'jetpack-admin-ui-design-tokens';
	108	+
	109	+ /**
	110	+ * Handle for the source-less stylesheet that hides WordPress core admin notices.
	111	+ *
	112	+ * @var string
	113	+ */
	114	+ const HIDE_CORE_NOTICES_HANDLE = 'jetpack-admin-ui-hide-core-notices';
	115	+
	116	+ /**
	117	+ * Visibility state: show the item only when its declared gate is satisfied.
	118	+ *
	119	+ * @var string
	120	+ */
	121	+ const VISIBILITY_DEFAULT = 'default';
	122	+
	123	+ /**
	124	+ * Visibility state: show the item whatever its gate says.
	125	+ *
	126	+ * @var string
	127	+ */
	128	+ const VISIBILITY_VISIBLE = 'visible';
	129	+
	130	+ /**
	131	+ * Visibility state: keep the item out whatever its gate says.
	132	+ *
	133	+ * @var string
	134	+ */
	135	+ const VISIBILITY_HIDDEN = 'hidden';
	136	+
	137	+ /**
	138	+ * Whether this class has been initialized
	139	+ *
	140	+ * @var boolean
	141	+ */
	142	+ private static $initialized = false;
	143	+
	144	+ /**
	145	+ * List of menu items enqueued to be added
	146	+ *
	147	+ * @var array
	148	+ */
	149	+ private static $menu_items = array();
	150	+
	151	+ /**
	152	+ * List of top level menu items enqueued to be added
	153	+ *
	154	+ * @var array
	155	+ */
	156	+ private static $top_level_items = array();
	157	+
	158	+ /**
	159	+ * Hook suffixes of the pages registered through this class.
	160	+ *
	161	+ * Used to scope the design-tokens stylesheet to Jetpack admin pages.
	162	+ *
	163	+ * @var array
	164	+ */
	165	+ private static $page_hooks = array();
	166	+
	167	+ /**
	168	+ * Optional connection manager dependency.
	169	+ *
	170	+ * @var object|null
	171	+ */
	172	+ private static $connection_manager = null;
	173	+
	174	+ /**
	175	+ * Callback that answers whether a menu item's declared gate is satisfied.
	176	+ *
	177	+ * Set by My Jetpack, which owns the product classes the gates name. Stays null on a
	178	+ * site without it, where every gate then fails open.
	179	+ *
	180	+ * @var callable|null
	181	+ */
	182	+ private static $visibility_resolver = null;
	183	+
	184	+ /**
	185	+ * Menu slugs registered this request but kept out of the rendered sidebar.
	186	+ *
	187	+ * @var string[]
	188	+ */
	189	+ private static $hidden_menu_slugs = array();
	190	+
	191	+ /**
	192	+ * Top level menu slugs registered this request but kept out of the rendered sidebar.
	193	+ *
	194	+ * @var string[]
	195	+ */
	196	+ private static $hidden_top_level_slugs = array();
	197	+
	198	+ /**
	199	+ * Whether the top level registration pass has been hooked.
	200	+ *
	201	+ * Separate from $initialized, which also builds the Jetpack menu.
	202	+ *
	203	+ * @var boolean
	204	+ */
	205	+ private static $top_level_initialized = false;
	206	+
	207	+ /**
	208	+ * Initialize the class and set up the main hook
	209	+ *
	210	+ * @return void
	211	+ */
	212	+ public static function init() {
	213	+ if ( ! self::$initialized ) {
	214	+ self::$initialized = true;
	215	+ self::handle_akismet_menu();
	216	+ add_action( 'admin_menu', array( __CLASS__, 'admin_menu_hook_callback' ), 1000 ); // Jetpack uses 998.
	217	+ add_action( 'network_admin_menu', array( __CLASS__, 'admin_menu_hook_callback' ), 1000 ); // Jetpack uses 998.
	218	+ add_action( 'admin_head', array( __CLASS__, 'remove_hidden_menu_items' ) );
	219	+ add_action( 'admin_enqueue_scripts', array( __CLASS__, 'add_upgrade_menu_item_styles' ) );
	220	+ add_action( 'admin_enqueue_scripts', array( __CLASS__, 'maybe_enqueue_design_tokens' ) );
	221	+ }
	222	+ }
	223	+
	224	+ /**
	225	+ * Drops every queued item and unhooks the registration passes.
	226	+ *
	227	+ * Intended for tests.
	228	+ *
	229	+ * @return void
	230	+ */
	231	+ public static function reset() {
	232	+ self::$menu_items = array();
	233	+ self::$top_level_items = array();
	234	+ self::$page_hooks = array();
	235	+ self::$hidden_menu_slugs = array();
	236	+ self::$hidden_top_level_slugs = array();
	237	+ self::$initialized = false;
	238	+ self::$top_level_initialized = false;
	239	+
	240	+ remove_action( 'admin_menu', array( __CLASS__, 'admin_menu_hook_callback' ), 1000 );
	241	+ remove_action( 'network_admin_menu', array( __CLASS__, 'admin_menu_hook_callback' ), 1000 );
	242	+ remove_action( 'admin_menu', array( __CLASS__, 'top_level_menu_hook_callback' ), 1000 );
	243	+ remove_action( 'admin_head', array( __CLASS__, 'remove_hidden_menu_items' ) );
	244	+ remove_action( 'admin_enqueue_scripts', array( __CLASS__, 'add_upgrade_menu_item_styles' ) );
	245	+ remove_action( 'admin_enqueue_scripts', array( __CLASS__, 'maybe_enqueue_design_tokens' ) );
	246	+ }
	247	+
	248	+ /**
	249	+ * Handles the Akismet menu item when used alongside other stand-alone plugins
	250	+ *
	251	+ * When Jetpack plugin is present, Akismet menu item is moved under the Jetpack top level menu, but if Akismet is active alongside other stand-alone plugins,
	252	+ * we use this method to move the menu item.
	253	+ */
	254	+ private static function handle_akismet_menu() {
	255	+ if ( class_exists( 'Akismet_Admin' ) ) {
	256	+ add_action(
	257	+ 'admin_menu',
	258	+ function () {
	259	+ // Prevent Akismet from adding a menu item.
	260	+ remove_action( 'admin_menu', array( 'Akismet_Admin', 'admin_menu' ), 5 );
	261	+
	262	+ // Add an Anti-spam menu item for Jetpack.
	263	+ self::add_menu( __( 'Akismet Anti-spam', 'jetpack-admin-ui' ), __( 'Akismet Anti-spam', 'jetpack-admin-ui' ), 'manage_options', 'akismet-key-config', array( 'Akismet_Admin', 'display_page' ) );
	264	+ },
	265	+ 4
	266	+ );
	267	+
	268	+ }
	269	+ }
	270	+
	271	+ /**
	272	+ * Callback to the admin_menu and network_admin_menu hooks that will register the enqueued menu items
	273	+ *
	274	+ * @return void
	275	+ */
	276	+ public static function admin_menu_hook_callback() {
	277	+ $can_see_toplevel_menu = true;
	278	+ $jetpack_plugin_present = class_exists( 'Jetpack_React_Page' );
	279	+ $icon = 'dashicons-admin-plugins';
	280	+ if ( method_exists( '\Automattic\Jetpack\Assets\Logo', 'get_base64_admin_menu_logo' ) ) {
	281	+ $icon = ( new \Automattic\Jetpack\Assets\Logo() )->get_base64_admin_menu_logo();
	282	+ } elseif ( method_exists( '\Automattic\Jetpack\Assets\Logo', 'get_base64_logo' ) ) {
	283	+ $icon = ( new \Automattic\Jetpack\Assets\Logo() )->get_base64_logo();
	284	+ }
	285	+
	286	+ if ( ! $jetpack_plugin_present ) {
	287	+ add_menu_page(
	288	+ 'Jetpack',
	289	+ 'Jetpack',
	290	+ 'edit_posts',
	291	+ 'jetpack',
	292	+ '__return_null',
	293	+ $icon,
	294	+ 3
	295	+ );
	296	+
	297	+ // If Jetpack plugin is not present, user will only be able to see this menu if they have enough capability to at least one of the sub menus being added.
	298	+ $can_see_toplevel_menu = false;
	299	+ }
	300	+
	301	+ /*
	302	+ * Sort here and register in that order, without passing the position on: core splices an
	303	+ * int back in, and prepends 0 or less. See https://core.trac.wordpress.org/ticket/52035.
	304	+ */
	305	+ usort(
	306	+ self::$menu_items,
	307	+ function ( $a, $b ) {
	308	+ $position_a = empty( $a['position'] ) ? 0 : $a['position'];
	309	+ $position_b = empty( $b['position'] ) ? 0 : $b['position'];
	310	+ $result = $position_a <=> $position_b;
	311	+
	312	+ if ( 0 === $result ) {
	313	+ // Case-insensitive and number-aware, so "eCommerce" sorts with the Es.
	314	+ // Still a byte compare: a leading accented character sorts after Z.
	315	+ $result = strnatcasecmp( $a['menu_title'], $b['menu_title'] );
	316	+ }
	317	+
	318	+ return $result;
	319	+ }
	320	+ );
	321	+
	322	+ $visibility = self::get_visibility_states();
	323	+
	324	+ self::$hidden_menu_slugs = array();
	325	+
	326	+ foreach ( self::$menu_items as $menu_item ) {
	327	+ if ( ! current_user_can( $menu_item['capability'] ) ) {
	328	+ continue;
	329	+ }
	330	+
	331	+ /*
	332	+ * A hidden item is still registered, so its page keeps resolving for links into it.
	333	+ * It leaves the submenu on admin_head instead: core's access check reads $submenu.
	334	+ */
	335	+ if ( self::is_menu_item_visible( $menu_item, $visibility ) ) {
	336	+ $can_see_toplevel_menu = true;
	337	+ } else {
	338	+ self::$hidden_menu_slugs[] = $menu_item['menu_slug'];
	339	+ }
	340	+
	341	+ add_submenu_page(
	342	+ 'jetpack',
	343	+ $menu_item['page_title'],
	344	+ $menu_item['menu_title'],
	345	+ $menu_item['capability'],
	346	+ $menu_item['menu_slug'],
	347	+ $menu_item['function']
	348	+ );
	349	+ }
	350	+
	351	+ if ( ! $jetpack_plugin_present ) {
	352	+ remove_submenu_page( 'jetpack', 'jetpack' );
	353	+ }
	354	+
	355	+ if ( ! $can_see_toplevel_menu ) {
	356	+ remove_menu_page( 'jetpack' );
	357	+ }
	358	+
	359	+ self::maybe_add_upgrade_menu_item();
	360	+ }
	361	+
	362	+ /**
	363	+ * Hooks the top level registration pass, without building the Jetpack menu that init() does.
	364	+ *
	365	+ * @return void
	366	+ */
	367	+ private static function init_top_level() {
	368	+ if ( ! self::$top_level_initialized ) {
	369	+ self::$top_level_initialized = true;
	370	+ add_action( 'admin_menu', array( __CLASS__, 'top_level_menu_hook_callback' ), 1000 );
	371	+ add_action( 'admin_head', array( __CLASS__, 'remove_hidden_menu_items' ) );
	372	+ }
	373	+ }
	374	+
	375	+ /**
	376	+ * Registers the queued top level items, skipping the ones that should not be seen.
	377	+ *
	378	+ * These sit beside the Jetpack menu, so they never count towards keeping it alive.
	379	+ *
	380	+ * @return void
	381	+ */
	382	+ public static function top_level_menu_hook_callback() {
	383	+ $visibility = self::get_visibility_states();
	384	+
	385	+ self::$hidden_top_level_slugs = array();
	386	+
	387	+ foreach ( self::$top_level_items as $menu_item ) {
	388	+ if ( ! current_user_can( $menu_item['capability'] ) ) {
	389	+ continue;
	390	+ }
	391	+
	392	+ if ( ! self::is_menu_item_visible( $menu_item, $visibility ) ) {
	393	+ self::$hidden_top_level_slugs[] = $menu_item['menu_slug'];
	394	+ }
	395	+
	396	+ add_menu_page(
	397	+ $menu_item['page_title'],
	398	+ $menu_item['menu_title'],
	399	+ $menu_item['capability'],
	400	+ $menu_item['menu_slug'],
	401	+ $menu_item['function'],
	402	+ $menu_item['icon_url'],
	403	+ $menu_item['position']
	404	+ );
	405	+ }
	406	+ }
	407	+
	408	+ /**
	409	+ * Adds a top level menu item under the same visibility gate and filter as add_menu().
	410	+ *
	411	+ * Unlike add_menu(), the page gets neither the core-notice CSS nor the design tokens.
	412	+ * Parameters mirror add_menu_page(), with $args appended.
	413	+ *
	414	+ * @since 0.13.0
	415	+ *
	416	+ * @param string $page_title The text to be displayed in the title tags of the page when the menu
	417	+ * is selected.
	418	+ * @param string $menu_title The text to be used for the menu.
	419	+ * @param string $capability The capability required for this menu to be displayed to the user.
	420	+ * @param string $menu_slug The slug name to refer to this menu by. Should be unique for this menu.
	421	+ * @param callable|null $function The function to be called to output the content for this page.
	422	+ * @param string $icon_url The URL to the icon to be used for this menu, or a dashicons class.
	423	+ * @param int|null $position The position in the menu order this item should appear.
	424	+ * @param array $args Optional. Visibility declaration for this item; see add_menu().
	425	+ *
	426	+ * @return string The resulting page's hook_suffix
	427	+ */
	428	+ public static function add_top_level_menu( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url = '', $position = null, $args = array() ) {
	429	+ self::init_top_level();
	430	+ self::$top_level_items[] = compact( 'page_title', 'menu_title', 'capability', 'menu_slug', 'function', 'icon_url', 'position', 'args' );
	431	+
	432	+ // Same derivation as get_plugin_page_hookname(), which strips ".php" anywhere in the slug.
	433	+ return 'toplevel_page_' . preg_replace( '!\.php!', '', plugin_basename( $menu_slug ) );
	434	+ }
	435	+
	436	+ /**
	437	+ * Adds a new submenu to the Jetpack Top level menu
	438	+ *
	439	+ * The parameters this method accepts are the same as @see add_submenu_page. This class will
	440	+ * aggreagate all menu items registered by stand-alone plugins and make sure they all go under the same
	441	+ * Jetpack top level menu. It will also handle the top level menu registration in case the Jetpack plugin is not present.
	442	+ *
	443	+ * @param string $page_title The text to be displayed in the title tags of the page when the menu
	444	+ * is selected.
	445	+ * @param string $menu_title The text to be used for the menu.
	446	+ * @param string $capability The capability required for this menu to be displayed to the user.
	447	+ * @param string $menu_slug The slug name to refer to this menu by. Should be unique for this menu
	448	+ * and only include lowercase alphanumeric, dashes, and underscores characters
	449	+ * to be compatible with sanitize_key().
	450	+ * @param callable|null $function The function to be called to output the content for this page.
	451	+ * @param int|null $position One of the POSITION_* tiers; any other value is ignored. Leave empty typically.
	452	+ * @param array $args Optional. Visibility declaration for this item:
	453	+ * - 'product' (string) My Jetpack product slug whose activation gates the item.
	454	+ * - 'module' (string) Jetpack module name, for items with no product class.
	455	+ * - 'key' (string) The name hosts use for this item in the visibility
	456	+ * filter. Declare one on every item; see get_item_key().
	457	+ * An item that declares no gate is always shown.
	458	+ *
	459	+ * @return string The resulting page's hook_suffix
	460	+ */
	461	+ public static function add_menu( $page_title, $menu_title, $capability, $menu_slug, $function, $position = null, $args = array() ) {
	462	+ self::init();
	463	+
	464	+ /*
	465	+ * Anything but a tier would opt the item out of the alphabetical order, so treat it as omitted.
	466	+ * @todo Add _doing_it_wrong() here after December 2026. Until all our own plugins ship tier-only
	467	+ * positions, it would have the latest release of one Jetpack plugin warning about another.
	468	+ */
	469	+ $position = is_numeric( $position ) && in_array( (int) $position, self::CALLER_POSITIONS, true ) ? (int) $position : null;
	470	+
	471	+ self::$menu_items[] = compact( 'page_title', 'menu_title', 'capability', 'menu_slug', 'function', 'position', 'args' );
	472	+
	473	+ /**
	474	+ * Let's return the page hook so consumers can use.
	475	+ * Pages normally sit under the Jetpack top level menu page, so we can hardcode the first part of the string.
	476	+ * Using get_plugin_page_hookname here won't work because the top level page is not registered yet.
	477	+ */
	478	+ $hook = 'jetpack_page_' . $menu_slug;
	479	+
	480	+ // Core names the page admin_page_<slug> instead when the user has no Jetpack top-level menu.
	481	+ foreach ( array( $hook, 'admin_page_' . $menu_slug ) as $page_hook ) {
	482	+ // Track the page hook so the design-tokens stylesheet can be scoped to it.
	483	+ self::$page_hooks[] = $page_hook;
	484	+
	485	+ // Hide WordPress core admin notices on this Jetpack page. The load-<hook>
	486	+ // action only fires when the matching screen is being rendered, so this
	487	+ // stays scoped to Jetpack pages and reaches every page registered here.
	488	+ add_action( 'load-' . $page_hook, array( __CLASS__, 'hide_core_admin_notices' ) );
	489	+ add_action( 'load-' . $page_hook . '-network', array( __CLASS__, 'hide_core_admin_notices' ) );
	490	+ }
	491	+
	492	+ return $hook;
	493	+ }
	494	+
	495	+ /**
	496	+ * Enqueues the stylesheet that hides WordPress core admin notices on the current Jetpack page.
	497	+ *
	498	+ * Hooked from the page's load-<hook> action so it only runs on Jetpack screens. That action
	499	+ * runs before admin_enqueue_scripts, so the handle is queued in time to be printed.
	500	+ *
	501	+ * @return void
	502	+ */
	503	+ public static function hide_core_admin_notices() {
	504	+ // wp_add_inline_style() appends, so the CSS is attached only while the handle is new to the request.
	505	+ if ( ! wp_style_is( self::HIDE_CORE_NOTICES_HANDLE, 'registered' ) ) {
	506	+ wp_register_style( self::HIDE_CORE_NOTICES_HANDLE, false, array(), self::PACKAGE_VERSION );
	507	+ wp_add_inline_style( self::HIDE_CORE_NOTICES_HANDLE, self::get_hide_core_admin_notices_styles() );
	508	+ }
	509	+
	510	+ wp_enqueue_style( self::HIDE_CORE_NOTICES_HANDLE );
	511	+ }
	512	+
	513	+ /**
	514	+ * Enqueues the CSS that hides WordPress core admin notices.
	515	+ *
	516	+ * Callers must run this before WordPress flushes the style queue in
	517	+ * print_admin_styles() (admin_print_styles, priority 20). Later than that,
	518	+ * the handle is never printed. The previous admin_print_styles priority-10
	519	+ * hook still works.
	520	+ *
	521	+ * @deprecated 0.10.0 Use hide_core_admin_notices(), which enqueues the CSS.
	522	+ *
	523	+ * @return void
	524	+ */
	525	+ public static function print_hide_core_admin_notices_style() {
	526	+ _deprecated_function( __METHOD__, 'admin-ui-0.10.0', __CLASS__ . '::hide_core_admin_notices' );
	527	+ self::hide_core_admin_notices();
	528	+ }
	529	+
	530	+ /**
	531	+ * Gets the CSS that hides WordPress core admin notices.
	532	+ *
	533	+ * We only target direct children of #wpbody-content (where core renders notices via the
	534	+ * admin_notices / all_admin_notices hooks). This intentionally leaves JITMs untouched —
	535	+ * they output `.jetpack-jitm-message`, not `.notice` — and leaves in-app/React notices
	536	+ * untouched, since those render deeper inside `.wrap`. The CSS rides on a source-less
	537	+ * handle rather than a build asset so it also reaches older Jetpack pages that ship no
	538	+ * stylesheet of their own.
	539	+ *
	540	+ * @return string CSS rules.
	541	+ */
	542	+ private static function get_hide_core_admin_notices_styles() {
	543	+ return '
	544	+ #wpbody-content > .notice,
	545	+ #wpbody-content > .update-nag,
	546	+ #wpbody-content > .updated,
	547	+ #wpbody-content > .error { display: none !important; }
	548	+ ';
	549	+ }
	550	+
	551	+ /**
	552	+ * Sets the callback that resolves a menu item's declared gate.
	553	+ *
	554	+ * The callback receives the item's $args array and returns true (gate satisfied),
	555	+ * false (not satisfied), or null when it cannot answer — an unknown product slug,
	556	+ * for instance. Null is treated as satisfied, so a gate this package cannot resolve
	557	+ * never removes a menu item.
	558	+ *
	559	+ * This is the seam My Jetpack fills. Hosts wanting to shape the sidebar should use the
	560	+ * `jetpack_admin_menu_visibility` filter instead, which takes precedence: an item the
	561	+ * filter names is never put to this callback at all.
	562	+ *
	563	+ * @param callable|null $resolver Resolver callback, or null to clear it.
	564	+ * @return void
	565	+ */
	566	+ public static function set_visibility_resolver( $resolver ) {
	567	+ self::$visibility_resolver = $resolver;
	568	+ }
	569	+
	570	+ /**
	571	+ * Takes hidden items out of the sidebar before it renders.
	572	+ *
	573	+ * Runs on admin_head, after core's access check has already resolved the current page,
	574	+ * so a hidden item's page stays reachable while its entry disappears.
	575	+ *
	576	+ * @return void
	577	+ */
	578	+ public static function remove_hidden_menu_items() {
	579	+ foreach ( self::$hidden_menu_slugs as $menu_slug ) {
	580	+ remove_submenu_page( 'jetpack', plugin_basename( $menu_slug ) );
	581	+ }
	582	+
	583	+ foreach ( self::$hidden_top_level_slugs as $menu_slug ) {
	584	+ remove_menu_page( plugin_basename( $menu_slug ) );
	585	+ }
	586	+ }
	587	+
	588	+ /**
	589	+ * Returns the name a host uses for a menu item in the visibility filter.
	590	+ *
	591	+ * The menu slug is only a fallback. It is the wrong thing to hand a host as an identifier:
	592	+ * several items register a URL as their slug, Blaze's is filterable, and VideoPress swaps
	593	+ * between two slugs depending on whether the module is active — so a host naming one of
	594	+ * them is naming a moving target, or only half an item.
	595	+ *
	596	+ * @param array $menu_item A registered menu item.
	597	+ * @return string
	598	+ */
	599	+ private static function get_item_key( array $menu_item ) {
	600	+ if ( ! empty( $menu_item['args']['key'] ) ) {
	601	+ return (string) $menu_item['args']['key'];
	602	+ }
	603	+
	604	+ return (string) $menu_item['menu_slug'];
	605	+ }
	606	+
	607	+ /**
	608	+ * Builds the item => state map and hands it to hosts to amend.
	609	+ *
	610	+ * @return array Map of item key to one of the VISIBILITY_* states.
	611	+ */
	612	+ private static function get_visibility_states() {
	613	+ // This filter is one a policy feeds, and nothing else need have read the policy this request.
	614	+ if ( method_exists( Feature_Policy::class, 'ensure_hooks' ) ) {
	615	+ Feature_Policy::ensure_hooks();
	616	+ }
	617	+
	618	+ $states = array();
	619	+ $items = array_merge( self::$menu_items, self::$top_level_items );
	620	+
	621	+ foreach ( $items as $menu_item ) {
	622	+ $states[ self::get_item_key( $menu_item ) ] = self::VISIBILITY_DEFAULT;
	623	+ }
	624	+
	625	+ /**
	626	+ * Filters which Jetpack items appear in the wp-admin sidebar.
	627	+ *
	628	+ * Governs the sidebar entry only — a hidden item's page stays reachable by URL, so this
	629	+ * is not an access control. States: 'default' follows the item's feature, 'visible' shows it, 'hidden' removes it.
	630	+ *
	631	+ * @since 0.12.0
	632	+ *
	633	+ * @param array $states Map of item key (menu slug unless the item declared one) to state.
	634	+ * @param array $menu_items The registered menu items, for context.
	635	+ */
	636	+ $states = apply_filters( 'jetpack_admin_menu_visibility', $states, $items );
	637	+
	638	+ return is_array( $states ) ? $states : array();
	639	+ }
	640	+
	641	+ /**
	642	+ * Decides whether a single menu item should appear in the sidebar.
	643	+ *
	644	+ * @param array $menu_item A registered menu item.
	645	+ * @param array $visibility The resolved state map from get_visibility_states().
	646	+ * @return bool
	647	+ */
	648	+ private static function is_menu_item_visible( array $menu_item, array $visibility ) {
	649	+ $key = self::get_item_key( $menu_item );
	650	+ $state = $visibility[ $key ] ?? self::VISIBILITY_DEFAULT;
	651	+
	652	+ if ( self::VISIBILITY_HIDDEN === $state ) {
	653	+ return false;
	654	+ }
	655	+
	656	+ if ( self::VISIBILITY_VISIBLE === $state ) {
	657	+ return true;
	658	+ }
	659	+
	660	+ return self::is_gate_satisfied( $menu_item['args'] ?? array() );
	661	+ }
	662	+
	663	+ /**
	664	+ * Asks the resolver whether an item's declared gate is satisfied.
	665	+ *
	666	+ * Everything here fails open. An item that declares no gate, a site with no resolver
	667	+ * registered, and a gate the resolver does not recognize all keep the item in the
	668	+ * sidebar, so adopting this mechanism cannot remove an item nobody asked it to.
	669	+ *
	670	+ * @param array $args The item's visibility declaration.
	671	+ * @return bool
	672	+ */
	673	+ private static function is_gate_satisfied( array $args ) {
	674	+ if ( ! isset( $args['product'] ) && ! isset( $args['module'] ) ) {
	675	+ return true;
	676	+ }
	677	+
	678	+ if ( ! is_callable( self::$visibility_resolver ) ) {
	679	+ return true;
	680	+ }
	681	+
	682	+ $resolved = call_user_func( self::$visibility_resolver, $args );
	683	+
	684	+ return null === $resolved ? true : (bool) $resolved;
	685	+ }
	686	+
	687	+ /**
	688	+ * Removes an already added submenu
	689	+ *
	690	+ * @param string $menu_slug The slug of the submenu to remove.
	691	+ *
	692	+ * @return array|false The removed submenu on success, false if not found.
	693	+ */
	694	+ public static function remove_menu( $menu_slug ) {
	695	+
	696	+ foreach ( self::$menu_items as $index => $menu_item ) {
	697	+ if ( $menu_item['menu_slug'] === $menu_slug ) {
	698	+ unset( self::$menu_items[ $index ] );
	699	+
	700	+ return $menu_item;
	701	+ }
	702	+ }
	703	+
	704	+ return false;
	705	+ }
	706	+
	707	+ /**
	708	+ * Gets the slug for the first item under the Jetpack top level menu
	709	+ *
	710	+ * Skips hidden items rather than reading $submenu alone, because callers on admin_enqueue_scripts
	711	+ * and outside wp-admin ask before — or without — the admin_head pass that drops them.
	712	+ *
	713	+ * @return string|null
	714	+ */
	715	+ public static function get_top_level_menu_item_slug() {
	716	+ global $submenu;
	717	+
	718	+ if ( empty( $submenu['jetpack'] ) ) {
	719	+ return null;
	720	+ }
	721	+
	722	+ $hidden = array_map( 'plugin_basename', self::$hidden_menu_slugs );
	723	+
	724	+ foreach ( $submenu['jetpack'] as $item ) {
	725	+ if ( isset( $item[2] ) && ! in_array( $item[2], $hidden, true ) ) {
	726	+ return $item[2];
	727	+ }
	728	+ }
	729	+
	730	+ return null;
	731	+ }
	732	+
	733	+ /**
	734	+ * Gets the URL for the first item under the Jetpack top level menu
	735	+ *
	736	+ * @param string $fallback If Jetpack menu is not there or no children is found, return this fallback instead. Default to admin_url().
	737	+ * @return string
	738	+ */
	739	+ public static function get_top_level_menu_item_url( $fallback = false ) {
	740	+ $slug = self::get_top_level_menu_item_slug();
	741	+
	742	+ if ( $slug ) {
	743	+ $url = menu_page_url( $slug, false );
	744	+ return $url;
	745	+ }
	746	+
	747	+ $url = $fallback ? $fallback : admin_url();
	748	+ return $url;
	749	+ }
	750	+
	751	+ /**
	752	+ * Checks whether the current site should show the upgrade menu item.
	753	+ *
	754	+ * The upgrade menu is only shown to administrators on free-plan sites
	755	+ * that are not hosted on WordPress.com.
	756	+ *
	757	+ * @return bool True if the upgrade menu should be shown.
	758	+ */
	759	+ private static function should_show_upgrade_menu() {
	760	+
	761	+ // Only show to administrators.
	762	+ if ( ! current_user_can( 'manage_options' ) ) {
	763	+ return false;
	764	+ }
	765	+
	766	+ // Don't show upsells on WordPress.com platform.
	767	+ if ( class_exists( '\Automattic\Jetpack\Status\Host' ) ) {
	768	+ $host = new \Automattic\Jetpack\Status\Host();
	769	+ if ( $host->is_wpcom_platform() ) {
	770	+ return false;
	771	+ }
	772	+ }
	773	+
	774	+ // Don't show upsells in offline/development mode.
	775	+ if ( class_exists( '\Automattic\Jetpack\Status' ) ) {
	776	+ $status = new \Automattic\Jetpack\Status();
	777	+ if ( $status->is_offline_mode() ) {
	778	+ return false;
	779	+ }
	780	+ }
	781	+
	782	+ // Only show after the site and current user are connected.
	783	+ if ( ! self::is_site_and_user_connected() ) {
	784	+ return false;
	785	+ }
	786	+
	787	+ // Only show to free-plan sites.
	788	+ return self::is_free_plan();
	789	+ }
	790	+
	791	+ /**
	792	+ * Checks whether the site and current user are connected to WordPress.com.
	793	+ *
	794	+ * @return bool True if site and current user are connected.
	795	+ */
	796	+ private static function is_site_and_user_connected() {
	797	+ $connection_manager = self::$connection_manager;
	798	+ if ( ! $connection_manager && class_exists( '\Automattic\Jetpack\Connection\Manager' ) ) {
	799	+ $connection_manager = new \Automattic\Jetpack\Connection\Manager();
	800	+ self::$connection_manager = $connection_manager;
	801	+ }
	802	+
	803	+ if (
	804	+ $connection_manager
	805	+ && is_callable( array( $connection_manager, 'is_connected' ) )
	806	+ && is_callable( array( $connection_manager, 'is_user_connected' ) )
	807	+ ) {
	808	+ return (bool) $connection_manager->is_connected()
	809	+ && (bool) $connection_manager->is_user_connected( get_current_user_id() );
	810	+ }
	811	+
	812	+ return false;
	813	+ }
	814	+
	815	+ /**
	816	+ * Sets the connection manager dependency; used by tests.
	817	+ *
	818	+ * @param object|null $connection_manager Connection manager object.
	819	+ * @return void
	820	+ */
	821	+ public static function set_connection_manager( $connection_manager ) {
	822	+ self::$connection_manager = $connection_manager;
	823	+ }
	824	+
	825	+ /**
	826	+ * Checks whether the current site is on a free Jetpack plan with no active paid license.
	827	+ *
	828	+ * @return bool True if the site has no paid plan.
	829	+ */
	830	+ private static function is_free_plan() {
	831	+ // Check the active plan - use the is_free field or product_slug.
	832	+ $plan = get_option( 'jetpack_active_plan', array() );
	833	+
	834	+ // Back-compat: older plan payloads use class to indicate paid plans.
	835	+ if ( isset( $plan['class'] ) && 'free' !== $plan['class'] ) {
	836	+ return false;
	837	+ }
	838	+
	839	+ // If the plan explicitly says it's not free, trust that.
	840	+ if ( isset( $plan['is_free'] ) && false === $plan['is_free'] ) {
	841	+ return false;
	842	+ }
	843	+
	844	+ // Check if the product slug indicates a paid plan.
	845	+ if ( isset( $plan['product_slug'] ) && 'jetpack_free' !== $plan['product_slug'] ) {
	846	+ return false;
	847	+ }
	848	+
	849	+ // Also check for site products (licenses can add products without changing plan).
	850	+ $products = get_option( 'jetpack_site_products', array() );
	851	+ if ( ! empty( $products ) && is_array( $products ) ) {
	852	+ return false;
	853	+ }
	854	+
	855	+ return true;
	856	+ }
	857	+
	858	+ /**
	859	+ * Conditionally adds an "Upgrade Jetpack" submenu item for free-plan sites.
	860	+ *
	861	+ * Only shown to users with manage_options capability on self-hosted sites without a paid Jetpack plan or license.
	862	+ *
	863	+ * @return void
	864	+ */
	865	+ private static function maybe_add_upgrade_menu_item() {
	866	+ if ( ! self::should_show_upgrade_menu() ) {
	867	+ return;
	868	+ }
	869	+
	870	+ $upgrade_url = class_exists( '\Automattic\Jetpack\Redirect' )
	871	+ ? \Automattic\Jetpack\Redirect::get_url( self::UPGRADE_MENU_SLUG )
	872	+ : self::UPGRADE_MENU_FALLBACK_URL;
	873	+
	874	+ $menu_title = esc_html__( 'Upgrade Jetpack', 'jetpack-admin-ui' );
	875	+
	876	+ add_submenu_page(
	877	+ 'jetpack',
	878	+ $menu_title,
	879	+ $menu_title,
	880	+ 'manage_options',
	881	+ esc_url( $upgrade_url ),
	882	+ null, // @phan-suppress-current-line PhanTypeMismatchArgumentProbablyReal -- Core should ideally document null for no-callback arg. https://core.trac.wordpress.org/ticket/52539.
	883	+ self::POSITION_UPGRADE
	884	+ );
	885	+
	886	+ // Add a CSS class to the <li> element so styles can target it precisely.
	887	+ global $submenu;
	888	+ if ( ! empty( $submenu['jetpack'] ) ) {
	889	+ foreach ( $submenu['jetpack'] as $index => $item ) {
	890	+ if ( isset( $item[2] ) && false !== strpos( $item[2], self::UPGRADE_MENU_SLUG ) ) {
	891	+ // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited
	892	+ $submenu['jetpack'][ $index ][4] = ( ! empty( $item[4] ) ? $item[4] . ' ' : '' ) . self::UPGRADE_MENU_SLUG;
	893	+ break;
	894	+ }
	895	+ }
	896	+ }
	897	+ }
	898	+
	899	+ /**
	900	+ * Enqueues admin styles for the "Upgrade Jetpack" menu item.
	901	+ *
	902	+ * The sidebar menu is visible on every admin page, so styles load globally.
	903	+ * Only enqueues for free-plan sites on self-hosted installs.
	904	+ *
	905	+ * @return void
	906	+ */
	907	+ public static function add_upgrade_menu_item_styles() {
	908	+ if ( ! self::should_show_upgrade_menu() ) {
	909	+ return;
	910	+ }
	911	+
	912	+ $asset_file = dirname( __DIR__ ) . '/build/admin-ui-upgrade-menu.asset.php';
	913	+ $asset = file_exists( $asset_file ) ? require $asset_file : array();
	914	+
	915	+ wp_enqueue_style(
	916	+ 'jetpack-admin-ui-upgrade-menu',
	917	+ plugins_url( '../build/admin-ui-upgrade-menu.css', __FILE__ ),
	918	+ $asset['dependencies'] ?? array(),
	919	+ $asset['version'] ?? self::PACKAGE_VERSION
	920	+ );
	921	+
	922	+ self::enqueue_upgrade_menu_tracks_script( $asset );
	923	+ }
	924	+
	925	+ /**
	926	+ * Enqueues WPDS design tokens so `var(--wpds-*)` values resolve at runtime.
	927	+ *
	928	+ * Prefer Core/Gutenberg's `wp-theme` style when registered; otherwise ship
	929	+ * the bundled copy. The caller scopes the call to the right page(s).
	930	+ *
	931	+ * @return void
	932	+ */
	933	+ public static function enqueue_design_tokens() {
	934	+ // Registered since WP 7.1 (and by Gutenberg):
	935	+ // https://make.wordpress.org/core/2026/07/31/design-system-theming-in-wordpress-7-1/
	936	+ if ( wp_style_is( 'wp-theme', 'registered' ) ) {
	937	+ wp_enqueue_style( 'wp-theme' );
	938	+ return;
	939	+ }
	940	+
	941	+ // @todo Remove this, the called function, and the webpack entrypoint it registers when WP 7.1 is the minimum version.
	942	+ self::register_design_tokens_style();
	943	+ wp_enqueue_style( self::DESIGN_TOKENS_HANDLE );
	944	+ }
	945	+
	946	+ /**
	947	+ * Registers the bundled, token-only WPDS design-tokens stylesheet.
	948	+ *
	949	+ * Used only when `wp-theme` is not registered. Safe to call repeatedly:
	950	+ * wp_register_style() is a no-op once the handle is registered.
	951	+ *
	952	+ * @return void
	953	+ */
	954	+ private static function register_design_tokens_style() {
	955	+ if ( wp_style_is( self::DESIGN_TOKENS_HANDLE, 'registered' ) ) {
	956	+ return;
	957	+ }
	958	+
	959	+ $asset_file = dirname( __DIR__ ) . '/build/design-tokens.asset.php';
	960	+ $asset = file_exists( $asset_file ) ? require $asset_file : array();
	961	+
	962	+ wp_register_style(
	963	+ self::DESIGN_TOKENS_HANDLE,
	964	+ plugins_url( '../build/design-tokens.css', __FILE__ ),
	965	+ $asset['dependencies'] ?? array(),
	966	+ $asset['version'] ?? self::PACKAGE_VERSION
	967	+ );
	968	+ }
	969	+
	970	+ /**
	971	+ * Enqueues the design tokens on the pages registered through this class.
	972	+ *
	973	+ * This is the admin_enqueue_scripts callback for the modernized Jetpack
	974	+ * dashboards. Scoped to self::$page_hooks so the tokens load wherever a
	975	+ * modernized dashboard renders, regardless of plan or connection state; the
	976	+ * actual enqueue is delegated to the reusable enqueue_design_tokens() API.
	977	+ *
	978	+ * @param string $hook_suffix The current admin page's hook suffix.
	979	+ * @return void
	980	+ */
	981	+ public static function maybe_enqueue_design_tokens( $hook_suffix ) {
	982	+ if ( ! in_array( $hook_suffix, self::$page_hooks, true ) ) {
	983	+ return;
	984	+ }
	985	+
	986	+ self::enqueue_design_tokens();
	987	+ }
	988	+
	989	+ /**
	990	+ * Enqueues Tracks for the upgrade submenu item.
	991	+ *
	992	+ * @param array $asset Parsed contents of admin-ui-upgrade-menu.asset.php.
	993	+ * @return void
	994	+ */
	995	+ private static function enqueue_upgrade_menu_tracks_script( $asset ) {
	996	+ if ( ! class_exists( '\Automattic\Jetpack\Tracking' ) ) {
	997	+ return;
	998	+ }
	999	+
	1000	+ Tracking::register_tracks_functions_scripts( true );
	1001	+
	1002	+ wp_enqueue_script(
	1003	+ 'jetpack-admin-ui-upgrade-menu-tracking',
	1004	+ plugins_url( '../build/admin-ui-upgrade-menu-tracking.js', __FILE__ ),
	1005	+ $asset['dependencies'] ?? array(),
	1006	+ $asset['version'] ?? self::PACKAGE_VERSION,
	1007	+ true
	1008	+ );
	1009	+
	1010	+ $current_screen = get_current_screen();
	1011	+ $is_admin = current_user_can( 'jetpack_disconnect' );
	1012	+ $site_id = class_exists( 'Jetpack_Options' ) ? Jetpack_Options::get_option( 'id' ) : null;
	1013	+ $tracks_user_data = class_exists( 'Jetpack_Tracks_Client' ) ? Jetpack_Tracks_Client::get_connected_user_tracks_identity() : null;
	1014	+
	1015	+ wp_localize_script(
	1016	+ 'jetpack-admin-ui-upgrade-menu-tracking',
	1017	+ 'jetpackAdminUiUpgradeMenu',
	1018	+ array(
	1019	+ 'menuItemClass' => self::UPGRADE_MENU_SLUG,
	1020	+ 'tracksUserData' => $tracks_user_data,
	1021	+ 'tracksEventData' => array(
	1022	+ 'is_admin' => $is_admin,
	1023	+ 'current_screen' => $current_screen ? $current_screen->id : false,
	1024	+ 'blog_id' => $site_id,
	1025	+ ),
	1026	+ )
	1027	+ );
	1028	+ }
	1029	+}