[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|null
  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       * @since 6.4.0
  85       * @var callable|null
  86       */
  87      public $on_destroy = null;
  88  
  89      /**
  90       * Constructor - creates a reference to a token in some external HTML string.
  91       *
  92       * @since 6.4.0
  93       *
  94       * @param string|null   $bookmark_name         Name of bookmark corresponding to location in HTML where token is found,
  95       *                                             or `null` for markers and nodes without a bookmark.
  96       * @param string        $node_name             Name of node token represents; if uppercase, an HTML element; if lowercase, a special value like "marker".
  97       * @param bool          $has_self_closing_flag Whether the source token contains the self-closing flag, regardless of whether it's valid.
  98       * @param callable|null $on_destroy            Optional. Function to call when destroying token, useful for releasing the bookmark.
  99       */
 100  	public function __construct( ?string $bookmark_name, string $node_name, bool $has_self_closing_flag, ?callable $on_destroy = null ) {
 101          $this->bookmark_name         = $bookmark_name;
 102          $this->namespace             = 'html';
 103          $this->node_name             = $node_name;
 104          $this->has_self_closing_flag = $has_self_closing_flag;
 105          $this->on_destroy            = $on_destroy;
 106      }
 107  
 108      /**
 109       * Destructor.
 110       *
 111       * @since 6.4.0
 112       */
 113  	public function __destruct() {
 114          if ( is_callable( $this->on_destroy ) ) {
 115              call_user_func( $this->on_destroy, $this->bookmark_name );
 116          }
 117      }
 118  
 119      /**
 120       * Wakeup magic method.
 121       *
 122       * @since 6.4.2
 123       */
 124  	public function __wakeup() {
 125          throw new \LogicException( __CLASS__ . ' should never be unserialized' );
 126      }
 127  }