[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 encoding a token as JSON never
  18   * includes it. A token restored by unserialization is inert: it holds no HTML,
  19   * so it never renders.
  20   *
  21   * @since 7.2.0
  22   *
  23   * @access private
  24   */
  25  final class WP_Interactivity_Dangerous_HTML {
  26      /**
  27       * The trusted HTML. It is `null` for a token restored by unserialization,
  28       * which never renders.
  29       *
  30       * @since 7.2.0
  31       * @var string|null
  32       */
  33      private $html = null;
  34  
  35      /**
  36       * Constructor.
  37       *
  38       * @since 7.2.0
  39       *
  40       * @param string $html The HTML to mark as trusted. It is not sanitized.
  41       */
  42  	public function __construct( string $html ) {
  43          $this->html = $html;
  44      }
  45  
  46      /**
  47       * Gets the trusted HTML of a value.
  48       *
  49       * @since 7.2.0
  50       *
  51       * @param mixed $value Any value.
  52       * @return string|null The HTML of the token if the value is a token whose constructor
  53       *                     ran, or `null` for any other value.
  54       */
  55  	public static function get_html( $value ): ?string {
  56          return $value instanceof self ? $value->html : null;
  57      }
  58  
  59      /**
  60       * Makes a token restored by unserialization inert.
  61       *
  62       * Clears the HTML, so the token never renders, and reports the unserialization
  63       * instead of throwing, so a page that cached a token keeps working.
  64       *
  65       * @since 7.2.0
  66       */
  67  	public function __wakeup(): void {
  68          $this->html = null;
  69  
  70          _doing_it_wrong(
  71              __METHOD__,
  72              __( 'A token that marks HTML as trusted should not be unserialized. The unserialized token holds no HTML and does not render.' ),
  73              '7.2.0'
  74          );
  75      }
  76  }