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 */
 22class 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}
127