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