6 * @subpackage Blocks |
6 * @subpackage Blocks |
7 * @since 5.5.0 |
7 * @since 5.5.0 |
8 */ |
8 */ |
9 |
9 |
10 /** |
10 /** |
11 * Class used for interacting with patterns. |
11 * Class used for interacting with block patterns. |
12 * |
12 * |
13 * @since 5.5.0 |
13 * @since 5.5.0 |
14 */ |
14 */ |
15 final class WP_Block_Patterns_Registry { |
15 final class WP_Block_Patterns_Registry { |
16 /** |
16 /** |
17 * Registered patterns array. |
17 * Registered block patterns array. |
18 * |
18 * |
19 * @since 5.5.0 |
19 * @since 5.5.0 |
20 * @var array |
20 * @var array[] |
21 */ |
21 */ |
22 private $registered_patterns = array(); |
22 private $registered_patterns = array(); |
23 |
23 |
24 /** |
24 /** |
|
25 * Patterns registered outside the `init` action. |
|
26 * |
|
27 * @since 6.0.0 |
|
28 * @var array[] |
|
29 */ |
|
30 private $registered_patterns_outside_init = array(); |
|
31 |
|
32 /** |
25 * Container for the main instance of the class. |
33 * Container for the main instance of the class. |
26 * |
34 * |
27 * @since 5.5.0 |
35 * @since 5.5.0 |
28 * @var WP_Block_Patterns_Registry|null |
36 * @var WP_Block_Patterns_Registry|null |
29 */ |
37 */ |
30 private static $instance = null; |
38 private static $instance = null; |
31 |
39 |
32 /** |
40 /** |
33 * Registers a pattern. |
41 * Registers a block pattern. |
34 * |
42 * |
35 * @since 5.5.0 |
43 * @since 5.5.0 |
36 * |
44 * @since 5.8.0 Added support for the `blockTypes` property. |
37 * @param string $pattern_name Pattern name including namespace. |
45 * |
38 * @param array $pattern_properties Array containing the properties of the pattern: title, |
46 * @param string $pattern_name Block pattern name including namespace. |
39 * content, description, viewportWidth, categories, keywords. |
47 * @param array $pattern_properties { |
|
48 * List of properties for the block pattern. |
|
49 * |
|
50 * @type string $title Required. A human-readable title for the pattern. |
|
51 * @type string $content Required. Block HTML markup for the pattern. |
|
52 * @type string $description Optional. Visually hidden text used to describe the pattern in the |
|
53 * inserter. A description is optional, but is strongly |
|
54 * encouraged when the title does not fully describe what the |
|
55 * pattern does. The description will help users discover the |
|
56 * pattern while searching. |
|
57 * @type int $viewportWidth Optional. The intended width of the pattern to allow for a scaled |
|
58 * preview within the pattern inserter. |
|
59 * @type array $categories Optional. A list of registered pattern categories used to group block |
|
60 * patterns. Block patterns can be shown on multiple categories. |
|
61 * A category must be registered separately in order to be used |
|
62 * here. |
|
63 * @type array $blockTypes Optional. A list of block names including namespace that could use |
|
64 * the block pattern in certain contexts (placeholder, transforms). |
|
65 * The block pattern is available in the block editor inserter |
|
66 * regardless of this list of block names. |
|
67 * Certain blocks support further specificity besides the block name |
|
68 * (e.g. for `core/template-part` you can specify areas |
|
69 * like `core/template-part/header` or `core/template-part/footer`). |
|
70 * @type array $keywords Optional. A list of aliases or keywords that help users discover the |
|
71 * pattern while searching. |
|
72 * } |
40 * @return bool True if the pattern was registered with success and false otherwise. |
73 * @return bool True if the pattern was registered with success and false otherwise. |
41 */ |
74 */ |
42 public function register( $pattern_name, $pattern_properties ) { |
75 public function register( $pattern_name, $pattern_properties ) { |
43 if ( ! isset( $pattern_name ) || ! is_string( $pattern_name ) ) { |
76 if ( ! isset( $pattern_name ) || ! is_string( $pattern_name ) ) { |
44 _doing_it_wrong( |
77 _doing_it_wrong( |
65 '5.5.0' |
98 '5.5.0' |
66 ); |
99 ); |
67 return false; |
100 return false; |
68 } |
101 } |
69 |
102 |
70 $this->registered_patterns[ $pattern_name ] = array_merge( |
103 $pattern = array_merge( |
71 $pattern_properties, |
104 $pattern_properties, |
72 array( 'name' => $pattern_name ) |
105 array( 'name' => $pattern_name ) |
73 ); |
106 ); |
|
107 $this->registered_patterns[ $pattern_name ] = $pattern; |
|
108 |
|
109 // If the pattern is registered inside an action other than `init`, store it |
|
110 // also to a dedicated array. Used to detect deprecated registrations inside |
|
111 // `admin_init` or `current_screen`. |
|
112 if ( current_action() && 'init' !== current_action() ) { |
|
113 $this->registered_patterns_outside_init[ $pattern_name ] = $pattern; |
|
114 } |
74 |
115 |
75 return true; |
116 return true; |
76 } |
117 } |
77 |
118 |
78 /** |
119 /** |
79 * Unregisters a pattern. |
120 * Unregisters a block pattern. |
80 * |
121 * |
81 * @since 5.5.0 |
122 * @since 5.5.0 |
82 * |
123 * |
83 * @param string $pattern_name Pattern name including namespace. |
124 * @param string $pattern_name Block pattern name including namespace. |
84 * @return bool True if the pattern was unregistered with success and false otherwise. |
125 * @return bool True if the pattern was unregistered with success and false otherwise. |
85 */ |
126 */ |
86 public function unregister( $pattern_name ) { |
127 public function unregister( $pattern_name ) { |
87 if ( ! $this->is_registered( $pattern_name ) ) { |
128 if ( ! $this->is_registered( $pattern_name ) ) { |
88 _doing_it_wrong( |
129 _doing_it_wrong( |
93 ); |
134 ); |
94 return false; |
135 return false; |
95 } |
136 } |
96 |
137 |
97 unset( $this->registered_patterns[ $pattern_name ] ); |
138 unset( $this->registered_patterns[ $pattern_name ] ); |
|
139 unset( $this->registered_patterns_outside_init[ $pattern_name ] ); |
98 |
140 |
99 return true; |
141 return true; |
100 } |
142 } |
101 |
143 |
102 /** |
144 /** |
103 * Retrieves an array containing the properties of a registered pattern. |
145 * Retrieves an array containing the properties of a registered block pattern. |
104 * |
146 * |
105 * @since 5.5.0 |
147 * @since 5.5.0 |
106 * |
148 * |
107 * @param string $pattern_name Pattern name including namespace. |
149 * @param string $pattern_name Block pattern name including namespace. |
108 * @return array Registered pattern properties. |
150 * @return array Registered pattern properties. |
109 */ |
151 */ |
110 public function get_registered( $pattern_name ) { |
152 public function get_registered( $pattern_name ) { |
111 if ( ! $this->is_registered( $pattern_name ) ) { |
153 if ( ! $this->is_registered( $pattern_name ) ) { |
112 return null; |
154 return null; |
114 |
156 |
115 return $this->registered_patterns[ $pattern_name ]; |
157 return $this->registered_patterns[ $pattern_name ]; |
116 } |
158 } |
117 |
159 |
118 /** |
160 /** |
119 * Retrieves all registered patterns. |
161 * Retrieves all registered block patterns. |
120 * |
162 * |
121 * @since 5.5.0 |
163 * @since 5.5.0 |
122 * |
164 * |
123 * @return array Array of arrays containing the registered patterns properties, |
165 * @param bool $outside_init_only Return only patterns registered outside the `init` action. |
124 * and per style. |
166 * @return array[] Array of arrays containing the registered block patterns properties, |
125 */ |
167 * and per style. |
126 public function get_all_registered() { |
168 */ |
127 return array_values( $this->registered_patterns ); |
169 public function get_all_registered( $outside_init_only = false ) { |
128 } |
170 return array_values( |
129 |
171 $outside_init_only |
130 /** |
172 ? $this->registered_patterns_outside_init |
131 * Checks if a pattern is registered. |
173 : $this->registered_patterns |
132 * |
174 ); |
133 * @since 5.5.0 |
175 } |
134 * |
176 |
135 * @param string $pattern_name Pattern name including namespace. |
177 /** |
|
178 * Checks if a block pattern is registered. |
|
179 * |
|
180 * @since 5.5.0 |
|
181 * |
|
182 * @param string $pattern_name Block pattern name including namespace. |
136 * @return bool True if the pattern is registered, false otherwise. |
183 * @return bool True if the pattern is registered, false otherwise. |
137 */ |
184 */ |
138 public function is_registered( $pattern_name ) { |
185 public function is_registered( $pattern_name ) { |
139 return isset( $this->registered_patterns[ $pattern_name ] ); |
186 return isset( $this->registered_patterns[ $pattern_name ] ); |
140 } |
187 } |
156 return self::$instance; |
203 return self::$instance; |
157 } |
204 } |
158 } |
205 } |
159 |
206 |
160 /** |
207 /** |
161 * Registers a new pattern. |
208 * Registers a new block pattern. |
162 * |
209 * |
163 * @since 5.5.0 |
210 * @since 5.5.0 |
164 * |
211 * |
165 * @param string $pattern_name Pattern name including namespace. |
212 * @param string $pattern_name Block pattern name including namespace. |
166 * @param array $pattern_properties Array containing the properties of the pattern. |
213 * @param array $pattern_properties List of properties for the block pattern. |
|
214 * See WP_Block_Patterns_Registry::register() for accepted arguments. |
167 * @return bool True if the pattern was registered with success and false otherwise. |
215 * @return bool True if the pattern was registered with success and false otherwise. |
168 */ |
216 */ |
169 function register_block_pattern( $pattern_name, $pattern_properties ) { |
217 function register_block_pattern( $pattern_name, $pattern_properties ) { |
170 return WP_Block_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties ); |
218 return WP_Block_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties ); |
171 } |
219 } |
172 |
220 |
173 /** |
221 /** |
174 * Unregisters a pattern. |
222 * Unregisters a block pattern. |
175 * |
223 * |
176 * @since 5.5.0 |
224 * @since 5.5.0 |
177 * |
225 * |
178 * @param string $pattern_name Pattern name including namespace. |
226 * @param string $pattern_name Block pattern name including namespace. |
179 * @return bool True if the pattern was unregistered with success and false otherwise. |
227 * @return bool True if the pattern was unregistered with success and false otherwise. |
180 */ |
228 */ |
181 function unregister_block_pattern( $pattern_name ) { |
229 function unregister_block_pattern( $pattern_name ) { |
182 return WP_Block_Patterns_Registry::get_instance()->unregister( $pattern_name ); |
230 return WP_Block_Patterns_Registry::get_instance()->unregister( $pattern_name ); |
183 } |
231 } |