gutenberg / lib / experimental / dashboard-widgets / class-wp-widget-type-registry.php

class-wp-widget-type-registry.php in Gutenberg 23.5.0, at lib/experimental/dashboard-widgets/class-wp-widget-type-registry.php

184 lines 5.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Widget Types API: WP_Widget_Type_Registry class.
4	*
5	* @package gutenberg
6	*/
7
8	if ( ! class_exists( 'WP_Widget_Type_Registry' ) ) {
9
10	/**
11	* Internal class used for interacting with widget types.
12	*
13	* Singleton registry that stores `WP_Widget_Type` instances keyed by their
14	* namespaced name. Hydrated once per request from the build manifest at
15	* `init`; consumers query the registry instead of re-parsing the manifest.
16	*/
17	#[AllowDynamicProperties]
18	final class WP_Widget_Type_Registry {
19
20	/**
21	* Registered widget types, as `$name => $instance` pairs.
22	*
23	* @var WP_Widget_Type[]
24	*/
25	private $registered_widget_types = array();
26
27	/**
28	* Container for the main instance of the class.
29	*
30	* @var WP_Widget_Type_Registry\|null
31	*/
32	private static $instance = null;
33
34	/**
35	* Registers a widget type.
36	*
37	* @param string\|WP_Widget_Type $name Widget type name including
38	* namespace, or alternatively a
39	* complete WP_Widget_Type instance.
40	* When an instance is provided the
41	* `$args` parameter is ignored.
42	* @param array $args Optional. Array of widget type
43	* arguments. Accepts any public
44	* property of `WP_Widget_Type`.
45	* Default empty array.
46	* @return WP_Widget_Type\|false The registered widget type on success,
47	* or false on failure.
48	*/
49	public function register( $name, $args = array() ) {
50	$widget_type = null;
51	if ( $name instanceof WP_Widget_Type ) {
52	$widget_type = $name;
53	$name = $widget_type->name;
54	}
55
56	if ( ! is_string( $name ) ) {
57	_doing_it_wrong(
58	__METHOD__,
59	__( 'Widget type names must be strings.', 'gutenberg' ),
60	'23.1.0'
61	);
62	return false;
63	}
64
65	if ( preg_match( '/[A-Z]+/', $name ) ) {
66	_doing_it_wrong(
67	__METHOD__,
68	__( 'Widget type names must not contain uppercase characters.', 'gutenberg' ),
69	'23.1.0'
70	);
71	return false;
72	}
73
74	$name_matcher = '/^[a-z0-9-]+\/[a-z0-9-]+$/';
75	if ( ! preg_match( $name_matcher, $name ) ) {
76	_doing_it_wrong(
77	__METHOD__,
78	__( 'Widget type names must contain a namespace prefix. Example: my-plugin/my-custom-widget-type', 'gutenberg' ),
79	'23.1.0'
80	);
81	return false;
82	}
83
84	if ( $this->is_registered( $name ) ) {
85	_doing_it_wrong(
86	__METHOD__,
87	/* translators: %s: Widget type name. */
88	sprintf( __( 'Widget type "%s" is already registered.', 'gutenberg' ), $name ),
89	'23.1.0'
90	);
91	return false;
92	}
93
94	if ( ! $widget_type ) {
95	$widget_type = new WP_Widget_Type( $name, $args );
96	}
97
98	$this->registered_widget_types[ $name ] = $widget_type;
99
100	return $widget_type;
101	}
102
103	/**
104	* Unregisters a widget type.
105	*
106	* @param string\|WP_Widget_Type $name Widget type name including
107	* namespace, or alternatively a
108	* complete WP_Widget_Type instance.
109	* @return WP_Widget_Type\|false The unregistered widget type on success,
110	* or false on failure.
111	*/
112	public function unregister( $name ) {
113	if ( $name instanceof WP_Widget_Type ) {
114	$name = $name->name;
115	}
116
117	if ( ! $this->is_registered( $name ) ) {
118	_doing_it_wrong(
119	__METHOD__,
120	/* translators: %s: Widget type name. */
121	sprintf( __( 'Widget type "%s" is not registered.', 'gutenberg' ), $name ),
122	'23.1.0'
123	);
124	return false;
125	}
126
127	$unregistered_widget_type = $this->registered_widget_types[ $name ];
128	unset( $this->registered_widget_types[ $name ] );
129
130	return $unregistered_widget_type;
131	}
132
133	/**
134	* Retrieves a registered widget type.
135	*
136	* @param string $name Widget type name including namespace.
137	* @return WP_Widget_Type\|null The registered widget type, or null if it
138	* is not registered.
139	*/
140	public function get_registered( $name ) {
141	if ( ! $this->is_registered( $name ) ) {
142	return null;
143	}
144
145	return $this->registered_widget_types[ $name ];
146	}
147
148	/**
149	* Retrieves all registered widget types.
150	*
151	* @return WP_Widget_Type[] Associative array of `$name => $widget_type`
152	* pairs.
153	*/
154	public function get_all_registered() {
155	return $this->registered_widget_types;
156	}
157
158	/**
159	* Checks if a widget type is registered.
160	*
161	* @param string $name Widget type name including namespace.
162	* @return bool True if the widget type is registered, false otherwise.
163	*/
164	public function is_registered( $name ) {
165	return isset( $this->registered_widget_types[ $name ] );
166	}
167
168	/**
169	* Utility method to retrieve the main instance of the class.
170	*
171	* The instance will be created if it does not exist yet.
172	*
173	* @return WP_Widget_Type_Registry The main instance.
174	*/
175	public static function get_instance() {
176	if ( null === self::$instance ) {
177	self::$instance = new self();
178	}
179
180	return self::$instance;
181	}
182	}
183	}
184