Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
90.74%
49 / 54
100.00%
5 / 5
 CRAP
n/a
0 / 0
Automattic\Jetpack\PremiumAnalytics\get_dashboard_default_widget_instance
100.00%
12 / 12
100.00%
1 / 1
 2
Automattic\Jetpack\PremiumAnalytics\remove_unsupported_default_layout_items
100.00%
6 / 6
100.00%
1 / 1
 2
Automattic\Jetpack\PremiumAnalytics\get_answering_widget_type_registry
100.00%
5 / 5
100.00%
1 / 1
 4
Automattic\Jetpack\PremiumAnalytics\resolve_former_widget_types_in_default_layout
100.00%
11 / 11
100.00%
1 / 1
 5
Automattic\Jetpack\PremiumAnalytics\remove_unregistered_default_layout_items
100.00%
15 / 15
100.00%
1 / 1
 4
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
13namespace Automattic\Jetpack\PremiumAnalytics;
14
15if ( ! defined( 'ABSPATH' ) ) {
16    exit( 0 );
17}
18
19// Availability policy for default layout instances: defaults are read outside
20// the widget registry bootstrap, so the policy must be loaded here explicitly.
21require_once __DIR__ . '/widget-type-support.php';
22
23/**
24 * Identifier of the Premium Analytics dashboard, formatted as `<plugin>_<page>`
25 * to match the underscore form produced by the wp-build pipeline. Used as the
26 * `{name}` segment of the sections REST route.
27 */
28const DASHBOARD_NAME = 'jetpack-premium-analytics_dashboard';
29
30/**
31 * Filter through which a section's default layout is resolved. Documented where it
32 * runs, in Dashboard_Section::get_default_layout().
33 */
34const DASHBOARD_DEFAULT_LAYOUT_FILTER = 'jetpack_premium_analytics_dashboard_default_layout';
35
36/**
37 * Filter through which the widget types a section's inserter offers beyond its default layout
38 * are resolved. Documented where it runs, in Dashboard_Section::get_insertable_widget_types().
39 *
40 * @since 0.13.0
41 */
42const DASHBOARD_INSERTABLE_WIDGET_TYPES_FILTER = 'jetpack_premium_analytics_dashboard_insertable_widget_types';
43
44/**
45 * Tile heights for default layouts, in dashboard rows: a one-line strip of highlights.
46 *
47 * @since 0.17.0
48 */
49const DASHBOARD_TILE_STRIP = 1;
50
51/**
52 * A chart, a figure or a short list.
53 *
54 * @since 0.17.0
55 */
56const DASHBOARD_TILE_CARD = 2;
57
58/**
59 * A leaderboard tall enough for the ten rows the stats endpoints return by default.
60 *
61 * @since 0.17.0
62 */
63const DASHBOARD_TILE_LIST = 3;
64
65/**
66 * Builds a widget instance for a section's default layout.
67 *
68 * @param string            $uuid       Widget instance UUID.
69 * @param string            $type       Widget type.
70 * @param int               $order      Widget placement order.
71 * @param int|'full'|'fill' $width      Column span, 'full' to span the grid, or 'fill' for the rest of the row.
72 * @param int               $height     Widget placement height in rows; see the DASHBOARD_TILE_* constants.
73 * @param array             $attributes Optional widget attributes.
74 * @return array Widget instance.
75 */
76function get_dashboard_default_widget_instance(
77    $uuid,
78    $type,
79    $order,
80    $width = 1,
81    $height = DASHBOARD_TILE_CARD,
82    $attributes = array()
83) {
84    $widget = array(
85        'uuid' => $uuid,
86        'type' => $type,
87    );
88
89    if ( ! empty( $attributes ) ) {
90        $widget['attributes'] = $attributes;
91    }
92
93    $widget['placement'] = array(
94        'width'  => $width,
95        'height' => $height,
96        'order'  => $order,
97    );
98
99    return $widget;
100}
101
102/**
103 * Drops the widget instances the site cannot serve from a section's default layout.
104 *
105 * A persisted layout keeps such an instance as a removable ghost widget; a default must not
106 * seed one. Hooked late, after the callbacks that add instances, so it covers those too.
107 *
108 * @param array $layout Default widget instances.
109 * @return array The layout minus the unsupported instances.
110 */
111function remove_unsupported_default_layout_items( $layout ) {
112    $layout = remove_unsupported_widget_items(
113        is_array( $layout ) ? $layout : array(),
114        'type',
115        get_widget_support_context()
116    );
117
118    return remove_unregistered_default_layout_items( $layout );
119}
120add_filter( DASHBOARD_DEFAULT_LAYOUT_FILTER, __NAMESPACE__ . '\\remove_unsupported_default_layout_items', 100 );
121
122/**
123 * The widget type registry once it can answer, or null before that.
124 *
125 * It cannot answer before `init`, without the widget type API loaded, or with nothing registered,
126 * which is a checkout without a build.
127 *
128 * @since 0.11.0
129 *
130 * @return Widget_Type_Registry|null
131 */
132function get_answering_widget_type_registry() {
133    if ( ! did_action( 'init' ) || ! function_exists( __NAMESPACE__ . '\\ensure_widget_registry_ready' ) ) {
134        return null;
135    }
136
137    ensure_widget_registry_ready();
138    $registry = Widget_Type_Registry::get_instance();
139
140    return $registry->get_all_registered() ? $registry : null;
141}
142
143/**
144 * Renames the widget instances whose type is a former name of a registered widget type.
145 *
146 * Hooked before the unregistered-type check, so an instance a plugin still adds under an old
147 * name survives it under the current one.
148 *
149 * @since 0.11.0
150 *
151 * @param array $layout Default widget instances.
152 * @return array The layout with current type names.
153 */
154function resolve_former_widget_types_in_default_layout( $layout ) {
155    $registry = get_answering_widget_type_registry();
156    if ( ! $registry || ! is_array( $layout ) ) {
157        return $layout;
158    }
159
160    return array_map(
161        static function ( $item ) use ( $registry ) {
162            if ( is_array( $item ) && is_string( $item['type'] ?? null ) ) {
163                $item['type'] = $registry->resolve_name( $item['type'] );
164            }
165            return $item;
166        },
167        $layout
168    );
169}
170add_filter( DASHBOARD_DEFAULT_LAYOUT_FILTER, __NAMESPACE__ . '\\resolve_former_widget_types_in_default_layout', 99 );
171
172/**
173 * Drops the widget instances whose type the widget type registry does not know.
174 *
175 * Only once the registry can answer: after `init`, with the widget type API loaded and at least
176 * one type registered. Before that, or on a checkout without a build, the default stays as
177 * declared rather than emptying itself.
178 *
179 * @since 0.9.0
180 *
181 * @param array $layout Default widget instances.
182 * @return array The layout minus the instances of unregistered types.
183 */
184function remove_unregistered_default_layout_items( $layout ) {
185    $registry = get_answering_widget_type_registry();
186    if ( ! $registry ) {
187        return $layout;
188    }
189    $registered = $registry->get_all_registered();
190
191    return array_values(
192        array_filter(
193            $layout,
194            static function ( $item ) use ( $registered ) {
195                if ( ! is_array( $item ) ) {
196                    return true;
197                }
198                // A non-string type, say the Widget_Type object register_widget_type() returns, is an
199                // unknown type, not a TypeError for the whole sections route.
200                $type = $item['type'] ?? '';
201                return is_string( $type ) && isset( $registered[ $type ] );
202            }
203        )
204    );
205}