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