[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Interactivity API: WP_Interactivity_API_Directives_Processor class.
   4   *
   5   * @package WordPress
   6   * @subpackage Interactivity API
   7   * @since 6.5.0
   8   */
   9  
  10  /**
  11   * Class used to iterate over the tags of an HTML string and help process the
  12   * directive attributes.
  13   *
  14   * @since 6.5.0
  15   *
  16   * @access private
  17   */
  18  final class WP_Interactivity_API_Directives_Processor extends WP_HTML_Tag_Processor {
  19      /**
  20       * List of tags whose closer tag is not visited by the WP_HTML_Tag_Processor.
  21       *
  22       * @since 6.5.0
  23       * @var string[]
  24       */
  25      const TAGS_THAT_DONT_VISIT_CLOSER_TAG = array(
  26          'SCRIPT',
  27          'IFRAME',
  28          'NOEMBED',
  29          'NOFRAMES',
  30          'STYLE',
  31          'TEXTAREA',
  32          'TITLE',
  33          'XMP',
  34      );
  35  
  36      /**
  37       * Returns the content between two balanced template tags.
  38       *
  39       * It positions the cursor in the closer tag of the balanced template tag,
  40       * if it exists.
  41       *
  42       * @since 6.5.0
  43       *
  44       * @access private
  45       *
  46       * @return string|null The content between the current opener template tag and its matching closer tag or null if it
  47       *                     doesn't find the matching closing tag or the current tag is not a template opener tag.
  48       */
  49  	public function get_content_between_balanced_template_tags() {
  50          if ( 'TEMPLATE' !== $this->get_tag() ) {
  51              return null;
  52          }
  53  
  54          $positions = $this->get_after_opener_tag_and_before_closer_tag_positions();
  55          if ( ! $positions ) {
  56              return null;
  57          }
  58          list( $after_opener_tag, $before_closer_tag ) = $positions;
  59  
  60          return substr( $this->html, $after_opener_tag, $before_closer_tag - $after_opener_tag );
  61      }
  62  
  63      /**
  64       * Sets the content between two balanced tags.
  65       *
  66       * @since 6.5.0
  67       *
  68       * @access private
  69       *
  70       * @param string $new_content The string to replace the content between the matching tags.
  71       * @return bool Whether the content was successfully replaced.
  72       */
  73  	public function set_content_between_balanced_tags( string $new_content ): bool {
  74          $positions = $this->get_after_opener_tag_and_before_closer_tag_positions( true );
  75          if ( ! $positions ) {
  76              return false;
  77          }
  78          list( $after_opener_tag, $before_closer_tag ) = $positions;
  79  
  80          $this->lexical_updates[] = new WP_HTML_Text_Replacement(
  81              $after_opener_tag,
  82              $before_closer_tag - $after_opener_tag,
  83              esc_html( $new_content )
  84          );
  85  
  86          return true;
  87      }
  88  
  89      /**
  90       * Moves to the matching closer tag of the current opener tag and replaces
  91       * the content between them.
  92       *
  93       * The matching closer tag is found as in
  94       * {@see WP_Interactivity_API_Directives_Processor::next_balanced_tag_closer_tag()}.
  95       * The new content is written as given. Unlike
  96       * {@see WP_Interactivity_API_Directives_Processor::set_content_between_balanced_tags()},
  97       * it neither applies the pending updates nor seeks back to the opener tag,
  98       * so it can be called any number of times on the same processor.
  99       *
 100       * @since 7.2.0
 101       *
 102       * @access private
 103       *
 104       * @param string $new_content The markup to replace the content between the matching tags with.
 105       * @return bool Whether the matching closer tag was found. When it is not found, the cursor is at the end
 106       *              of the HTML and nothing is replaced.
 107       */
 108  	public function skip_to_balanced_tag_closer( string $new_content ): bool {
 109          $bookmarks = $this->get_balanced_tag_bookmarks();
 110          if ( ! $bookmarks ) {
 111              return false;
 112          }
 113          list( $opener_tag, $closer_tag ) = $bookmarks;
 114  
 115          $after_opener_tag  = $this->bookmarks[ $opener_tag ]->start + $this->bookmarks[ $opener_tag ]->length;
 116          $before_closer_tag = $this->bookmarks[ $closer_tag ]->start;
 117  
 118          $this->release_bookmark( $opener_tag );
 119          $this->release_bookmark( $closer_tag );
 120  
 121          $this->lexical_updates[] = new WP_HTML_Text_Replacement(
 122              $after_opener_tag,
 123              $before_closer_tag - $after_opener_tag,
 124              $new_content
 125          );
 126  
 127          return true;
 128      }
 129  
 130      /**
 131       * Appends content after the closing tag of a template tag.
 132       *
 133       * It positions the cursor in the closer tag of the balanced template tag,
 134       * if it exists.
 135       *
 136       * @since 6.5.0
 137       *
 138       * @access private
 139       *
 140       * @param string $new_content The string to append after the closing template tag.
 141       * @return bool Whether the content was successfully appended.
 142       */
 143  	public function append_content_after_template_tag_closer( string $new_content ): bool {
 144          if ( empty( $new_content ) || 'TEMPLATE' !== $this->get_tag() || ! $this->is_tag_closer() ) {
 145              return false;
 146          }
 147  
 148          // Flushes any changes.
 149          $this->get_updated_html();
 150  
 151          $bookmark = 'append_content_after_template_tag_closer';
 152          $this->set_bookmark( $bookmark );
 153          $after_closing_tag = $this->bookmarks[ $bookmark ]->start + $this->bookmarks[ $bookmark ]->length;
 154          $this->release_bookmark( $bookmark );
 155  
 156          // Appends the new content.
 157          $this->lexical_updates[] = new WP_HTML_Text_Replacement( $after_closing_tag, 0, $new_content );
 158  
 159          return true;
 160      }
 161  
 162      /**
 163       * Gets the positions right after the opener tag and right before the closer
 164       * tag in a balanced tag.
 165       *
 166       * By default, it positions the cursor in the closer tag of the balanced tag.
 167       * If $rewind is true, it seeks back to the opener tag.
 168       *
 169       * @since 6.5.0
 170       *
 171       * @access private
 172       *
 173       * @param bool $rewind Optional. Whether to seek back to the opener tag after finding the positions. Defaults to false.
 174       * @return array|null Start and end byte position, or null when no balanced tag bookmarks.
 175       */
 176      private function get_after_opener_tag_and_before_closer_tag_positions( bool $rewind = false ) {
 177          // Flushes any changes.
 178          $this->get_updated_html();
 179  
 180          $bookmarks = $this->get_balanced_tag_bookmarks();
 181          if ( ! $bookmarks ) {
 182              return null;
 183          }
 184          list( $opener_tag, $closer_tag ) = $bookmarks;
 185  
 186          $after_opener_tag  = $this->bookmarks[ $opener_tag ]->start + $this->bookmarks[ $opener_tag ]->length;
 187          $before_closer_tag = $this->bookmarks[ $closer_tag ]->start;
 188  
 189          if ( $rewind ) {
 190              $this->seek( $opener_tag );
 191          }
 192  
 193          $this->release_bookmark( $opener_tag );
 194          $this->release_bookmark( $closer_tag );
 195  
 196          return array( $after_opener_tag, $before_closer_tag );
 197      }
 198  
 199      /**
 200       * Returns a pair of bookmarks for the current opener tag and the matching
 201       * closer tag.
 202       *
 203       * It positions the cursor in the closer tag of the balanced tag, if it
 204       * exists.
 205       *
 206       * @since 6.5.0
 207       *
 208       * @return array|null A pair of bookmarks, or null if there's no matching closing tag.
 209       */
 210  	private function get_balanced_tag_bookmarks() {
 211          static $i   = 0;
 212          $opener_tag = 'opener_tag_of_balanced_tag_' . ++$i;
 213  
 214          $this->set_bookmark( $opener_tag );
 215          if ( ! $this->next_balanced_tag_closer_tag() ) {
 216              $this->release_bookmark( $opener_tag );
 217              return null;
 218          }
 219  
 220          $closer_tag = 'closer_tag_of_balanced_tag_' . ++$i;
 221          $this->set_bookmark( $closer_tag );
 222  
 223          return array( $opener_tag, $closer_tag );
 224      }
 225  
 226      /**
 227       * Skips processing the content between tags.
 228       *
 229       * It positions the cursor in the closer tag of the foreign element, if it
 230       * exists.
 231       *
 232       * This function is intended to skip processing SVG and MathML inner content
 233       * instead of bailing out the whole processing.
 234       *
 235       * @since 6.5.0
 236       *
 237       * @access private
 238       *
 239       * @return bool Whether the foreign content was successfully skipped.
 240       */
 241  	public function skip_to_tag_closer(): bool {
 242          $depth    = 1;
 243          $tag_name = $this->get_tag();
 244  
 245          while ( $depth > 0 && $this->next_tag( array( 'tag_closers' => 'visit' ) ) ) {
 246              if ( ! $this->is_tag_closer() && $this->get_attribute_names_with_prefix( 'data-wp-' ) ) {
 247                  /* translators: 1: SVG or MATH HTML tag. */
 248                  $message = sprintf( __( 'Interactivity directives were detected inside an incompatible %1$s tag. These directives will be ignored in the server side render.' ), $tag_name );
 249                  _doing_it_wrong( __METHOD__, $message, '6.6.0' );
 250              }
 251              if ( $this->get_tag() === $tag_name ) {
 252                  if ( $this->has_self_closing_flag() ) {
 253                      continue;
 254                  }
 255                  $depth += $this->is_tag_closer() ? -1 : 1;
 256              }
 257          }
 258  
 259          return 0 === $depth;
 260      }
 261  
 262      /**
 263       * Finds the matching closing tag for an opening tag.
 264       *
 265       * When called while the processor is on an open tag, it traverses the HTML
 266       * until it finds the matching closer tag, respecting any in-between content,
 267       * including nested tags of the same name. Returns false when called on a
 268       * closer tag, a tag that doesn't have a closer tag (void), a tag that
 269       * doesn't visit the closer tag, or if no matching closing tag was found.
 270       *
 271       * @since 6.5.0
 272       *
 273       * @access private
 274       *
 275       * @return bool Whether a matching closing tag was found.
 276       */
 277  	public function next_balanced_tag_closer_tag(): bool {
 278          $depth    = 0;
 279          $tag_name = $this->get_tag();
 280  
 281          if ( ! $this->has_and_visits_its_closer_tag() ) {
 282              return false;
 283          }
 284  
 285          while ( $this->next_tag(
 286              array(
 287                  'tag_name'    => $tag_name,
 288                  'tag_closers' => 'visit',
 289              )
 290          ) ) {
 291              if ( ! $this->is_tag_closer() ) {
 292                  ++$depth;
 293                  continue;
 294              }
 295  
 296              if ( 0 === $depth ) {
 297                  return true;
 298              }
 299  
 300              --$depth;
 301          }
 302  
 303          return false;
 304      }
 305  
 306      /**
 307       * Checks whether the current tag has and will visit its matching closer tag.
 308       *
 309       * @since 6.5.0
 310       *
 311       * @access private
 312       *
 313       * @return bool Whether the current tag has a closer tag.
 314       */
 315  	public function has_and_visits_its_closer_tag(): bool {
 316          $tag_name = $this->get_tag();
 317  
 318          return null !== $tag_name && (
 319              ! WP_HTML_Processor::is_void( $tag_name ) &&
 320              ! in_array( $tag_name, self::TAGS_THAT_DONT_VISIT_CLOSER_TAG, true )
 321          );
 322      }
 323  }