1<?php
2/**
3 * Blocks API: WP_Block_Type class
4 *
5 * @package WordPress
6 * @subpackage Blocks
7 * @since 5.0.0
8 */
9
10/**
11 * Core class representing a block type.
12 *
13 * @since 5.0.0
14 *
15 * @see register_block_type()
16 */
17#[AllowDynamicProperties]
18class WP_Block_Type {
19
20 /**
21 * Block API version.
22 *
23 * @since 5.6.0
24 * @var int
25 */
26 public $api_version = 1;
27
28 /**
29 * Block type key.
30 *
31 * @since 5.0.0
32 * @var string
33 */
34 public $name;
35
36 /**
37 * Human-readable block type label.
38 *
39 * @since 5.5.0
40 * @var string
41 */
42 public $title = '';
43
44 /**
45 * Block type category classification, used in search interfaces
46 * to arrange block types by category.
47 *
48 * @since 5.5.0
49 * @var string|null
50 */
51 public $category = null;
52
53 /**
54 * Setting parent lets a block require that it is only available
55 * when nested within the specified blocks.
56 *
57 * @since 5.5.0
58 * @var string[]|null
59 */
60 public $parent = null;
61
62 /**
63 * Setting ancestor makes a block available only inside the specified
64 * block types at any position of the ancestor's block subtree.
65 *
66 * @since 6.0.0
67 * @var string[]|null
68 */
69 public $ancestor = null;
70
71 /**
72 * Limits which block types can be inserted as children of this block type.
73 *
74 * @since 6.5.0
75 * @var string[]|null
76 */
77 public $allowed_blocks = null;
78
79 /**
80 * Block type icon.
81 *
82 * @since 5.5.0
83 * @var string|null
84 */
85 public $icon = null;
86
87 /**
88 * A detailed block type description.
89 *
90 * @since 5.5.0
91 * @var string
92 */
93 public $description = '';
94
95 /**
96 * Additional keywords to produce block type as result
97 * in search interfaces.
98 *
99 * @since 5.5.0
100 * @var string[]
101 */
102 public $keywords = array();
103
104 /**
105 * The translation textdomain.
106 *
107 * @since 5.5.0
108 * @var string|null
109 */
110 public $textdomain = null;
111
112 /**
113 * Alternative block styles.
114 *
115 * @since 5.5.0
116 * @var array
117 */
118 public $styles = array();
119
120 /**
121 * Block variations.
122 *
123 * @since 5.8.0
124 * @since 6.5.0 Only accessible through magic getter. null by default.
125 * @var array[]|null
126 */
127 private $variations = null;
128
129 /**
130 * Block variations callback.
131 *
132 * @since 6.5.0
133 * @var callable|null
134 */
135 public $variation_callback = null;
136
137 /**
138 * Custom CSS selectors for theme.json style generation.
139 *
140 * @since 6.3.0
141 * @var array
142 */
143 public $selectors = array();
144
145 /**
146 * Supported features.
147 *
148 * @since 5.5.0
149 * @var array|null
150 */
151 public $supports = null;
152
153 /**
154 * Structured data for the block preview.
155 *
156 * @since 5.5.0
157 * @var array|null
158 */
159 public $example = null;
160
161 /**
162 * Block type render callback.
163 *
164 * @since 5.0.0
165 * @var callable
166 */
167 public $render_callback = null;
168
169 /**
170 * Block type attributes property schemas.
171 *
172 * @since 5.0.0
173 * @var array|null
174 */
175 public $attributes = null;
176
177 /**
178 * Context values inherited by blocks of this type.
179 *
180 * @since 5.5.0
181 * @var string[]
182 */
183 private $uses_context = array();
184
185 /**
186 * Context provided by blocks of this type.
187 *
188 * @since 5.5.0
189 * @var string[]|null
190 */
191 public $provides_context = null;
192
193 /**
194 * Block hooks for this block type.
195 *
196 * A block hook is specified by a block type and a relative position.
197 * The hooked block will be automatically inserted in the given position
198 * next to the "anchor" block whenever the latter is encountered.
199 *
200 * @since 6.4.0
201 * @var string[]
202 */
203 public $block_hooks = array();
204
205 /**
206 * Block type editor only script handles.
207 *
208 * @since 6.1.0
209 * @var string[]
210 */
211 public $editor_script_handles = array();
212
213 /**
214 * Block type front end and editor script handles.
215 *
216 * @since 6.1.0
217 * @var string[]
218 */
219 public $script_handles = array();
220
221 /**
222 * Block type front end only script handles.
223 *
224 * @since 6.1.0
225 * @var string[]
226 */
227 public $view_script_handles = array();
228
229 /**
230 * Block type front end only script module IDs.
231 *
232 * @since 6.5.0
233 * @var string[]
234 */
235 public $view_script_module_ids = array();
236
237 /**
238 * Block type editor only style handles.
239 *
240 * @since 6.1.0
241 * @var string[]
242 */
243 public $editor_style_handles = array();
244
245 /**
246 * Block type front end and editor style handles.
247 *
248 * @since 6.1.0
249 * @var string[]
250 */
251 public $style_handles = array();
252
253 /**
254 * Block type front end only style handles.
255 *
256 * @since 6.5.0
257 * @var string[]
258 */
259 public $view_style_handles = array();
260
261 /**
262 * Deprecated block type properties for script and style handles.
263 *
264 * @since 6.1.0
265 * @var string[]
266 */
267 private $deprecated_properties = array(
268 'editor_script',
269 'script',
270 'view_script',
271 'editor_style',
272 'style',
273 );
274
275 /**
276 * Attributes supported by every block.
277 *
278 * @since 6.0.0 Added `lock`.
279 * @since 6.5.0 Added `metadata`.
280 * @var array
281 */
282 const GLOBAL_ATTRIBUTES = array(
283 'lock' => array( 'type' => 'object' ),
284 'metadata' => array( 'type' => 'object' ),
285 );
286
287 /**
288 * Constructor.
289 *
290 * Will populate object properties from the provided arguments.
291 *
292 * @since 5.0.0
293 * @since 5.5.0 Added the `title`, `category`, `parent`, `icon`, `description`,
294 * `keywords`, `textdomain`, `styles`, `supports`, `example`,
295 * `uses_context`, and `provides_context` properties.
296 * @since 5.6.0 Added the `api_version` property.
297 * @since 5.8.0 Added the `variations` property.
298 * @since 5.9.0 Added the `view_script` property.
299 * @since 6.0.0 Added the `ancestor` property.
300 * @since 6.1.0 Added the `editor_script_handles`, `script_handles`, `view_script_handles`,
301 * `editor_style_handles`, and `style_handles` properties.
302 * Deprecated the `editor_script`, `script`, `view_script`, `editor_style`, and `style` properties.
303 * @since 6.3.0 Added the `selectors` property.
304 * @since 6.4.0 Added the `block_hooks` property.
305 * @since 6.5.0 Added the `allowed_blocks`, `variation_callback`, and `view_style_handles` properties.
306 *
307 * @see register_block_type()
308 *
309 * @param string $block_type Block type name including namespace.
310 * @param array|string $args {
311 * Optional. Array or string of arguments for registering a block type. Any arguments may be defined,
312 * however the ones described below are supported by default. Default empty array.
313 *
314 * @type string $api_version Block API version.
315 * @type string $title Human-readable block type label.
316 * @type string|null $category Block type category classification, used in
317 * search interfaces to arrange block types by category.
318 * @type string[]|null $parent Setting parent lets a block require that it is only
319 * available when nested within the specified blocks.
320 * @type string[]|null $ancestor Setting ancestor makes a block available only inside the specified
321 * block types at any position of the ancestor's block subtree.
322 * @type string[]|null $allowed_blocks Limits which block types can be inserted as children of this block type.
323 * @type string|null $icon Block type icon.
324 * @type string $description A detailed block type description.
325 * @type string[] $keywords Additional keywords to produce block type as
326 * result in search interfaces.
327 * @type string|null $textdomain The translation textdomain.
328 * @type array[] $styles Alternative block styles.
329 * @type array[] $variations Block variations.
330 * @type array $selectors Custom CSS selectors for theme.json style generation.
331 * @type array|null $supports Supported features.
332 * @type array|null $example Structured data for the block preview.
333 * @type callable|null $render_callback Block type render callback.
334 * @type callable|null $variation_callback Block type variations callback.
335 * @type array|null $attributes Block type attributes property schemas.
336 * @type string[] $uses_context Context values inherited by blocks of this type.
337 * @type string[]|null $provides_context Context provided by blocks of this type.
338 * @type string[] $block_hooks Block hooks.
339 * @type string[] $editor_script_handles Block type editor only script handles.
340 * @type string[] $script_handles Block type front end and editor script handles.
341 * @type string[] $view_script_handles Block type front end only script handles.
342 * @type string[] $editor_style_handles Block type editor only style handles.
343 * @type string[] $style_handles Block type front end and editor style handles.
344 * @type string[] $view_style_handles Block type front end only style handles.
345 * }
346 */
347 public function __construct( $block_type, $args = array() ) {
348 $this->name = $block_type;
349
350 $this->set_props( $args );
351 }
352
353 /**
354 * Proxies getting values for deprecated properties for script and style handles for backward compatibility.
355 * Gets the value for the corresponding new property if the first item in the array provided.
356 *
357 * @since 6.1.0
358 *
359 * @param string $name Deprecated property name.
360 *
361 * @return string|string[]|null|void The value read from the new property if the first item in the array provided,
362 * null when value not found, or void when unknown property name provided.
363 */
364 public function __get( $name ) {
365 if ( 'variations' === $name ) {
366 return $this->get_variations();
367 }
368
369 if ( 'uses_context' === $name ) {
370 return $this->get_uses_context();
371 }
372
373 if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
374 return;
375 }
376
377 $new_name = $name . '_handles';
378
379 if ( ! property_exists( $this, $new_name ) || ! is_array( $this->{$new_name} ) ) {
380 return null;
381 }
382
383 if ( count( $this->{$new_name} ) > 1 ) {
384 return $this->{$new_name};
385 }
386 return isset( $this->{$new_name}[0] ) ? $this->{$new_name}[0] : null;
387 }
388
389 /**
390 * Proxies checking for deprecated properties for script and style handles for backward compatibility.
391 * Checks whether the corresponding new property has the first item in the array provided.
392 *
393 * @since 6.1.0
394 *
395 * @param string $name Deprecated property name.
396 *
397 * @return bool Returns true when for the new property the first item in the array exists,
398 * or false otherwise.
399 */
400 public function __isset( $name ) {
401 if ( in_array( $name, array( 'variations', 'uses_context' ), true ) ) {
402 return true;
403 }
404
405 if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
406 return false;
407 }
408
409 $new_name = $name . '_handles';
410 return isset( $this->{$new_name}[0] );
411 }
412
413 /**
414 * Proxies setting values for deprecated properties for script and style handles for backward compatibility.
415 * Sets the value for the corresponding new property as the first item in the array.
416 * It also allows setting custom properties for backward compatibility.
417 *
418 * @since 6.1.0
419 *
420 * @param string $name Property name.
421 * @param mixed $value Property value.
422 */
423 public function __set( $name, $value ) {
424 if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
425 $this->{$name} = $value;
426 return;
427 }
428
429 $new_name = $name . '_handles';
430
431 if ( is_array( $value ) ) {
432 $filtered = array_filter( $value, 'is_string' );
433
434 if ( count( $filtered ) !== count( $value ) ) {
435 _doing_it_wrong(
436 __METHOD__,
437 sprintf(
438 /* translators: %s: The '$value' argument. */
439 __( 'The %s argument must be a string or a string array.' ),
440 '<code>$value</code>'
441 ),
442 '6.1.0'
443 );
444 }
445
446 $this->{$new_name} = array_values( $filtered );
447 return;
448 }
449
450 if ( ! is_string( $value ) ) {
451 return;
452 }
453
454 $this->{$new_name} = array( $value );
455 }
456
457 /**
458 * Renders the block type output for given attributes.
459 *
460 * @since 5.0.0
461 *
462 * @param array $attributes Optional. Block attributes. Default empty array.
463 * @param string $content Optional. Block content. Default empty string.
464 * @return string Rendered block type output.
465 */
466 public function render( $attributes = array(), $content = '' ) {
467 if ( ! $this->is_dynamic() ) {
468 return '';
469 }
470
471 $attributes = $this->prepare_attributes_for_render( $attributes );
472
473 return (string) call_user_func( $this->render_callback, $attributes, $content );
474 }
475
476 /**
477 * Returns true if the block type is dynamic, or false otherwise. A dynamic
478 * block is one which defers its rendering to occur on-demand at runtime.
479 *
480 * @since 5.0.0
481 *
482 * @return bool Whether block type is dynamic.
483 */
484 public function is_dynamic() {
485 return is_callable( $this->render_callback );
486 }
487
488 /**
489 * Validates attributes against the current block schema, populating
490 * defaulted and missing values.
491 *
492 * @since 5.0.0
493 *
494 * @param array $attributes Original block attributes.
495 * @return array Prepared block attributes.
496 */
497 public function prepare_attributes_for_render( $attributes ) {
498 // If there are no attribute definitions for the block type, skip
499 // processing and return verbatim.
500 if ( ! isset( $this->attributes ) ) {
501 return $attributes;
502 }
503
504 foreach ( $attributes as $attribute_name => $value ) {
505 // If the attribute is not defined by the block type, it cannot be
506 // validated.
507 if ( ! isset( $this->attributes[ $attribute_name ] ) ) {
508 continue;
509 }
510
511 $schema = $this->attributes[ $attribute_name ];
512
513 // Validate value by JSON schema. An invalid value should revert to
514 // its default, if one exists. This occurs by virtue of the missing
515 // attributes loop immediately following. If there is not a default
516 // assigned, the attribute value should remain unset.
517 $is_valid = rest_validate_value_from_schema( $value, $schema, $attribute_name );
518 if ( is_wp_error( $is_valid ) ) {
519 unset( $attributes[ $attribute_name ] );
520 }
521 }
522
523 // Populate values of any missing attributes for which the block type
524 // defines a default.
525 $missing_schema_attributes = array_diff_key( $this->attributes, $attributes );
526 foreach ( $missing_schema_attributes as $attribute_name => $schema ) {
527 if ( isset( $schema['default'] ) ) {
528 $attributes[ $attribute_name ] = $schema['default'];
529 }
530 }
531
532 return $attributes;
533 }
534
535 /**
536 * Sets block type properties.
537 *
538 * @since 5.0.0
539 *
540 * @param array|string $args Array or string of arguments for registering a block type.
541 * See WP_Block_Type::__construct() for information on accepted arguments.
542 */
543 public function set_props( $args ) {
544 $args = wp_parse_args(
545 $args,
546 array(
547 'render_callback' => null,
548 )
549 );
550
551 $args['name'] = $this->name;
552
553 // Setup attributes if needed.
554 if ( ! isset( $args['attributes'] ) || ! is_array( $args['attributes'] ) ) {
555 $args['attributes'] = array();
556 }
557
558 // Register core attributes.
559 foreach ( static::GLOBAL_ATTRIBUTES as $attr_key => $attr_schema ) {
560 if ( ! array_key_exists( $attr_key, $args['attributes'] ) ) {
561 $args['attributes'][ $attr_key ] = $attr_schema;
562 }
563 }
564
565 /**
566 * Filters the arguments for registering a block type.
567 *
568 * @since 5.5.0
569 *
570 * @param array $args Array of arguments for registering a block type.
571 * @param string $block_type Block type name including namespace.
572 */
573 $args = apply_filters( 'register_block_type_args', $args, $this->name );
574
575 foreach ( $args as $property_name => $property_value ) {
576 $this->$property_name = $property_value;
577 }
578 }
579
580 /**
581 * Get all available block attributes including possible layout attribute from Columns block.
582 *
583 * @since 5.0.0
584 *
585 * @return array Array of attributes.
586 */
587 public function get_attributes() {
588 return is_array( $this->attributes ) ?
589 $this->attributes :
590 array();
591 }
592
593 /**
594 * Get block variations.
595 *
596 * @since 6.5.0
597 *
598 * @return array[]
599 */
600 public function get_variations() {
601 if ( ! isset( $this->variations ) ) {
602 $this->variations = array();
603 if ( is_callable( $this->variation_callback ) ) {
604 $this->variations = call_user_func( $this->variation_callback );
605 }
606 }
607
608 /**
609 * Filters the registered variations for a block type.
610 *
611 * @since 6.5.0
612 *
613 * @param array $variations Array of registered variations for a block type.
614 * @param WP_Block_Type $block_type The full block type object.
615 */
616 return apply_filters( 'get_block_type_variations', $this->variations, $this );
617 }
618
619 /**
620 * Get block uses context.
621 *
622 * @since 6.5.0
623 *
624 * @return string[]
625 */
626 public function get_uses_context() {
627 /**
628 * Filters the registered uses context for a block type.
629 *
630 * @since 6.5.0
631 *
632 * @param string[] $uses_context Array of registered uses context for a block type.
633 * @param WP_Block_Type $block_type The full block type object.
634 */
635 return apply_filters( 'get_block_type_uses_context', $this->uses_context, $this );
636 }
637}
638