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