[ 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       * @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       *
 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 string[]
 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 string[]      $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  }


Generated : Tue Dec 24 08:20:01 2024 Cross-referenced by PHPXref