[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

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

   1  <?php
   2  /**
   3   * Blocks API: WP_Block class
   4   *
   5   * @package WordPress
   6   * @since 5.5.0
   7   */
   8  
   9  /**
  10   * Class representing a parsed instance of a block.
  11   *
  12   * @since 5.5.0
  13   * @property array $attributes
  14   */
  15  #[AllowDynamicProperties]
  16  class WP_Block {
  17  
  18      /**
  19       * Original parsed array representation of block.
  20       *
  21       * @since 5.5.0
  22       * @var array
  23       */
  24      public $parsed_block;
  25  
  26      /**
  27       * Name of block.
  28       *
  29       * @example "core/paragraph"
  30       *
  31       * @since 5.5.0
  32       * @var string
  33       */
  34      public $name;
  35  
  36      /**
  37       * Block type associated with the instance.
  38       *
  39       * @since 5.5.0
  40       * @var WP_Block_Type
  41       */
  42      public $block_type;
  43  
  44      /**
  45       * Block context values.
  46       *
  47       * @since 5.5.0
  48       * @var array
  49       */
  50      public $context = array();
  51  
  52      /**
  53       * All available context of the current hierarchy.
  54       *
  55       * @since 5.5.0
  56       * @var array
  57       * @access protected
  58       */
  59      protected $available_context;
  60  
  61      /**
  62       * Block type registry.
  63       *
  64       * @since 5.9.0
  65       * @var WP_Block_Type_Registry
  66       * @access protected
  67       */
  68      protected $registry;
  69  
  70      /**
  71       * List of inner blocks (of this same class)
  72       *
  73       * @since 5.5.0
  74       * @var WP_Block_List
  75       */
  76      public $inner_blocks = array();
  77  
  78      /**
  79       * Resultant HTML from inside block comment delimiters after removing inner
  80       * blocks.
  81       *
  82       * @example "...Just <!-- wp:test /--> testing..." -> "Just testing..."
  83       *
  84       * @since 5.5.0
  85       * @var string
  86       */
  87      public $inner_html = '';
  88  
  89      /**
  90       * List of string fragments and null markers where inner blocks were found
  91       *
  92       * @example array(
  93       *   'inner_html'    => 'BeforeInnerAfter',
  94       *   'inner_blocks'  => array( block, block ),
  95       *   'inner_content' => array( 'Before', null, 'Inner', null, 'After' ),
  96       * )
  97       *
  98       * @since 5.5.0
  99       * @var array
 100       */
 101      public $inner_content = array();
 102  
 103      /**
 104       * Constructor.
 105       *
 106       * Populates object properties from the provided block instance argument.
 107       *
 108       * The given array of context values will not necessarily be available on
 109       * the instance itself, but is treated as the full set of values provided by
 110       * the block's ancestry. This is assigned to the private `available_context`
 111       * property. Only values which are configured to consumed by the block via
 112       * its registered type will be assigned to the block's `context` property.
 113       *
 114       * @since 5.5.0
 115       *
 116       * @param array                  $block             {
 117       *     An associative array of a single parsed block object. See WP_Block_Parser_Block.
 118       *
 119       *     @type string   $blockName    Name of block.
 120       *     @type array    $attrs        Attributes from block comment delimiters.
 121       *     @type array    $innerBlocks  List of inner blocks. An array of arrays that
 122       *                                  have the same structure as this one.
 123       *     @type string   $innerHTML    HTML from inside block comment delimiters.
 124       *     @type array    $innerContent List of string fragments and null markers where inner blocks were found.
 125       * }
 126       * @param array                  $available_context Optional array of ancestry context values.
 127       * @param WP_Block_Type_Registry $registry          Optional block type registry.
 128       */
 129  	public function __construct( $block, $available_context = array(), $registry = null ) {
 130          $this->parsed_block = $block;
 131          $this->name         = $block['blockName'];
 132  
 133          if ( is_null( $registry ) ) {
 134              $registry = WP_Block_Type_Registry::get_instance();
 135          }
 136  
 137          $this->registry = $registry;
 138  
 139          $this->block_type = $registry->get_registered( $this->name );
 140  
 141          $this->available_context = $available_context;
 142  
 143          if ( ! empty( $this->block_type->uses_context ) ) {
 144              foreach ( $this->block_type->uses_context as $context_name ) {
 145                  if ( array_key_exists( $context_name, $this->available_context ) ) {
 146                      $this->context[ $context_name ] = $this->available_context[ $context_name ];
 147                  }
 148              }
 149          }
 150  
 151          if ( ! empty( $block['innerBlocks'] ) ) {
 152              $child_context = $this->available_context;
 153  
 154              if ( ! empty( $this->block_type->provides_context ) ) {
 155                  foreach ( $this->block_type->provides_context as $context_name => $attribute_name ) {
 156                      if ( array_key_exists( $attribute_name, $this->attributes ) ) {
 157                          $child_context[ $context_name ] = $this->attributes[ $attribute_name ];
 158                      }
 159                  }
 160              }
 161  
 162              $this->inner_blocks = new WP_Block_List( $block['innerBlocks'], $child_context, $registry );
 163          }
 164  
 165          if ( ! empty( $block['innerHTML'] ) ) {
 166              $this->inner_html = $block['innerHTML'];
 167          }
 168  
 169          if ( ! empty( $block['innerContent'] ) ) {
 170              $this->inner_content = $block['innerContent'];
 171          }
 172      }
 173  
 174      /**
 175       * Returns a value from an inaccessible property.
 176       *
 177       * This is used to lazily initialize the `attributes` property of a block,
 178       * such that it is only prepared with default attributes at the time that
 179       * the property is accessed. For all other inaccessible properties, a `null`
 180       * value is returned.
 181       *
 182       * @since 5.5.0
 183       *
 184       * @param string $name Property name.
 185       * @return array|null Prepared attributes, or null.
 186       */
 187  	public function __get( $name ) {
 188          if ( 'attributes' === $name ) {
 189              $this->attributes = isset( $this->parsed_block['attrs'] ) ?
 190                  $this->parsed_block['attrs'] :
 191                  array();
 192  
 193              if ( ! is_null( $this->block_type ) ) {
 194                  $this->attributes = $this->block_type->prepare_attributes_for_render( $this->attributes );
 195              }
 196  
 197              return $this->attributes;
 198          }
 199  
 200          return null;
 201      }
 202  
 203      /**
 204       * Processes the block bindings and updates the block attributes with the values from the sources.
 205       *
 206       * A block might contain bindings in its attributes. Bindings are mappings
 207       * between an attribute of the block and a source. A "source" is a function
 208       * registered with `register_block_bindings_source()` that defines how to
 209       * retrieve a value from outside the block, e.g. from post meta.
 210       *
 211       * This function will process those bindings and update the block's attributes
 212       * with the values coming from the bindings.
 213       *
 214       * ### Example
 215       *
 216       * The "bindings" property for an Image block might look like this:
 217       *
 218       * ```json
 219       * {
 220       *   "metadata": {
 221       *     "bindings": {
 222       *       "title": {
 223       *         "source": "core/post-meta",
 224       *         "args": { "key": "text_custom_field" }
 225       *       },
 226       *       "url": {
 227       *         "source": "core/post-meta",
 228       *         "args": { "key": "url_custom_field" }
 229       *       }
 230       *     }
 231       *   }
 232       * }
 233       * ```
 234       *
 235       * The above example will replace the `title` and `url` attributes of the Image
 236       * block with the values of the `text_custom_field` and `url_custom_field` post meta.
 237       *
 238       * @since 6.5.0
 239       * @since 6.6.0 Handle the `__default` attribute for pattern overrides.
 240       *
 241       * @return array The computed block attributes for the provided block bindings.
 242       */
 243  	private function process_block_bindings() {
 244          $parsed_block               = $this->parsed_block;
 245          $computed_attributes        = array();
 246          $supported_block_attributes = array(
 247              'core/paragraph' => array( 'content' ),
 248              'core/heading'   => array( 'content' ),
 249              'core/image'     => array( 'id', 'url', 'title', 'alt' ),
 250              'core/button'    => array( 'url', 'text', 'linkTarget', 'rel' ),
 251          );
 252  
 253          // If the block doesn't have the bindings property, isn't one of the supported
 254          // block types, or the bindings property is not an array, return the block content.
 255          if (
 256              ! isset( $supported_block_attributes[ $this->name ] ) ||
 257              empty( $parsed_block['attrs']['metadata']['bindings'] ) ||
 258              ! is_array( $parsed_block['attrs']['metadata']['bindings'] )
 259          ) {
 260              return $computed_attributes;
 261          }
 262  
 263          $bindings = $parsed_block['attrs']['metadata']['bindings'];
 264  
 265          /*
 266           * If the default binding is set for pattern overrides, replace it
 267           * with a pattern override binding for all supported attributes.
 268           */
 269          if (
 270              isset( $bindings['__default']['source'] ) &&
 271              'core/pattern-overrides' === $bindings['__default']['source']
 272          ) {
 273              $updated_bindings = array();
 274  
 275              /*
 276               * Build a binding array of all supported attributes.
 277               * Note that this also omits the `__default` attribute from the
 278               * resulting array.
 279               */
 280              foreach ( $supported_block_attributes[ $parsed_block['blockName'] ] as $attribute_name ) {
 281                  // Retain any non-pattern override bindings that might be present.
 282                  $updated_bindings[ $attribute_name ] = isset( $bindings[ $attribute_name ] )
 283                      ? $bindings[ $attribute_name ]
 284                      : array( 'source' => 'core/pattern-overrides' );
 285              }
 286              $bindings = $updated_bindings;
 287          }
 288  
 289          foreach ( $bindings as $attribute_name => $block_binding ) {
 290              // If the attribute is not in the supported list, process next attribute.
 291              if ( ! in_array( $attribute_name, $supported_block_attributes[ $this->name ], true ) ) {
 292                  continue;
 293              }
 294              // If no source is provided, or that source is not registered, process next attribute.
 295              if ( ! isset( $block_binding['source'] ) || ! is_string( $block_binding['source'] ) ) {
 296                  continue;
 297              }
 298  
 299              $block_binding_source = get_block_bindings_source( $block_binding['source'] );
 300              if ( null === $block_binding_source ) {
 301                  continue;
 302              }
 303  
 304              $source_args  = ! empty( $block_binding['args'] ) && is_array( $block_binding['args'] ) ? $block_binding['args'] : array();
 305              $source_value = $block_binding_source->get_value( $source_args, $this, $attribute_name );
 306  
 307              // If the value is not null, process the HTML based on the block and the attribute.
 308              if ( ! is_null( $source_value ) ) {
 309                  $computed_attributes[ $attribute_name ] = $source_value;
 310              }
 311          }
 312  
 313          return $computed_attributes;
 314      }
 315  
 316      /**
 317       * Depending on the block attribute name, replace its value in the HTML based on the value provided.
 318       *
 319       * @since 6.5.0
 320       *
 321       * @param string $block_content  Block content.
 322       * @param string $attribute_name The attribute name to replace.
 323       * @param mixed  $source_value   The value used to replace in the HTML.
 324       * @return string The modified block content.
 325       */
 326  	private function replace_html( string $block_content, string $attribute_name, $source_value ) {
 327          $block_type = $this->block_type;
 328          if ( ! isset( $block_type->attributes[ $attribute_name ]['source'] ) ) {
 329              return $block_content;
 330          }
 331  
 332          // Depending on the attribute source, the processing will be different.
 333          switch ( $block_type->attributes[ $attribute_name ]['source'] ) {
 334              case 'html':
 335              case 'rich-text':
 336                  $block_reader = new WP_HTML_Tag_Processor( $block_content );
 337  
 338                  // TODO: Support for CSS selectors whenever they are ready in the HTML API.
 339                  // In the meantime, support comma-separated selectors by exploding them into an array.
 340                  $selectors = explode( ',', $block_type->attributes[ $attribute_name ]['selector'] );
 341                  // Add a bookmark to the first tag to be able to iterate over the selectors.
 342                  $block_reader->next_tag();
 343                  $block_reader->set_bookmark( 'iterate-selectors' );
 344  
 345                  // TODO: This shouldn't be needed when the `set_inner_html` function is ready.
 346                  // Store the parent tag and its attributes to be able to restore them later in the button.
 347                  // The button block has a wrapper while the paragraph and heading blocks don't.
 348                  if ( 'core/button' === $this->name ) {
 349                      $button_wrapper                 = $block_reader->get_tag();
 350                      $button_wrapper_attribute_names = $block_reader->get_attribute_names_with_prefix( '' );
 351                      $button_wrapper_attrs           = array();
 352                      foreach ( $button_wrapper_attribute_names as $name ) {
 353                          $button_wrapper_attrs[ $name ] = $block_reader->get_attribute( $name );
 354                      }
 355                  }
 356  
 357                  foreach ( $selectors as $selector ) {
 358                      // If the parent tag, or any of its children, matches the selector, replace the HTML.
 359                      if ( strcasecmp( $block_reader->get_tag( $selector ), $selector ) === 0 || $block_reader->next_tag(
 360                          array(
 361                              'tag_name' => $selector,
 362                          )
 363                      ) ) {
 364                          $block_reader->release_bookmark( 'iterate-selectors' );
 365  
 366                          // TODO: Use `set_inner_html` method whenever it's ready in the HTML API.
 367                          // Until then, it is hardcoded for the paragraph, heading, and button blocks.
 368                          // Store the tag and its attributes to be able to restore them later.
 369                          $selector_attribute_names = $block_reader->get_attribute_names_with_prefix( '' );
 370                          $selector_attrs           = array();
 371                          foreach ( $selector_attribute_names as $name ) {
 372                              $selector_attrs[ $name ] = $block_reader->get_attribute( $name );
 373                          }
 374                          $selector_markup = "<$selector>" . wp_kses_post( $source_value ) . "</$selector>";
 375                          $amended_content = new WP_HTML_Tag_Processor( $selector_markup );
 376                          $amended_content->next_tag();
 377                          foreach ( $selector_attrs as $attribute_key => $attribute_value ) {
 378                              $amended_content->set_attribute( $attribute_key, $attribute_value );
 379                          }
 380                          if ( 'core/paragraph' === $this->name || 'core/heading' === $this->name ) {
 381                              return $amended_content->get_updated_html();
 382                          }
 383                          if ( 'core/button' === $this->name ) {
 384                              $button_markup  = "<$button_wrapper>{$amended_content->get_updated_html()}</$button_wrapper>";
 385                              $amended_button = new WP_HTML_Tag_Processor( $button_markup );
 386                              $amended_button->next_tag();
 387                              foreach ( $button_wrapper_attrs as $attribute_key => $attribute_value ) {
 388                                  $amended_button->set_attribute( $attribute_key, $attribute_value );
 389                              }
 390                              return $amended_button->get_updated_html();
 391                          }
 392                      } else {
 393                          $block_reader->seek( 'iterate-selectors' );
 394                      }
 395                  }
 396                  $block_reader->release_bookmark( 'iterate-selectors' );
 397                  return $block_content;
 398  
 399              case 'attribute':
 400                  $amended_content = new WP_HTML_Tag_Processor( $block_content );
 401                  if ( ! $amended_content->next_tag(
 402                      array(
 403                          // TODO: build the query from CSS selector.
 404                          'tag_name' => $block_type->attributes[ $attribute_name ]['selector'],
 405                      )
 406                  ) ) {
 407                      return $block_content;
 408                  }
 409                  $amended_content->set_attribute( $block_type->attributes[ $attribute_name ]['attribute'], $source_value );
 410                  return $amended_content->get_updated_html();
 411  
 412              default:
 413                  return $block_content;
 414          }
 415      }
 416  
 417  
 418      /**
 419       * Generates the render output for the block.
 420       *
 421       * @since 5.5.0
 422       * @since 6.5.0 Added block bindings processing.
 423       *
 424       * @global WP_Post $post Global post object.
 425       *
 426       * @param array $options {
 427       *     Optional options object.
 428       *
 429       *     @type bool $dynamic Defaults to 'true'. Optionally set to false to avoid using the block's render_callback.
 430       * }
 431       * @return string Rendered block output.
 432       */
 433  	public function render( $options = array() ) {
 434          global $post;
 435  
 436          /*
 437           * There can be only one root interactive block at a time because the rendered HTML of that block contains
 438           * the rendered HTML of all its inner blocks, including any interactive block.
 439           */
 440          static $root_interactive_block = null;
 441          /**
 442           * Filters whether Interactivity API should process directives.
 443           *
 444           * @since 6.6.0
 445           *
 446           * @param bool $enabled Whether the directives processing is enabled.
 447           */
 448          $interactivity_process_directives_enabled = apply_filters( 'interactivity_process_directives', true );
 449          if (
 450              $interactivity_process_directives_enabled && null === $root_interactive_block && (
 451                  ( isset( $this->block_type->supports['interactivity'] ) && true === $this->block_type->supports['interactivity'] ) ||
 452                  ! empty( $this->block_type->supports['interactivity']['interactive'] )
 453              )
 454          ) {
 455              $root_interactive_block = $this;
 456          }
 457  
 458          $options = wp_parse_args(
 459              $options,
 460              array(
 461                  'dynamic' => true,
 462              )
 463          );
 464  
 465          // Process the block bindings and get attributes updated with the values from the sources.
 466          $computed_attributes = $this->process_block_bindings();
 467          if ( ! empty( $computed_attributes ) ) {
 468              // Merge the computed attributes with the original attributes.
 469              $this->attributes = array_merge( $this->attributes, $computed_attributes );
 470          }
 471  
 472          $is_dynamic    = $options['dynamic'] && $this->name && null !== $this->block_type && $this->block_type->is_dynamic();
 473          $block_content = '';
 474  
 475          if ( ! $options['dynamic'] || empty( $this->block_type->skip_inner_blocks ) ) {
 476              $index = 0;
 477  
 478              foreach ( $this->inner_content as $chunk ) {
 479                  if ( is_string( $chunk ) ) {
 480                      $block_content .= $chunk;
 481                  } else {
 482                      $inner_block  = $this->inner_blocks[ $index ];
 483                      $parent_block = $this;
 484  
 485                      /** This filter is documented in wp-includes/blocks.php */
 486                      $pre_render = apply_filters( 'pre_render_block', null, $inner_block->parsed_block, $parent_block );
 487  
 488                      if ( ! is_null( $pre_render ) ) {
 489                          $block_content .= $pre_render;
 490                      } else {
 491                          $source_block = $inner_block->parsed_block;
 492  
 493                          /** This filter is documented in wp-includes/blocks.php */
 494                          $inner_block->parsed_block = apply_filters( 'render_block_data', $inner_block->parsed_block, $source_block, $parent_block );
 495  
 496                          /** This filter is documented in wp-includes/blocks.php */
 497                          $inner_block->context = apply_filters( 'render_block_context', $inner_block->context, $inner_block->parsed_block, $parent_block );
 498  
 499                          $block_content .= $inner_block->render();
 500                      }
 501  
 502                      ++$index;
 503                  }
 504              }
 505          }
 506  
 507          if ( ! empty( $computed_attributes ) && ! empty( $block_content ) ) {
 508              foreach ( $computed_attributes as $attribute_name => $source_value ) {
 509                  $block_content = $this->replace_html( $block_content, $attribute_name, $source_value );
 510              }
 511          }
 512  
 513          if ( $is_dynamic ) {
 514              $global_post = $post;
 515              $parent      = WP_Block_Supports::$block_to_render;
 516  
 517              WP_Block_Supports::$block_to_render = $this->parsed_block;
 518  
 519              $block_content = (string) call_user_func( $this->block_type->render_callback, $this->attributes, $block_content, $this );
 520  
 521              WP_Block_Supports::$block_to_render = $parent;
 522  
 523              $post = $global_post;
 524          }
 525  
 526          if ( ( ! empty( $this->block_type->script_handles ) ) ) {
 527              foreach ( $this->block_type->script_handles as $script_handle ) {
 528                  wp_enqueue_script( $script_handle );
 529              }
 530          }
 531  
 532          if ( ! empty( $this->block_type->view_script_handles ) ) {
 533              foreach ( $this->block_type->view_script_handles as $view_script_handle ) {
 534                  wp_enqueue_script( $view_script_handle );
 535              }
 536          }
 537  
 538          if ( ! empty( $this->block_type->view_script_module_ids ) ) {
 539              foreach ( $this->block_type->view_script_module_ids as $view_script_module_id ) {
 540                  wp_enqueue_script_module( $view_script_module_id );
 541              }
 542          }
 543  
 544          if ( ( ! empty( $this->block_type->style_handles ) ) ) {
 545              foreach ( $this->block_type->style_handles as $style_handle ) {
 546                  wp_enqueue_style( $style_handle );
 547              }
 548          }
 549  
 550          if ( ( ! empty( $this->block_type->view_style_handles ) ) ) {
 551              foreach ( $this->block_type->view_style_handles as $view_style_handle ) {
 552                  wp_enqueue_style( $view_style_handle );
 553              }
 554          }
 555  
 556          /**
 557           * Filters the content of a single block.
 558           *
 559           * @since 5.0.0
 560           * @since 5.9.0 The `$instance` parameter was added.
 561           *
 562           * @param string   $block_content The block content.
 563           * @param array    $block         The full block, including name and attributes.
 564           * @param WP_Block $instance      The block instance.
 565           */
 566          $block_content = apply_filters( 'render_block', $block_content, $this->parsed_block, $this );
 567  
 568          /**
 569           * Filters the content of a single block.
 570           *
 571           * The dynamic portion of the hook name, `$name`, refers to
 572           * the block name, e.g. "core/paragraph".
 573           *
 574           * @since 5.7.0
 575           * @since 5.9.0 The `$instance` parameter was added.
 576           *
 577           * @param string   $block_content The block content.
 578           * @param array    $block         The full block, including name and attributes.
 579           * @param WP_Block $instance      The block instance.
 580           */
 581          $block_content = apply_filters( "render_block_{$this->name}", $block_content, $this->parsed_block, $this );
 582  
 583          if ( $root_interactive_block === $this ) {
 584              // The root interactive block has finished rendering. Time to process directives.
 585              $block_content          = wp_interactivity_process_directives( $block_content );
 586              $root_interactive_block = null;
 587          }
 588  
 589          return $block_content;
 590      }
 591  }


Generated : Sat Sep 14 08:20:02 2024 Cross-referenced by PHPXref