[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Interactivity API: WP_Interactivity_Dangerous_HTML class.
   4   *
   5   * @package WordPress
   6   * @subpackage Interactivity API
   7   * @since 7.2.0
   8   */
   9  
  10  /**
  11   * Token that marks an HTML string as trusted, for server directive processing
  12   * to render as the content of an element.
  13   *
  14   * Create tokens with {@see wp_interactivity_as_dangerous_html()}, which
  15   * documents the risks of marking HTML as trusted.
  16   *
  17   * The HTML is kept in a private property, so it never reaches JSON: a token
  18   * encodes as the marker `{"wpServerHtml":true}`, which tells the client to
  19   * keep the content the element already has. The marker holds no HTML. A token
  20   * restored by unserialization is inert: it holds no HTML, so it never renders,
  21   * and it encodes as the marker too.
  22   *
  23   * Both JSON encoding paths of `wp_json_encode()` print the marker: `json_encode()`
  24   * uses {@see WP_Interactivity_Dangerous_HTML::jsonSerialize()}, and the fallback
  25   * for data that is not valid UTF-8 rebuilds the object by iterating it with
  26   * {@see WP_Interactivity_Dangerous_HTML::getIterator()}.
  27   *
  28   * @since 7.2.0
  29   *
  30   * @access private
  31   */
  32  final class WP_Interactivity_Dangerous_HTML implements JsonSerializable, IteratorAggregate {
  33      /**
  34       * The trusted HTML. It is `null` for a token restored by unserialization,
  35       * which never renders.
  36       *
  37       * @since 7.2.0
  38       * @var string|null
  39       */
  40      private $html = null;
  41  
  42      /**
  43       * Constructor.
  44       *
  45       * @since 7.2.0
  46       *
  47       * @param string $html The HTML to mark as trusted. It is not sanitized.
  48       */
  49  	public function __construct( string $html ) {
  50          $this->html = $html;
  51      }
  52  
  53      /**
  54       * Gets the trusted HTML of a value.
  55       *
  56       * @since 7.2.0
  57       *
  58       * @param mixed $value Any value.
  59       * @return string|null The HTML of the token if the value is a token whose constructor
  60       *                     ran, or `null` for any other value.
  61       */
  62  	public static function get_html( $value ): ?string {
  63          return $value instanceof self ? $value->html : null;
  64      }
  65  
  66      /**
  67       * Makes a token restored by unserialization inert.
  68       *
  69       * Clears the HTML, so the token never renders, and reports the unserialization
  70       * instead of throwing, so a page that cached a token keeps working.
  71       *
  72       * @since 7.2.0
  73       */
  74  	public function __wakeup(): void {
  75          $this->html = null;
  76  
  77          _doing_it_wrong(
  78              __METHOD__,
  79              __( 'A token that marks HTML as trusted should not be unserialized. The unserialized token holds no HTML and does not render.' ),
  80              '7.2.0'
  81          );
  82      }
  83  
  84      /**
  85       * Gets the value that JSON encoding prints in place of the token.
  86       *
  87       * It is the same for every token and holds none of its HTML.
  88       *
  89       * @since 7.2.0
  90       *
  91       * @return array<string, bool> The marker: a single `wpServerHtml` entry set to `true`,
  92       *                             which `json_encode()` prints as `{"wpServerHtml":true}`.
  93       */
  94  	public function jsonSerialize(): array {
  95          return array( 'wpServerHtml' => true );
  96      }
  97  
  98      /**
  99       * Gets the iterator that `foreach` and the fallback of `wp_json_encode()` read.
 100       *
 101       * It yields the same single entry as {@see WP_Interactivity_Dangerous_HTML::jsonSerialize()}
 102       * and none of the token's HTML.
 103       *
 104       * @since 7.2.0
 105       *
 106       * @return Traversable<string, bool> An iterator yielding `wpServerHtml` => `true`, once.
 107       */
 108  	public function getIterator(): Traversable {
 109          return new ArrayIterator( $this->jsonSerialize() );
 110      }
 111  }