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