[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       * Called when token is garbage-collected or otherwise destroyed.
  65       *
  66       * @var callable|null
  67       */
  68      public $on_destroy = null;
  69  
  70      /**
  71       * Constructor - creates a reference to a token in some external HTML string.
  72       *
  73       * @since 6.4.0
  74       *
  75       * @param string   $bookmark_name         Name of bookmark corresponding to location in HTML where token is found.
  76       * @param string   $node_name             Name of node token represents; if uppercase, an HTML element; if lowercase, a special value like "marker".
  77       * @param bool     $has_self_closing_flag Whether the source token contains the self-closing flag, regardless of whether it's valid.
  78       * @param callable $on_destroy            Function to call when destroying token, useful for releasing the bookmark.
  79       */
  80  	public function __construct( $bookmark_name, $node_name, $has_self_closing_flag, $on_destroy = null ) {
  81          $this->bookmark_name         = $bookmark_name;
  82          $this->node_name             = $node_name;
  83          $this->has_self_closing_flag = $has_self_closing_flag;
  84          $this->on_destroy            = $on_destroy;
  85      }
  86  
  87      /**
  88       * Destructor.
  89       *
  90       * @since 6.4.0
  91       */
  92  	public function __destruct() {
  93          if ( is_callable( $this->on_destroy ) ) {
  94              call_user_func( $this->on_destroy, $this->bookmark_name );
  95          }
  96      }
  97  
  98      /**
  99       * Wakeup magic method.
 100       *
 101       * @since 6.4.2
 102       */
 103  	public function __wakeup() {
 104          throw new \LogicException( __CLASS__ . ' should never be unserialized' );
 105      }
 106  }