| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
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] 18 class 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 * @return string|string[]|null The value read from the new property if the first item in the array provided, 361 * null when value not found or when unknown property name provided. 362 */ 363 public function __get( $name ) { 364 if ( 'variations' === $name ) { 365 return $this->get_variations(); 366 } 367 368 if ( 'uses_context' === $name ) { 369 return $this->get_uses_context(); 370 } 371 372 if ( ! in_array( $name, $this->deprecated_properties, true ) ) { 373 return null; 374 } 375 376 $new_name = $name . '_handles'; 377 378 if ( ! property_exists( $this, $new_name ) || ! is_array( $this->{$new_name} ) ) { 379 return null; 380 } 381 382 if ( count( $this->{$new_name} ) > 1 ) { 383 return $this->{$new_name}; 384 } 385 return $this->{$new_name}[0] ?? null; 386 } 387 388 /** 389 * Proxies checking for deprecated properties for script and style handles for backward compatibility. 390 * Checks whether the corresponding new property has the first item in the array provided. 391 * 392 * @since 6.1.0 393 * 394 * @param string $name Deprecated property name. 395 * @return bool Returns true when for the new property the first item in the array exists, 396 * or false otherwise. 397 */ 398 public function __isset( $name ) { 399 if ( in_array( $name, array( 'variations', 'uses_context' ), true ) ) { 400 return true; 401 } 402 403 if ( ! in_array( $name, $this->deprecated_properties, true ) ) { 404 return false; 405 } 406 407 $new_name = $name . '_handles'; 408 return isset( $this->{$new_name}[0] ); 409 } 410 411 /** 412 * Proxies setting values for deprecated properties for script and style handles for backward compatibility. 413 * Sets the value for the corresponding new property as the first item in the array. 414 * It also allows setting custom properties for backward compatibility. 415 * 416 * @since 6.1.0 417 * 418 * @param string $name Property name. 419 * @param mixed $value Property value. 420 */ 421 public function __set( $name, $value ) { 422 if ( ! in_array( $name, $this->deprecated_properties, true ) ) { 423 $this->{$name} = $value; 424 return; 425 } 426 427 $new_name = $name . '_handles'; 428 429 if ( is_array( $value ) ) { 430 $filtered = array_filter( $value, 'is_string' ); 431 432 if ( count( $filtered ) !== count( $value ) ) { 433 _doing_it_wrong( 434 __METHOD__, 435 sprintf( 436 /* translators: %s: The '$value' argument. */ 437 __( 'The %s argument must be a string or a string array.' ), 438 '<code>$value</code>' 439 ), 440 '6.1.0' 441 ); 442 } 443 444 $this->{$new_name} = array_values( $filtered ); 445 return; 446 } 447 448 if ( ! is_string( $value ) ) { 449 return; 450 } 451 452 $this->{$new_name} = array( $value ); 453 } 454 455 /** 456 * Renders the block type output for given attributes. 457 * 458 * @since 5.0.0 459 * 460 * @param array $attributes Optional. Block attributes. Default empty array. 461 * @param string $content Optional. Block content. Default empty string. 462 * @return string Rendered block type output. 463 */ 464 public function render( $attributes = array(), $content = '' ) { 465 if ( ! $this->is_dynamic() ) { 466 return ''; 467 } 468 469 $attributes = $this->prepare_attributes_for_render( $attributes ); 470 471 return (string) call_user_func( $this->render_callback, $attributes, $content ); 472 } 473 474 /** 475 * Returns true if the block type is dynamic, or false otherwise. A dynamic 476 * block is one which defers its rendering to occur on-demand at runtime. 477 * 478 * @since 5.0.0 479 * 480 * @return bool Whether block type is dynamic. 481 */ 482 public function is_dynamic() { 483 return is_callable( $this->render_callback ); 484 } 485 486 /** 487 * Validates attributes against the current block schema, populating 488 * defaulted and missing values. 489 * 490 * @since 5.0.0 491 * 492 * @param array $attributes Original block attributes. 493 * @return array Prepared block attributes. 494 */ 495 public function prepare_attributes_for_render( $attributes ) { 496 // If there are no attribute definitions for the block type, skip 497 // processing and return verbatim. 498 if ( ! isset( $this->attributes ) ) { 499 return $attributes; 500 } 501 502 foreach ( $attributes as $attribute_name => $value ) { 503 // If the attribute is not defined by the block type, it cannot be 504 // validated. 505 if ( ! isset( $this->attributes[ $attribute_name ] ) ) { 506 continue; 507 } 508 509 $schema = $this->attributes[ $attribute_name ]; 510 511 // Validate value by JSON schema. An invalid value should revert to 512 // its default, if one exists. This occurs by virtue of the missing 513 // attributes loop immediately following. If there is not a default 514 // assigned, the attribute value should remain unset. 515 $is_valid = rest_validate_value_from_schema( $value, $schema, $attribute_name ); 516 if ( is_wp_error( $is_valid ) ) { 517 unset( $attributes[ $attribute_name ] ); 518 } 519 } 520 521 // Populate values of any missing attributes for which the block type 522 // defines a default. 523 $missing_schema_attributes = array_diff_key( $this->attributes, $attributes ); 524 foreach ( $missing_schema_attributes as $attribute_name => $schema ) { 525 if ( isset( $schema['default'] ) ) { 526 $attributes[ $attribute_name ] = $schema['default']; 527 } 528 } 529 530 return $attributes; 531 } 532 533 /** 534 * Sets block type properties. 535 * 536 * @since 5.0.0 537 * 538 * @param array|string $args Array or string of arguments for registering a block type. 539 * See WP_Block_Type::__construct() for information on accepted arguments. 540 */ 541 public function set_props( $args ) { 542 $args = wp_parse_args( 543 $args, 544 array( 545 'render_callback' => null, 546 ) 547 ); 548 549 $args['name'] = $this->name; 550 551 // Setup attributes if needed. 552 if ( ! isset( $args['attributes'] ) || ! is_array( $args['attributes'] ) ) { 553 $args['attributes'] = array(); 554 } 555 556 // Register core attributes. 557 foreach ( static::GLOBAL_ATTRIBUTES as $attr_key => $attr_schema ) { 558 if ( ! array_key_exists( $attr_key, $args['attributes'] ) ) { 559 $args['attributes'][ $attr_key ] = $attr_schema; 560 } 561 } 562 563 /** 564 * Filters the arguments for registering a block type. 565 * 566 * @since 5.5.0 567 * 568 * @param array $args Array of arguments for registering a block type. 569 * @param string $block_type Block type name including namespace. 570 */ 571 $args = apply_filters( 'register_block_type_args', $args, $this->name ); 572 573 foreach ( $args as $property_name => $property_value ) { 574 $this->$property_name = $property_value; 575 } 576 } 577 578 /** 579 * Get all available block attributes including possible layout attribute from Columns block. 580 * 581 * @since 5.0.0 582 * 583 * @return array Array of attributes. 584 */ 585 public function get_attributes() { 586 return is_array( $this->attributes ) ? 587 $this->attributes : 588 array(); 589 } 590 591 /** 592 * Get block variations. 593 * 594 * @since 6.5.0 595 * 596 * @return array[] 597 */ 598 public function get_variations() { 599 if ( ! isset( $this->variations ) ) { 600 $this->variations = array(); 601 if ( is_callable( $this->variation_callback ) ) { 602 $this->variations = call_user_func( $this->variation_callback ); 603 } 604 } 605 606 /** 607 * Filters the registered variations for a block type. 608 * 609 * @since 6.5.0 610 * 611 * @param array $variations Array of registered variations for a block type. 612 * @param WP_Block_Type $block_type The full block type object. 613 */ 614 return apply_filters( 'get_block_type_variations', $this->variations, $this ); 615 } 616 617 /** 618 * Get block uses context. 619 * 620 * @since 6.5.0 621 * 622 * @return string[] 623 */ 624 public function get_uses_context() { 625 /** 626 * Filters the registered uses context for a block type. 627 * 628 * @since 6.5.0 629 * 630 * @param string[] $uses_context Array of registered uses context for a block type. 631 * @param WP_Block_Type $block_type The full block type object. 632 */ 633 return apply_filters( 'get_block_type_uses_context', $this->uses_context, $this ); 634 } 635 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Mon Aug 31 08:20:24 2026 | Cross-referenced by PHPXref |