[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * HTML API: WP_HTML_Token class
   4   *
   5   * @package WordPress
   6   * @subpackage HTML-API
   7   * @since 6.4.0
   8   */
   9  
  10  /**
  11   * Core class used by the HTML processor during HTML parsing
  12   * for referring to tokens in the input HTML string.
  13   *
  14   * This class is designed for internal use by the HTML processor.
  15   *
  16   * @since 6.4.0
  17   *
  18   * @access private
  19   *
  20   * @see WP_HTML_Processor
  21   */
  22  class WP_HTML_Token {
  23      /**
  24       * Name of bookmark corresponding to source of token in input HTML string.
  25       *
  26       * Having a bookmark name does not imply that the token still exists. It
  27       * may be that the source token and underlying bookmark was wiped out by
  28       * some modification to the source HTML.
  29       *
  30       * @since 6.4.0
  31       *
  32       * @var string
  33       */
  34      public $bookmark_name = null;
  35  
  36      /**
  37       * Name of node; lowercase names such as "marker" are not HTML elements.
  38       *
  39       * For HTML elements/tags this value should come from WP_HTML_Processor::get_tag().
  40       *
  41       * @since 6.4.0
  42       *
  43       * @see WP_HTML_Processor::get_tag()
  44       *
  45       * @var string
  46       */
  47      public $node_name = null;
  48  
  49      /**
  50       * Whether node contains the self-closing flag.
  51       *
  52       * A node may have a self-closing flag when it shouldn't. This value
  53       * only reports if the flag is present in the original HTML.
  54       *
  55       * @since 6.4.0
  56       *
  57       * @see https://html.spec.whatwg.org/#self-closing-flag
  58       *
  59       * @var bool
  60       */
  61      public $has_self_closing_flag = false;
  62  
  63      /**
  64       * Indicates if the element is an HTML element or if it's inside foreign content.
  65       *
  66       * @since 6.7.0
  67       *
  68       * @var string 'html', 'svg', or 'math'.
  69       */
  70      public $namespace = 'html';
  71  
  72      /**
  73       * Indicates which kind of integration point the element is, if any.
  74       *
  75       * @since 6.7.0
  76       *
  77       * @var string|null 'math', 'html', or null if not an integration point.
  78       */
  79      public $integration_node_type = null;
  80  
  81      /**
  82       * Called when token is garbage-collected or otherwise destroyed.
  83       *
  84       * @var callable|null
  85       */
  86      public $on_destroy = null;
  87  
  88      /**
  89       * Constructor - creates a reference to a token in some external HTML string.
  90       *
  91       * @since 6.4.0
  92       *
  93       * @param string|null   $bookmark_name         Name of bookmark corresponding to location in HTML where token is found,
  94       *                                             or `null` for markers and nodes without a bookmark.
  95       * @param string        $node_name             Name of node token represents; if uppercase, an HTML element; if lowercase, a special value like "marker".
  96       * @param bool          $has_self_closing_flag Whether the source token contains the self-closing flag, regardless of whether it's valid.
  97       * @param callable|null $on_destroy            Optional. Function to call when destroying token, useful for releasing the bookmark.
  98       */
  99  	public function __construct( ?string $bookmark_name, string $node_name, bool $has_self_closing_flag, ?callable $on_destroy = null ) {
 100          $this->bookmark_name         = $bookmark_name;
 101          $this->namespace             = 'html';
 102          $this->node_name             = $node_name;
 103          $this->has_self_closing_flag = $has_self_closing_flag;
 104          $this->on_destroy            = $on_destroy;
 105      }
 106  
 107      /**
 108       * Destructor.
 109       *
 110       * @since 6.4.0
 111       */
 112  	public function __destruct() {
 113          if ( is_callable( $this->on_destroy ) ) {
 114              call_user_func( $this->on_destroy, $this->bookmark_name );
 115          }
 116      }
 117  
 118      /**
 119       * Wakeup magic method.
 120       *
 121       * @since 6.4.2
 122       */
 123  	public function __wakeup() {
 124          throw new \LogicException( __CLASS__ . ' should never be unserialized' );
 125      }
 126  }