[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/ -> class-wp-block-type.php (source)

   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  }


Generated : Fri Nov 20 08:20:01 2026 Cross-referenced by PHPXref