← All changes | jetpack_vendor/automattic/jetpack-premium-analytics/src/dashboard-layout.php +182 -0 16.2-beta → 16.3-beta View file →

		@@ -1,0 +1,182 @@
	1	+<?php
	2	+/**
	3	+ * Dashboard Layout: the default-layout primitives shared by the section API and its registrants.
	4	+ *
	5	+ * A section declares its default layout when it registers, and
	6	+ * Dashboard_Section::get_default_layout() runs it through DASHBOARD_DEFAULT_LAYOUT_FILTER: the
	7	+ * package drops the widget types the site cannot serve there, and a plugin may add its own
	8	+ * instances to any section.
	9	+ *
	10	+ * @package automattic/jetpack-premium-analytics
	11	+ */
	12	+
	13	+namespace Automattic\Jetpack\PremiumAnalytics;
	14	+
	15	+// Availability policy for default layout instances: defaults are read outside
	16	+// the widget registry bootstrap, so the policy must be loaded here explicitly.
	17	+require_once __DIR__ . '/widget-type-support.php';
	18	+
	19	+/**
	20	+ * Identifier of the Premium Analytics dashboard, formatted as `<plugin>_<page>`
	21	+ * to match the underscore form produced by the wp-build pipeline. Used as the
	22	+ * `{name}` segment of the sections REST route.
	23	+ */
	24	+const DASHBOARD_NAME = 'jetpack-premium-analytics_dashboard';
	25	+
	26	+/**
	27	+ * Filter through which a section's default layout is resolved. Documented where it
	28	+ * runs, in Dashboard_Section::get_default_layout().
	29	+ */
	30	+const DASHBOARD_DEFAULT_LAYOUT_FILTER = 'jetpack_premium_analytics_dashboard_default_layout';
	31	+
	32	+/**
	33	+ * Builds a widget instance for a section's default layout.
	34	+ *
	35	+ * @param string $uuid Widget instance UUID.
	36	+ * @param string $type Widget type.
	37	+ * @param int $order Widget placement order.
	38	+ * @param int $width Widget placement width.
	39	+ * @param int $height Widget placement height.
	40	+ * @param array $attributes Optional widget attributes.
	41	+ * @return array Widget instance.
	42	+ */
	43	+function get_dashboard_default_widget_instance(
	44	+ $uuid,
	45	+ $type,
	46	+ $order,
	47	+ $width = 1,
	48	+ $height = 1,
	49	+ $attributes = array()
	50	+) {
	51	+ $widget = array(
	52	+ 'uuid' => $uuid,
	53	+ 'type' => $type,
	54	+ );
	55	+
	56	+ if ( ! empty( $attributes ) ) {
	57	+ $widget['attributes'] = $attributes;
	58	+ }
	59	+
	60	+ $widget['placement'] = array(
	61	+ 'width' => $width,
	62	+ 'height' => $height,
	63	+ 'order' => $order,
	64	+ );
	65	+
	66	+ return $widget;
	67	+}
	68	+
	69	+/**
	70	+ * Drops the widget instances the site cannot serve from a section's default layout.
	71	+ *
	72	+ * A persisted layout keeps such an instance as a removable ghost widget; a default must not
	73	+ * seed one. Hooked late, after the callbacks that add instances, so it covers those too.
	74	+ *
	75	+ * @param array $layout Default widget instances.
	76	+ * @return array The layout minus the unsupported instances.
	77	+ */
	78	+function remove_unsupported_default_layout_items( $layout ) {
	79	+ $layout = remove_unsupported_widget_items(
	80	+ is_array( $layout ) ? $layout : array(),
	81	+ 'type',
	82	+ get_widget_support_context()
	83	+ );
	84	+
	85	+ return remove_unregistered_default_layout_items( $layout );
	86	+}
	87	+add_filter( DASHBOARD_DEFAULT_LAYOUT_FILTER, __NAMESPACE__ . '\\remove_unsupported_default_layout_items', 100 );
	88	+
	89	+/**
	90	+ * The widget type registry once it can answer, or null before that.
	91	+ *
	92	+ * It cannot answer before `init`, without the widget type API loaded, or with nothing registered,
	93	+ * which is a checkout without a build.
	94	+ *
	95	+ * @since 0.11.0
	96	+ *
	97	+ * @return Widget_Type_Registry|null
	98	+ */
	99	+function get_answering_widget_type_registry() {
	100	+ if ( ! did_action( 'init' ) || ! function_exists( __NAMESPACE__ . '\\ensure_widget_registry_ready' ) ) {
	101	+ return null;
	102	+ }
	103	+
	104	+ ensure_widget_registry_ready();
	105	+ $registry = Widget_Type_Registry::get_instance();
	106	+
	107	+ return $registry->get_all_registered() ? $registry : null;
	108	+}
	109	+
	110	+/**
	111	+ * Renames the widget instances whose type is a former name of a registered widget type.
	112	+ *
	113	+ * Hooked before the unregistered-type check, so an instance a plugin still adds under an old
	114	+ * name survives it under the current one.
	115	+ *
	116	+ * @since 0.11.0
	117	+ *
	118	+ * @param array $layout Default widget instances.
	119	+ * @return array The layout with current type names.
	120	+ */
	121	+function resolve_former_widget_types_in_default_layout( $layout ) {
	122	+ $registry = get_answering_widget_type_registry();
	123	+ if ( ! $registry || ! is_array( $layout ) ) {
	124	+ return $layout;
	125	+ }
	126	+
	127	+ return array_map(
	128	+ static function ( $item ) use ( $registry ) {
	129	+ if ( is_array( $item ) && is_string( $item['type'] ?? null ) ) {
	130	+ $item['type'] = $registry->resolve_name( $item['type'] );
	131	+ }
	132	+ return $item;
	133	+ },
	134	+ $layout
	135	+ );
	136	+}
	137	+add_filter( DASHBOARD_DEFAULT_LAYOUT_FILTER, __NAMESPACE__ . '\\resolve_former_widget_types_in_default_layout', 99 );
	138	+
	139	+/**
	140	+ * Drops the widget instances whose type the widget type registry does not know.
	141	+ *
	142	+ * Only once the registry can answer: after `init`, with the widget type API loaded and at least
	143	+ * one type registered. Before that, or on a checkout without a build, the default stays as
	144	+ * declared rather than emptying itself.
	145	+ *
	146	+ * @since 0.9.0
	147	+ *
	148	+ * @param array $layout Default widget instances.
	149	+ * @return array The layout minus the instances of unregistered types.
	150	+ */
	151	+function remove_unregistered_default_layout_items( $layout ) {
	152	+ $registry = get_answering_widget_type_registry();
	153	+ if ( ! $registry ) {
	154	+ return $layout;
	155	+ }
	156	+ $registered = $registry->get_all_registered();
	157	+
	158	+ return array_values(
	159	+ array_filter(
	160	+ $layout,
	161	+ static function ( $item ) use ( $registered ) {
	162	+ if ( ! is_array( $item ) ) {
	163	+ return true;
	164	+ }
	165	+ // A non-string type, say the Widget_Type object register_widget_type() returns, is an
	166	+ // unknown type, not a TypeError for the whole sections route.
	167	+ $type = $item['type'] ?? '';
	168	+ return is_string( $type ) && isset( $registered[ $type ] );
	169	+ }
	170	+ )
	171	+ );
	172	+}
	173	+
	174	+/**
	175	+ * No-op kept for older copies of the package: they guard their include of this file on this
	176	+ * symbol and call it from boot_routes(), so a newer copy loading first must still define it.
	177	+ *
	178	+ * @since 0.8.0 Registers nothing; the route it registered is gone.
	179	+ *
	180	+ * @return void
	181	+ */
	182	+function register_dashboard_default_layout_route() {}