| [ 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 `view_style_handles` property. 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 array[] 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 array $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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Fri Apr 26 08:20:02 2024 | Cross-referenced by PHPXref |