- md5
- c2c01936f395a5bbd897bddcff4be751
- sha1
- 1e9c1fa116b0f2ca3ba03d7c9ea7131425ba65f9
- sha256
- 70774679019c486fab4deb2170010080ff4016836d79b4817ebe65ca5767c1d2
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111
<?php
/**
* Interactivity API: WP_Interactivity_Dangerous_HTML class.
*
* @package WordPress
* @subpackage Interactivity API
* @since 7.2.0
*/
/**
* Token that marks an HTML string as trusted, for server directive processing
* to render as the content of an element.
*
* Create tokens with {@see wp_interactivity_as_dangerous_html()}, which
* documents the risks of marking HTML as trusted.
*
* The HTML is kept in a private property, so it never reaches JSON: a token
* encodes as the marker `{"wpServerHtml":true}`, which tells the client to
* keep the content the element already has. The marker holds no HTML. A token
* restored by unserialization is inert: it holds no HTML, so it never renders,
* and it encodes as the marker too.
*
* Both JSON encoding paths of `wp_json_encode()` print the marker: `json_encode()`
* uses {@see WP_Interactivity_Dangerous_HTML::jsonSerialize()}, and the fallback
* for data that is not valid UTF-8 rebuilds the object by iterating it with
* {@see WP_Interactivity_Dangerous_HTML::getIterator()}.
*
* @since 7.2.0
*
* @access private
*/
final class WP_Interactivity_Dangerous_HTML implements JsonSerializable, IteratorAggregate {
/**
* The trusted HTML. It is `null` for a token restored by unserialization,
* which never renders.
*
* @since 7.2.0
* @var string|null
*/
private $html = null;
/**
* Constructor.
*
* @since 7.2.0
*
* @param string $html The HTML to mark as trusted. It is not sanitized.
*/
public function __construct( string $html ) {
$this->html = $html;
}
/**
* Gets the trusted HTML of a value.
*
* @since 7.2.0
*
* @param mixed $value Any value.
* @return string|null The HTML of the token if the value is a token whose constructor
* ran, or `null` for any other value.
*/
public static function get_html( $value ): ?string {
return $value instanceof self ? $value->html : null;
}
/**
* Makes a token restored by unserialization inert.
*
* Clears the HTML, so the token never renders, and reports the unserialization
* instead of throwing, so a page that cached a token keeps working.
*
* @since 7.2.0
*/
public function __wakeup(): void {
$this->html = null;
_doing_it_wrong(
__METHOD__,
__( 'A token that marks HTML as trusted should not be unserialized. The unserialized token holds no HTML and does not render.' ),
'7.2.0'
);
}
/**
* Gets the value that JSON encoding prints in place of the token.
*
* It is the same for every token and holds none of its HTML.
*
* @since 7.2.0
*
* @return array<string, bool> The marker: a single `wpServerHtml` entry set to `true`,
* which `json_encode()` prints as `{"wpServerHtml":true}`.
*/
public function jsonSerialize(): array {
return array( 'wpServerHtml' => true );
}
/**
* Gets the iterator that `foreach` and the fallback of `wp_json_encode()` read.
*
* It yields the same single entry as {@see WP_Interactivity_Dangerous_HTML::jsonSerialize()}
* and none of the token's HTML.
*
* @since 7.2.0
*
* @return Traversable<string, bool> An iterator yielding `wpServerHtml` => `true`, once.
*/
public function getIterator(): Traversable {
return new ArrayIterator( $this->jsonSerialize() );
}
}
The same content is in 5 releases, WordPress 7.2-beta1 to 7.2-beta5. See them all, or every version of this file.