From 0b179899a84f6b78e49ee7d2a92a78cb1f4f1651 Mon Sep 17 00:00:00 2001
From: Dennis Snell <dmsnell@git.wordpress.org>
Date: Fri, 19 Jul 2024 23:42:14 +0000
Subject: [PATCH] HTML API: Add PHP type annotations.

This patch adds type annotations to internal and private methods of the HTML
API and the supporting WP_Token_Map. Annotations have not been added to the
public interfaces where it would likely crash a site if called wrong.

These annotations should help avoid unnecessary type-related bugs (as have
been uncovered in earlier work adding such annotations) and provide additional
guidance to developers when interacting with these classes in an IDE.

Developed in https://github.com/WordPress/wordpress-develop/pull/6753
Discussed in https://core.trac.wordpress.org/ticket/61399

Props dmsnell, jonsurrell.
See #61399.


git-svn-id: https://develop.svn.wordpress.org/trunk@58769 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/class-wp-token-map.php        |  29 ++--
 ...ass-wp-html-active-formatting-elements.php |   6 +-
 .../html-api/class-wp-html-decoder.php        |  10 +-
 .../html-api/class-wp-html-open-elements.php  |  42 +++---
 .../class-wp-html-processor-state.php         |   4 +-
 .../html-api/class-wp-html-processor.php      | 127 +++++++++---------
 .../html-api/class-wp-html-span.php           |   2 +-
 .../html-api/class-wp-html-stack-event.php    |   2 +-
 .../html-api/class-wp-html-tag-processor.php  |  70 +++++-----
 .../class-wp-html-text-replacement.php        |   2 +-
 .../html-api/class-wp-html-token.php          |  10 +-
 11 files changed, 151 insertions(+), 153 deletions(-)

diff --git a/src/wp-includes/class-wp-token-map.php b/src/wp-includes/class-wp-token-map.php
index 524ab57fd4587..09a0b9303b452 100644
--- a/src/wp-includes/class-wp-token-map.php
+++ b/src/wp-includes/class-wp-token-map.php
@@ -280,7 +280,7 @@ class WP_Token_Map {
 	 *
 	 * @return WP_Token_Map|null Token map, unless unable to create it.
 	 */
-	public static function from_array( $mappings, $key_length = 2 ) {
+	public static function from_array( array $mappings, int $key_length = 2 ): ?WP_Token_Map {
 		$map             = new WP_Token_Map();
 		$map->key_length = $key_length;
 
@@ -328,7 +328,7 @@ public static function from_array( $mappings, $key_length = 2 ) {
 		foreach ( $groups as $group_key => $group ) {
 			usort(
 				$groups[ $group_key ],
-				static function ( $a, $b ) {
+				static function ( array $a, array $b ): int {
 					return self::longest_first_then_alphabetical( $a[0], $b[0] );
 				}
 			);
@@ -385,7 +385,7 @@ static function ( $a, $b ) {
 	 *
 	 * @return WP_Token_Map Map with precomputed data loaded.
 	 */
-	public static function from_precomputed_table( $state ) {
+	public static function from_precomputed_table( $state ): ?WP_Token_Map {
 		$has_necessary_state = isset(
 			$state['storage_version'],
 			$state['key_length'],
@@ -439,7 +439,7 @@ public static function from_precomputed_table( $state ) {
 	 * @param string $case_sensitivity Optional. Pass 'ascii-case-insensitive' to ignore ASCII case when matching. Default 'case-sensitive'.
 	 * @return bool Whether there's an entry for the given word in the map.
 	 */
-	public function contains( $word, $case_sensitivity = 'case-sensitive' ) {
+	public function contains( string $word, string $case_sensitivity = 'case-sensitive' ): bool {
 		$ignore_case = 'ascii-case-insensitive' === $case_sensitivity;
 
 		if ( $this->key_length >= strlen( $word ) ) {
@@ -527,7 +527,7 @@ public function contains( $word, $case_sensitivity = 'case-sensitive' ) {
 	 *
 	 * @return string|null Mapped value of lookup key if found, otherwise `null`.
 	 */
-	public function read_token( $text, $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ) {
+	public function read_token( string $text, int $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ): ?string {
 		$ignore_case = 'ascii-case-insensitive' === $case_sensitivity;
 		$text_length = strlen( $text );
 
@@ -571,15 +571,16 @@ public function read_token( $text, $offset = 0, &$matched_token_byte_length = nu
 	/**
 	 * Finds a match for a short word at the index.
 	 *
-	 * @since 6.6.0.
+	 * @since 6.6.0
+	 *
+	 * @param string   $text                       String in which to search for a lookup key.
+	 * @param int      $offset                     Optional. How many bytes into the string where the lookup key ought to start. Default 0.
+	 * @param int|null &$matched_token_byte_length Optional. Holds byte-length of found lookup key if matched, otherwise not set. Default null.
+	 * @param string   $case_sensitivity           Optional. Pass 'ascii-case-insensitive' to ignore ASCII case when matching. Default 'case-sensitive'.
 	 *
-	 * @param string $text                       String in which to search for a lookup key.
-	 * @param int    $offset                     Optional. How many bytes into the string where the lookup key ought to start. Default 0.
-	 * @param ?int   &$matched_token_byte_length Optional. Holds byte-length of found lookup key if matched, otherwise not set. Default null.
-	 * @param string $case_sensitivity           Optional. Pass 'ascii-case-insensitive' to ignore ASCII case when matching. Default 'case-sensitive'.
 	 * @return string|null Mapped value of lookup key if found, otherwise `null`.
 	 */
-	private function read_small_token( $text, $offset, &$matched_token_byte_length, $case_sensitivity = 'case-sensitive' ) {
+	private function read_small_token( string $text, int $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ): ?string {
 		$ignore_case  = 'ascii-case-insensitive' === $case_sensitivity;
 		$small_length = strlen( $this->small_words );
 		$search_text  = substr( $text, $offset, $this->key_length );
@@ -634,7 +635,7 @@ private function read_small_token( $text, $offset, &$matched_token_byte_length,
 	 *
 	 * @return array The lookup key/substitution values as an associate array.
 	 */
-	public function to_array() {
+	public function to_array(): array {
 		$tokens = array();
 
 		$at            = 0;
@@ -696,7 +697,7 @@ public function to_array() {
 	 * @param string $indent Optional. Use this string for indentation, or rely on the default horizontal tab character. Default "\t".
 	 * @return string Value which can be pasted into a PHP source file for quick loading of table.
 	 */
-	public function precomputed_php_source_table( $indent = "\t" ) {
+	public function precomputed_php_source_table( string $indent = "\t" ): string {
 		$i1 = $indent;
 		$i2 = $i1 . $indent;
 		$i3 = $i2 . $indent;
@@ -801,7 +802,7 @@ static function ( $match_result ) {
 	 * @param string $b Second string to compare.
 	 * @return int -1 or lower if `$a` is less than `$b`; 1 or greater if `$a` is greater than `$b`, and 0 if they are equal.
 	 */
-	private static function longest_first_then_alphabetical( $a, $b ) {
+	private static function longest_first_then_alphabetical( string $a, string $b ): int {
 		if ( $a === $b ) {
 			return 0;
 		}
diff --git a/src/wp-includes/html-api/class-wp-html-active-formatting-elements.php b/src/wp-includes/html-api/class-wp-html-active-formatting-elements.php
index 9f7fee9076243..69e34dca498c1 100644
--- a/src/wp-includes/html-api/class-wp-html-active-formatting-elements.php
+++ b/src/wp-includes/html-api/class-wp-html-active-formatting-elements.php
@@ -51,7 +51,7 @@ class WP_HTML_Active_Formatting_Elements {
 	 * @param WP_HTML_Token $token Look for this node in the stack.
 	 * @return bool Whether the referenced node is in the stack of active formatting elements.
 	 */
-	public function contains_node( $token ) {
+	public function contains_node( WP_HTML_Token $token ) {
 		foreach ( $this->walk_up() as $item ) {
 			if ( $token->bookmark_name === $item->bookmark_name ) {
 				return true;
@@ -95,7 +95,7 @@ public function current_node() {
 	 *
 	 * @param WP_HTML_Token $token Push this node onto the stack.
 	 */
-	public function push( $token ) {
+	public function push( WP_HTML_Token $token ) {
 		/*
 		 * > If there are already three elements in the list of active formatting elements after the last marker,
 		 * > if any, or anywhere in the list if there are no markers, that have the same tag name, namespace, and
@@ -119,7 +119,7 @@ public function push( $token ) {
 	 * @param WP_HTML_Token $token Remove this node from the stack, if it's there already.
 	 * @return bool Whether the node was found and removed from the stack of active formatting elements.
 	 */
-	public function remove_node( $token ) {
+	public function remove_node( WP_HTML_Token $token ) {
 		foreach ( $this->walk_up() as $position_from_end => $item ) {
 			if ( $token->bookmark_name !== $item->bookmark_name ) {
 				continue;
diff --git a/src/wp-includes/html-api/class-wp-html-decoder.php b/src/wp-includes/html-api/class-wp-html-decoder.php
index 42c6424423711..793c7cb2a0137 100644
--- a/src/wp-includes/html-api/class-wp-html-decoder.php
+++ b/src/wp-includes/html-api/class-wp-html-decoder.php
@@ -31,7 +31,7 @@ class WP_HTML_Decoder {
 	 *                                 Default 'case-sensitive'.
 	 * @return bool Whether the attribute value starts with the given string.
 	 */
-	public static function attribute_starts_with( $haystack, $search_text, $case_sensitivity = 'case-sensitive' ) {
+	public static function attribute_starts_with( $haystack, $search_text, $case_sensitivity = 'case-sensitive' ): bool {
 		$search_length = strlen( $search_text );
 		$loose_case    = 'ascii-case-insensitive' === $case_sensitivity;
 		$haystack_end  = strlen( $haystack );
@@ -90,7 +90,7 @@ public static function attribute_starts_with( $haystack, $search_text, $case_sen
 	 * @param string $text Text containing raw and non-decoded text node to decode.
 	 * @return string Decoded UTF-8 value of given text node.
 	 */
-	public static function decode_text_node( $text ) {
+	public static function decode_text_node( $text ): string {
 		return static::decode( 'data', $text );
 	}
 
@@ -110,7 +110,7 @@ public static function decode_text_node( $text ) {
 	 * @param string $text Text containing raw and non-decoded attribute value to decode.
 	 * @return string Decoded UTF-8 value of given attribute value.
 	 */
-	public static function decode_attribute( $text ) {
+	public static function decode_attribute( $text ): string {
 		return static::decode( 'attribute', $text );
 	}
 
@@ -133,7 +133,7 @@ public static function decode_attribute( $text ) {
 	 * @param string $text    Text document containing span of text to decode.
 	 * @return string Decoded UTF-8 string.
 	 */
-	public static function decode( $context, $text ) {
+	public static function decode( $context, $text ): string {
 		$decoded = '';
 		$end     = strlen( $text );
 		$at      = 0;
@@ -421,7 +421,7 @@ public static function read_character_reference( $context, $text, $at = 0, &$mat
 	 * @param int $code_point Which code point to convert.
 	 * @return string Converted code point, or `�` if invalid.
 	 */
-	public static function code_point_to_utf8_bytes( $code_point ) {
+	public static function code_point_to_utf8_bytes( $code_point ): string {
 		// Pre-check to ensure a valid code point.
 		if (
 			$code_point <= 0 ||
diff --git a/src/wp-includes/html-api/class-wp-html-open-elements.php b/src/wp-includes/html-api/class-wp-html-open-elements.php
index df6ba8158b085..065bbd25c9814 100644
--- a/src/wp-includes/html-api/class-wp-html-open-elements.php
+++ b/src/wp-includes/html-api/class-wp-html-open-elements.php
@@ -58,7 +58,7 @@ class WP_HTML_Open_Elements {
 	 *
 	 * @since 6.6.0
 	 *
-	 * @var Closure
+	 * @var Closure|null
 	 */
 	private $pop_handler = null;
 
@@ -69,7 +69,7 @@ class WP_HTML_Open_Elements {
 	 *
 	 * @since 6.6.0
 	 *
-	 * @var Closure
+	 * @var Closure|null
 	 */
 	private $push_handler = null;
 
@@ -83,7 +83,7 @@ class WP_HTML_Open_Elements {
 	 *
 	 * @param Closure $handler The handler function.
 	 */
-	public function set_pop_handler( Closure $handler ) {
+	public function set_pop_handler( Closure $handler ): void {
 		$this->pop_handler = $handler;
 	}
 
@@ -97,7 +97,7 @@ public function set_pop_handler( Closure $handler ) {
 	 *
 	 * @param Closure $handler The handler function.
 	 */
-	public function set_push_handler( Closure $handler ) {
+	public function set_push_handler( Closure $handler ): void {
 		$this->push_handler = $handler;
 	}
 
@@ -109,7 +109,7 @@ public function set_push_handler( Closure $handler ) {
 	 * @param WP_HTML_Token $token Look for this node in the stack.
 	 * @return bool Whether the referenced node is in the stack of open elements.
 	 */
-	public function contains_node( $token ) {
+	public function contains_node( WP_HTML_Token $token ): bool {
 		foreach ( $this->walk_up() as $item ) {
 			if ( $token->bookmark_name === $item->bookmark_name ) {
 				return true;
@@ -126,7 +126,7 @@ public function contains_node( $token ) {
 	 *
 	 * @return int How many node are in the stack of open elements.
 	 */
-	public function count() {
+	public function count(): int {
 		return count( $this->stack );
 	}
 
@@ -138,7 +138,7 @@ public function count() {
 	 *
 	 * @return WP_HTML_Token|null Last node in the stack of open elements, if one exists, otherwise null.
 	 */
-	public function current_node() {
+	public function current_node(): ?WP_HTML_Token {
 		$current_node = end( $this->stack );
 
 		return $current_node ? $current_node : null;
@@ -197,7 +197,7 @@ public function current_node_is( string $identity ): bool {
 	 * @param string[] $termination_list List of elements that terminate the search.
 	 * @return bool Whether the element was found in a specific scope.
 	 */
-	public function has_element_in_specific_scope( $tag_name, $termination_list ) {
+	public function has_element_in_specific_scope( string $tag_name, $termination_list ): bool {
 		foreach ( $this->walk_up() as $node ) {
 			if ( $node->node_name === $tag_name ) {
 				return true;
@@ -233,7 +233,7 @@ public function has_element_in_specific_scope( $tag_name, $termination_list ) {
 	 * @param string $tag_name Name of tag to check.
 	 * @return bool Whether given element is in scope.
 	 */
-	public function has_element_in_scope( $tag_name ) {
+	public function has_element_in_scope( string $tag_name ): bool {
 		return $this->has_element_in_specific_scope(
 			$tag_name,
 			array(
@@ -260,7 +260,7 @@ public function has_element_in_scope( $tag_name ) {
 	 * @param string $tag_name Name of tag to check.
 	 * @return bool Whether given element is in scope.
 	 */
-	public function has_element_in_list_item_scope( $tag_name ) {
+	public function has_element_in_list_item_scope( string $tag_name ): bool {
 		return $this->has_element_in_specific_scope(
 			$tag_name,
 			array(
@@ -281,7 +281,7 @@ public function has_element_in_list_item_scope( $tag_name ) {
 	 * @param string $tag_name Name of tag to check.
 	 * @return bool Whether given element is in scope.
 	 */
-	public function has_element_in_button_scope( $tag_name ) {
+	public function has_element_in_button_scope( string $tag_name ): bool {
 		return $this->has_element_in_specific_scope( $tag_name, array( 'BUTTON' ) );
 	}
 
@@ -297,7 +297,7 @@ public function has_element_in_button_scope( $tag_name ) {
 	 * @param string $tag_name Name of tag to check.
 	 * @return bool Whether given element is in scope.
 	 */
-	public function has_element_in_table_scope( $tag_name ) {
+	public function has_element_in_table_scope( string $tag_name ): bool {
 		throw new WP_HTML_Unsupported_Exception( 'Cannot process elements depending on table scope.' );
 
 		return false; // The linter requires this unreachable code until the function is implemented and can return.
@@ -323,7 +323,7 @@ public function has_element_in_table_scope( $tag_name ) {
 	 * @param string $tag_name Name of tag to check.
 	 * @return bool Whether the given element is in SELECT scope.
 	 */
-	public function has_element_in_select_scope( $tag_name ) {
+	public function has_element_in_select_scope( string $tag_name ): bool {
 		foreach ( $this->walk_up() as $node ) {
 			if ( $node->node_name === $tag_name ) {
 				return true;
@@ -349,7 +349,7 @@ public function has_element_in_select_scope( $tag_name ) {
 	 *
 	 * @return bool Whether a P is in BUTTON scope.
 	 */
-	public function has_p_in_button_scope() {
+	public function has_p_in_button_scope(): bool {
 		return $this->has_p_in_button_scope;
 	}
 
@@ -362,7 +362,7 @@ public function has_p_in_button_scope() {
 	 *
 	 * @return bool Whether a node was popped off of the stack.
 	 */
-	public function pop() {
+	public function pop(): bool {
 		$item = array_pop( $this->stack );
 		if ( null === $item ) {
 			return false;
@@ -387,7 +387,7 @@ public function pop() {
 	 * @param string $tag_name Name of tag that needs to be popped off of the stack of open elements.
 	 * @return bool Whether a tag of the given name was found and popped off of the stack of open elements.
 	 */
-	public function pop_until( $tag_name ) {
+	public function pop_until( string $tag_name ): bool {
 		foreach ( $this->walk_up() as $item ) {
 			if ( 'context-node' === $item->bookmark_name ) {
 				return true;
@@ -419,7 +419,7 @@ public function pop_until( $tag_name ) {
 	 *
 	 * @param WP_HTML_Token $stack_item Item to add onto stack.
 	 */
-	public function push( $stack_item ) {
+	public function push( WP_HTML_Token $stack_item ): void {
 		$this->stack[] = $stack_item;
 		$this->after_element_push( $stack_item );
 	}
@@ -432,7 +432,7 @@ public function push( $stack_item ) {
 	 * @param WP_HTML_Token $token The node to remove from the stack of open elements.
 	 * @return bool Whether the node was found and removed from the stack of open elements.
 	 */
-	public function remove_node( $token ) {
+	public function remove_node( WP_HTML_Token $token ): bool {
 		if ( 'context-node' === $token->bookmark_name ) {
 			return false;
 		}
@@ -502,7 +502,7 @@ public function walk_down() {
 	 * @param WP_HTML_Token|null $above_this_node Optional. Start traversing above this node,
 	 *                                            if provided and if the node exists.
 	 */
-	public function walk_up( $above_this_node = null ) {
+	public function walk_up( ?WP_HTML_Token $above_this_node = null ) {
 		$has_found_node = null === $above_this_node;
 
 		for ( $i = count( $this->stack ) - 1; $i >= 0; $i-- ) {
@@ -534,7 +534,7 @@ public function walk_up( $above_this_node = null ) {
 	 *
 	 * @param WP_HTML_Token $item Element that was added to the stack of open elements.
 	 */
-	public function after_element_push( $item ) {
+	public function after_element_push( WP_HTML_Token $item ): void {
 		/*
 		 * When adding support for new elements, expand this switch to trap
 		 * cases where the precalculated value needs to change.
@@ -567,7 +567,7 @@ public function after_element_push( $item ) {
 	 *
 	 * @param WP_HTML_Token $item Element that was removed from the stack of open elements.
 	 */
-	public function after_element_pop( $item ) {
+	public function after_element_pop( WP_HTML_Token $item ): void {
 		/*
 		 * When adding support for new elements, expand this switch to trap
 		 * cases where the precalculated value needs to change.
diff --git a/src/wp-includes/html-api/class-wp-html-processor-state.php b/src/wp-includes/html-api/class-wp-html-processor-state.php
index ab75041bee3d0..eadfe30d26cf9 100644
--- a/src/wp-includes/html-api/class-wp-html-processor-state.php
+++ b/src/wp-includes/html-api/class-wp-html-processor-state.php
@@ -333,7 +333,7 @@ class WP_HTML_Processor_State {
 	 *
 	 * @var WP_HTML_Open_Elements
 	 */
-	public $stack_of_open_elements = null;
+	public $stack_of_open_elements;
 
 	/**
 	 * Tracks open formatting elements, used to handle mis-nested formatting element tags.
@@ -346,7 +346,7 @@ class WP_HTML_Processor_State {
 	 *
 	 * @var WP_HTML_Active_Formatting_Elements
 	 */
-	public $active_formatting_elements = null;
+	public $active_formatting_elements;
 
 	/**
 	 * Refers to the currently-matched tag, if any.
diff --git a/src/wp-includes/html-api/class-wp-html-processor.php b/src/wp-includes/html-api/class-wp-html-processor.php
index 679c4a7e50fa5..72f39d3ad7a7a 100644
--- a/src/wp-includes/html-api/class-wp-html-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-processor.php
@@ -159,7 +159,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
 	 *
 	 * @var WP_HTML_Processor_State
 	 */
-	private $state = null;
+	private $state;
 
 	/**
 	 * Used to create unique bookmark names.
@@ -208,7 +208,7 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor {
 	 *
 	 * @since 6.4.0
 	 *
-	 * @var closure
+	 * @var Closure|null
 	 */
 	private $release_internal_bookmark_on_destruct = null;
 
@@ -368,7 +368,7 @@ public function __construct( $html, $use_the_static_create_methods_instead = nul
 		$this->state = new WP_HTML_Processor_State();
 
 		$this->state->stack_of_open_elements->set_push_handler(
-			function ( WP_HTML_Token $token ) {
+			function ( WP_HTML_Token $token ): void {
 				$is_virtual            = ! isset( $this->state->current_token ) || $this->is_tag_closer();
 				$same_node             = isset( $this->state->current_token ) && $token->node_name === $this->state->current_token->node_name;
 				$provenance            = ( ! $same_node || $is_virtual ) ? 'virtual' : 'real';
@@ -377,7 +377,7 @@ function ( WP_HTML_Token $token ) {
 		);
 
 		$this->state->stack_of_open_elements->set_pop_handler(
-			function ( WP_HTML_Token $token ) {
+			function ( WP_HTML_Token $token ): void {
 				$is_virtual            = ! isset( $this->state->current_token ) || ! $this->is_tag_closer();
 				$same_node             = isset( $this->state->current_token ) && $token->node_name === $this->state->current_token->node_name;
 				$provenance            = ( ! $same_node || $is_virtual ) ? 'virtual' : 'real';
@@ -390,7 +390,7 @@ function ( WP_HTML_Token $token ) {
 		 * a private method into WP_HTML_Token classes without
 		 * exposing it to any public API.
 		 */
-		$this->release_internal_bookmark_on_destruct = function ( $name ) {
+		$this->release_internal_bookmark_on_destruct = function ( string $name ): void {
 			parent::release_bookmark( $name );
 		};
 	}
@@ -403,8 +403,6 @@ function ( WP_HTML_Token $token ) {
 	 * @since 6.7.0
 	 *
 	 * @param string $message Explains support is missing in order to parse the current node.
-	 *
-	 * @return mixed
 	 */
 	private function bail( string $message ) {
 		$here  = $this->bookmarks[ $this->state->current_token->bookmark_name ];
@@ -457,7 +455,7 @@ private function bail( string $message ) {
 	 *
 	 * @return string|null The last error, if one exists, otherwise null.
 	 */
-	public function get_last_error() {
+	public function get_last_error(): ?string {
 		return $this->last_error;
 	}
 
@@ -500,7 +498,7 @@ public function get_unsupported_exception() {
 	 * }
 	 * @return bool Whether a tag was matched.
 	 */
-	public function next_tag( $query = null ) {
+	public function next_tag( $query = null ): bool {
 		$visit_closers = isset( $query['tag_closers'] ) && 'visit' === $query['tag_closers'];
 
 		if ( null === $query ) {
@@ -590,7 +588,7 @@ public function next_tag( $query = null ) {
 	 *
 	 * @return bool
 	 */
-	public function next_token() {
+	public function next_token(): bool {
 		$this->current_element = null;
 
 		if ( isset( $this->last_error ) ) {
@@ -643,7 +641,6 @@ public function next_token() {
 		return true;
 	}
 
-
 	/**
 	 * Indicates if the current tag token is a tag closer.
 	 *
@@ -660,7 +657,7 @@ public function next_token() {
 	 *
 	 * @return bool Whether the current tag is a tag closer.
 	 */
-	public function is_tag_closer() {
+	public function is_tag_closer(): bool {
 		return $this->is_virtual()
 			? ( WP_HTML_Stack_Event::POP === $this->current_element->operation && '#tag' === $this->get_token_type() )
 			: parent::is_tag_closer();
@@ -674,7 +671,7 @@ public function is_tag_closer() {
 	 *
 	 * @return bool Whether the current token is virtual.
 	 */
-	private function is_virtual() {
+	private function is_virtual(): bool {
 		return (
 			isset( $this->current_element->provenance ) &&
 			'virtual' === $this->current_element->provenance
@@ -706,7 +703,7 @@ private function is_virtual() {
 	 *                              May also contain the wildcard `*` which matches a single element, e.g. `array( 'SECTION', '*' )`.
 	 * @return bool Whether the currently-matched tag is found at the given nested structure.
 	 */
-	public function matches_breadcrumbs( $breadcrumbs ) {
+	public function matches_breadcrumbs( $breadcrumbs ): bool {
 		// Everything matches when there are zero constraints.
 		if ( 0 === count( $breadcrumbs ) ) {
 			return true;
@@ -757,7 +754,7 @@ public function matches_breadcrumbs( $breadcrumbs ) {
 	 * @return bool|null Whether to expect a closer for the currently-matched node,
 	 *                   or `null` if not matched on any token.
 	 */
-	public function expects_closer( $node = null ) {
+	public function expects_closer( $node = null ): ?bool {
 		$token_name = $node->node_name ?? $this->get_token_name();
 		if ( ! isset( $token_name ) ) {
 			return null;
@@ -788,7 +785,7 @@ public function expects_closer( $node = null ) {
 	 * @param string $node_to_process Whether to parse the next node or reprocess the current node.
 	 * @return bool Whether a tag was matched.
 	 */
-	public function step( $node_to_process = self::PROCESS_NEXT_NODE ) {
+	public function step( $node_to_process = self::PROCESS_NEXT_NODE ): bool {
 		// Refuse to proceed if there was a previous error.
 		if ( null !== $this->last_error ) {
 			return false;
@@ -938,7 +935,7 @@ public function step( $node_to_process = self::PROCESS_NEXT_NODE ) {
 	 *
 	 * @return string[]|null Array of tag names representing path to matched node, if matched, otherwise NULL.
 	 */
-	public function get_breadcrumbs() {
+	public function get_breadcrumbs(): ?array {
 		return $this->breadcrumbs;
 	}
 
@@ -967,7 +964,7 @@ public function get_breadcrumbs() {
 	 *
 	 * @return int Nesting-depth of current location in the document.
 	 */
-	public function get_current_depth() {
+	public function get_current_depth(): int {
 		return count( $this->breadcrumbs );
 	}
 
@@ -986,7 +983,7 @@ public function get_current_depth() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_initial() {
+	private function step_initial(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1005,7 +1002,7 @@ private function step_initial() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_before_html() {
+	private function step_before_html(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1024,7 +1021,7 @@ private function step_before_html() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_before_head() {
+	private function step_before_head(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1043,7 +1040,7 @@ private function step_before_head() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_head() {
+	private function step_in_head(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1062,7 +1059,7 @@ private function step_in_head() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_head_noscript() {
+	private function step_in_head_noscript(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1081,7 +1078,7 @@ private function step_in_head_noscript() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_after_head() {
+	private function step_after_head(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1100,7 +1097,7 @@ private function step_after_head() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_body() {
+	private function step_in_body(): bool {
 		$token_name = $this->get_token_name();
 		$token_type = $this->get_token_type();
 		$op_sigil   = '#tag' === $token_type ? ( parent::is_tag_closer() ? '-' : '+' ) : '';
@@ -1723,7 +1720,7 @@ private function step_in_body() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_table() {
+	private function step_in_table(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1742,7 +1739,7 @@ private function step_in_table() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_table_text() {
+	private function step_in_table_text(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1761,7 +1758,7 @@ private function step_in_table_text() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_caption() {
+	private function step_in_caption(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1780,7 +1777,7 @@ private function step_in_caption() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_column_group() {
+	private function step_in_column_group(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1799,7 +1796,7 @@ private function step_in_column_group() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_table_body() {
+	private function step_in_table_body(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1818,7 +1815,7 @@ private function step_in_table_body() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_row() {
+	private function step_in_row(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1837,7 +1834,7 @@ private function step_in_row() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_cell() {
+	private function step_in_cell(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -1856,7 +1853,7 @@ private function step_in_cell() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_select() {
+	private function step_in_select(): bool {
 		$token_name = $this->get_token_name();
 		$token_type = $this->get_token_type();
 		$op_sigil   = '#tag' === $token_type ? ( parent::is_tag_closer() ? '-' : '+' ) : '';
@@ -2037,7 +2034,7 @@ private function step_in_select() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_select_in_table() {
+	private function step_in_select_in_table(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -2056,7 +2053,7 @@ private function step_in_select_in_table() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_template() {
+	private function step_in_template(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -2075,7 +2072,7 @@ private function step_in_template() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_after_body() {
+	private function step_after_body(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -2094,7 +2091,7 @@ private function step_after_body() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_frameset() {
+	private function step_in_frameset(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -2113,7 +2110,7 @@ private function step_in_frameset() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_after_frameset() {
+	private function step_after_frameset(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -2132,7 +2129,7 @@ private function step_after_frameset() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_after_after_body() {
+	private function step_after_after_body(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -2151,7 +2148,7 @@ private function step_after_after_body() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_after_after_frameset() {
+	private function step_after_after_frameset(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -2170,7 +2167,7 @@ private function step_after_after_frameset() {
 	 *
 	 * @return bool Whether an element was found.
 	 */
-	private function step_in_foreign_content() {
+	private function step_in_foreign_content(): bool {
 		$this->bail( "No support for parsing in the '{$this->state->insertion_mode}' state." );
 	}
 
@@ -2222,7 +2219,7 @@ private function bookmark_token() {
 	 *
 	 * @return string|null Name of currently matched tag in input HTML, or `null` if none found.
 	 */
-	public function get_tag() {
+	public function get_tag(): ?string {
 		if ( null !== $this->last_error ) {
 			return null;
 		}
@@ -2263,7 +2260,7 @@ public function get_tag() {
 	 *
 	 * @return bool Whether the currently matched tag contains the self-closing flag.
 	 */
-	public function has_self_closing_flag() {
+	public function has_self_closing_flag(): bool {
 		return $this->is_virtual() ? false : parent::has_self_closing_flag();
 	}
 
@@ -2287,7 +2284,7 @@ public function has_self_closing_flag() {
 	 *
 	 * @return string|null Name of the matched token.
 	 */
-	public function get_token_name() {
+	public function get_token_name(): ?string {
 		return $this->is_virtual()
 			? $this->current_element->token->node_name
 			: parent::get_token_name();
@@ -2315,7 +2312,7 @@ public function get_token_name() {
 	 *
 	 * @return string|null What kind of token is matched, or null.
 	 */
-	public function get_token_type() {
+	public function get_token_type(): ?string {
 		if ( $this->is_virtual() ) {
 			/*
 			 * This logic comes from the Tag Processor.
@@ -2377,7 +2374,7 @@ public function get_attribute( $name ) {
 	 * @param string|bool $value The new attribute value.
 	 * @return bool Whether an attribute value was set.
 	 */
-	public function set_attribute( $name, $value ) {
+	public function set_attribute( $name, $value ): bool {
 		return $this->is_virtual() ? false : parent::set_attribute( $name, $value );
 	}
 
@@ -2389,7 +2386,7 @@ public function set_attribute( $name, $value ) {
 	 * @param string $name The attribute name to remove.
 	 * @return bool Whether an attribute was removed.
 	 */
-	public function remove_attribute( $name ) {
+	public function remove_attribute( $name ): bool {
 		return $this->is_virtual() ? false : parent::remove_attribute( $name );
 	}
 
@@ -2419,7 +2416,7 @@ public function remove_attribute( $name ) {
 	 * @param string $prefix Prefix of requested attribute names.
 	 * @return array|null List of attribute names, or `null` when no tag opener is matched.
 	 */
-	public function get_attribute_names_with_prefix( $prefix ) {
+	public function get_attribute_names_with_prefix( $prefix ): ?array {
 		return $this->is_virtual() ? null : parent::get_attribute_names_with_prefix( $prefix );
 	}
 
@@ -2431,7 +2428,7 @@ public function get_attribute_names_with_prefix( $prefix ) {
 	 * @param string $class_name The class name to add.
 	 * @return bool Whether the class was set to be added.
 	 */
-	public function add_class( $class_name ) {
+	public function add_class( $class_name ): bool {
 		return $this->is_virtual() ? false : parent::add_class( $class_name );
 	}
 
@@ -2443,7 +2440,7 @@ public function add_class( $class_name ) {
 	 * @param string $class_name The class name to remove.
 	 * @return bool Whether the class was set to be removed.
 	 */
-	public function remove_class( $class_name ) {
+	public function remove_class( $class_name ): bool {
 		return $this->is_virtual() ? false : parent::remove_class( $class_name );
 	}
 
@@ -2455,7 +2452,7 @@ public function remove_class( $class_name ) {
 	 * @param string $wanted_class Look for this CSS class name, ASCII case-insensitive.
 	 * @return bool|null Whether the matched tag contains the given class name, or null if not matched.
 	 */
-	public function has_class( $wanted_class ) {
+	public function has_class( $wanted_class ): ?bool {
 		return $this->is_virtual() ? null : parent::has_class( $wanted_class );
 	}
 
@@ -2499,7 +2496,7 @@ public function class_list() {
 	 *
 	 * @return string
 	 */
-	public function get_modifiable_text() {
+	public function get_modifiable_text(): string {
 		return $this->is_virtual() ? '' : parent::get_modifiable_text();
 	}
 
@@ -2522,7 +2519,7 @@ public function get_modifiable_text() {
 	 *
 	 * @return string|null
 	 */
-	public function get_comment_type() {
+	public function get_comment_type(): ?string {
 		return $this->is_virtual() ? null : parent::get_comment_type();
 	}
 
@@ -2537,7 +2534,7 @@ public function get_comment_type() {
 	 * @param string $bookmark_name Name of the bookmark to remove.
 	 * @return bool Whether the bookmark already existed before removal.
 	 */
-	public function release_bookmark( $bookmark_name ) {
+	public function release_bookmark( $bookmark_name ): bool {
 		return parent::release_bookmark( "_{$bookmark_name}" );
 	}
 
@@ -2558,7 +2555,7 @@ public function release_bookmark( $bookmark_name ) {
 	 * @param string $bookmark_name Jump to the place in the document identified by this bookmark name.
 	 * @return bool Whether the internal cursor was successfully moved to the bookmark's location.
 	 */
-	public function seek( $bookmark_name ) {
+	public function seek( $bookmark_name ): bool {
 		// Flush any pending updates to the document before beginning.
 		$this->get_updated_html();
 
@@ -2729,7 +2726,7 @@ public function seek( $bookmark_name ) {
 	 * @param string $bookmark_name Identifies this particular bookmark.
 	 * @return bool Whether the bookmark was successfully created.
 	 */
-	public function set_bookmark( $bookmark_name ) {
+	public function set_bookmark( $bookmark_name ): bool {
 		return parent::set_bookmark( "_{$bookmark_name}" );
 	}
 
@@ -2741,7 +2738,7 @@ public function set_bookmark( $bookmark_name ) {
 	 * @param string $bookmark_name Name to identify a bookmark that potentially exists.
 	 * @return bool Whether that bookmark exists.
 	 */
-	public function has_bookmark( $bookmark_name ) {
+	public function has_bookmark( $bookmark_name ): bool {
 		return parent::has_bookmark( "_{$bookmark_name}" );
 	}
 
@@ -2758,7 +2755,7 @@ public function has_bookmark( $bookmark_name ) {
 	 *
 	 * @see https://html.spec.whatwg.org/#close-a-p-element
 	 */
-	private function close_a_p_element() {
+	private function close_a_p_element(): void {
 		$this->generate_implied_end_tags( 'P' );
 		$this->state->stack_of_open_elements->pop_until( 'P' );
 	}
@@ -2773,7 +2770,7 @@ private function close_a_p_element() {
 	 *
 	 * @param string|null $except_for_this_element Perform as if this element doesn't exist in the stack of open elements.
 	 */
-	private function generate_implied_end_tags( $except_for_this_element = null ) {
+	private function generate_implied_end_tags( ?string $except_for_this_element = null ): void {
 		$elements_with_implied_end_tags = array(
 			'DD',
 			'DT',
@@ -2809,7 +2806,7 @@ private function generate_implied_end_tags( $except_for_this_element = null ) {
 	 * @see WP_HTML_Processor::generate_implied_end_tags
 	 * @see https://html.spec.whatwg.org/#generate-implied-end-tags
 	 */
-	private function generate_implied_end_tags_thoroughly() {
+	private function generate_implied_end_tags_thoroughly(): void {
 		$elements_with_implied_end_tags = array(
 			'CAPTION',
 			'COLGROUP',
@@ -2851,7 +2848,7 @@ private function generate_implied_end_tags_thoroughly() {
 	 *
 	 * @return bool Whether any formatting elements needed to be reconstructed.
 	 */
-	private function reconstruct_active_formatting_elements() {
+	private function reconstruct_active_formatting_elements(): bool {
 		/*
 		 * > If there are no entries in the list of active formatting elements, then there is nothing
 		 * > to reconstruct; stop this algorithm.
@@ -3074,7 +3071,7 @@ public function reset_insertion_mode(): void {
 	 *
 	 * @see https://html.spec.whatwg.org/#adoption-agency-algorithm
 	 */
-	private function run_adoption_agency_algorithm() {
+	private function run_adoption_agency_algorithm(): void {
 		$budget       = 1000;
 		$subject      = $this->get_tag();
 		$current_node = $this->state->stack_of_open_elements->current_node();
@@ -3182,7 +3179,7 @@ private function run_adoption_agency_algorithm() {
 	 *
 	 * @param WP_HTML_Token $token Name of bookmark pointing to element in original input HTML.
 	 */
-	private function insert_html_element( $token ) {
+	private function insert_html_element( WP_HTML_Token $token ): void {
 		$this->state->stack_of_open_elements->push( $token );
 	}
 
@@ -3200,7 +3197,7 @@ private function insert_html_element( $token ) {
 	 * @param string $tag_name Name of element to check.
 	 * @return bool Whether the element of the given name is in the special category.
 	 */
-	public static function is_special( $tag_name ) {
+	public static function is_special( $tag_name ): bool {
 		$tag_name = strtoupper( $tag_name );
 
 		return (
@@ -3315,7 +3312,7 @@ public static function is_special( $tag_name ) {
 	 * @param string $tag_name Name of HTML tag to check.
 	 * @return bool Whether the given tag is an HTML Void Element.
 	 */
-	public static function is_void( $tag_name ) {
+	public static function is_void( $tag_name ): bool {
 		$tag_name = strtoupper( $tag_name );
 
 		return (
diff --git a/src/wp-includes/html-api/class-wp-html-span.php b/src/wp-includes/html-api/class-wp-html-span.php
index b1ab865af3bed..04a1d5258c904 100644
--- a/src/wp-includes/html-api/class-wp-html-span.php
+++ b/src/wp-includes/html-api/class-wp-html-span.php
@@ -49,7 +49,7 @@ class WP_HTML_Span {
 	 * @param int $start  Byte offset into document where replacement span begins.
 	 * @param int $length Byte length of span.
 	 */
-	public function __construct( $start, $length ) {
+	public function __construct( int $start, int $length ) {
 		$this->start  = $start;
 		$this->length = $length;
 	}
diff --git a/src/wp-includes/html-api/class-wp-html-stack-event.php b/src/wp-includes/html-api/class-wp-html-stack-event.php
index aa4763cd399fc..dcb3c79ef1003 100644
--- a/src/wp-includes/html-api/class-wp-html-stack-event.php
+++ b/src/wp-includes/html-api/class-wp-html-stack-event.php
@@ -74,7 +74,7 @@ class WP_HTML_Stack_Event {
 	 * @param string        $operation  One of self::PUSH or self::POP.
 	 * @param string        $provenance "virtual" or "real".
 	 */
-	public function __construct( $token, $operation, $provenance ) {
+	public function __construct( WP_HTML_Token $token, string $operation, string $provenance ) {
 		$this->token      = $token;
 		$this->operation  = $operation;
 		$this->provenance = $provenance;
diff --git a/src/wp-includes/html-api/class-wp-html-tag-processor.php b/src/wp-includes/html-api/class-wp-html-tag-processor.php
index 46fc192083ec6..77782aa950625 100644
--- a/src/wp-includes/html-api/class-wp-html-tag-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-tag-processor.php
@@ -784,7 +784,7 @@ public function __construct( $html ) {
 	 * }
 	 * @return bool Whether a tag was matched.
 	 */
-	public function next_tag( $query = null ) {
+	public function next_tag( $query = null ): bool {
 		$this->parse_query( $query );
 		$already_found = 0;
 
@@ -832,7 +832,7 @@ public function next_tag( $query = null ) {
 	 *
 	 * @return bool Whether a token was parsed.
 	 */
-	public function next_token() {
+	public function next_token(): bool {
 		return $this->base_class_next_token();
 	}
 
@@ -851,7 +851,7 @@ public function next_token() {
 	 *
 	 * @return bool Whether a token was parsed.
 	 */
-	private function base_class_next_token() {
+	private function base_class_next_token(): bool {
 		$was_at = $this->bytes_already_parsed;
 		$this->after_tag();
 
@@ -1033,7 +1033,7 @@ private function base_class_next_token() {
 	 *
 	 * @return bool Whether the parse paused at the start of an incomplete token.
 	 */
-	public function paused_at_incomplete_token() {
+	public function paused_at_incomplete_token(): bool {
 		return self::STATE_INCOMPLETE_INPUT === $this->parser_state;
 	}
 
@@ -1112,7 +1112,7 @@ public function class_list() {
 	 * @param string $wanted_class Look for this CSS class name, ASCII case-insensitive.
 	 * @return bool|null Whether the matched tag contains the given class name, or null if not matched.
 	 */
-	public function has_class( $wanted_class ) {
+	public function has_class( $wanted_class ): ?bool {
 		if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
 			return null;
 		}
@@ -1209,7 +1209,7 @@ public function has_class( $wanted_class ) {
 	 * @param string $name Identifies this particular bookmark.
 	 * @return bool Whether the bookmark was successfully created.
 	 */
-	public function set_bookmark( $name ) {
+	public function set_bookmark( $name ): bool {
 		// It only makes sense to set a bookmark if the parser has paused on a concrete token.
 		if (
 			self::STATE_COMPLETE === $this->parser_state ||
@@ -1242,7 +1242,7 @@ public function set_bookmark( $name ) {
 	 * @param string $name Name of the bookmark to remove.
 	 * @return bool Whether the bookmark already existed before removal.
 	 */
-	public function release_bookmark( $name ) {
+	public function release_bookmark( $name ): bool {
 		if ( ! array_key_exists( $name, $this->bookmarks ) ) {
 			return false;
 		}
@@ -1262,7 +1262,7 @@ public function release_bookmark( $name ) {
 	 * @param string $tag_name The uppercase tag name which will close the RAWTEXT region.
 	 * @return bool Whether an end to the RAWTEXT region was found before the end of the document.
 	 */
-	private function skip_rawtext( $tag_name ) {
+	private function skip_rawtext( string $tag_name ): bool {
 		/*
 		 * These two functions distinguish themselves on whether character references are
 		 * decoded, and since functionality to read the inner markup isn't supported, it's
@@ -1281,7 +1281,7 @@ private function skip_rawtext( $tag_name ) {
 	 * @param string $tag_name The uppercase tag name which will close the RCDATA region.
 	 * @return bool Whether an end to the RCDATA region was found before the end of the document.
 	 */
-	private function skip_rcdata( $tag_name ) {
+	private function skip_rcdata( string $tag_name ): bool {
 		$html       = $this->html;
 		$doc_length = strlen( $html );
 		$tag_length = strlen( $tag_name );
@@ -1369,7 +1369,7 @@ private function skip_rcdata( $tag_name ) {
 	 *
 	 * @return bool Whether the script tag was closed before the end of the document.
 	 */
-	private function skip_script_data() {
+	private function skip_script_data(): bool {
 		$state      = 'unescaped';
 		$html       = $this->html;
 		$doc_length = strlen( $html );
@@ -1516,7 +1516,7 @@ private function skip_script_data() {
 	 *
 	 * @return bool Whether a tag was found before the end of the document.
 	 */
-	private function parse_next_tag() {
+	private function parse_next_tag(): bool {
 		$this->after_tag();
 
 		$html       = $this->html;
@@ -1906,7 +1906,7 @@ private function parse_next_tag() {
 	 *
 	 * @return bool Whether an attribute was found before the end of the document.
 	 */
-	private function parse_next_attribute() {
+	private function parse_next_attribute(): bool {
 		$doc_length = strlen( $this->html );
 
 		// Skip whitespace and slashes.
@@ -2041,7 +2041,7 @@ private function parse_next_attribute() {
 	 *
 	 * @since 6.2.0
 	 */
-	private function skip_whitespace() {
+	private function skip_whitespace(): void {
 		$this->bytes_already_parsed += strspn( $this->html, " \t\f\r\n", $this->bytes_already_parsed );
 	}
 
@@ -2050,7 +2050,7 @@ private function skip_whitespace() {
 	 *
 	 * @since 6.2.0
 	 */
-	private function after_tag() {
+	private function after_tag(): void {
 		/*
 		 * There could be lexical updates enqueued for an attribute that
 		 * also exists on the next tag. In order to avoid conflating the
@@ -2111,7 +2111,7 @@ private function after_tag() {
 	 * @see WP_HTML_Tag_Processor::$lexical_updates
 	 * @see WP_HTML_Tag_Processor::$classname_updates
 	 */
-	private function class_name_updates_to_attributes_updates() {
+	private function class_name_updates_to_attributes_updates(): void {
 		if ( count( $this->classname_updates ) === 0 ) {
 			return;
 		}
@@ -2256,7 +2256,7 @@ private function class_name_updates_to_attributes_updates() {
 	 * @param int $shift_this_point Accumulate and return shift for this position.
 	 * @return int How many bytes the given pointer moved in response to the updates.
 	 */
-	private function apply_attributes_updates( $shift_this_point ) {
+	private function apply_attributes_updates( int $shift_this_point ): int {
 		if ( ! count( $this->lexical_updates ) ) {
 			return 0;
 		}
@@ -2353,7 +2353,7 @@ private function apply_attributes_updates( $shift_this_point ) {
 	 * @param string $bookmark_name Name to identify a bookmark that potentially exists.
 	 * @return bool Whether that bookmark exists.
 	 */
-	public function has_bookmark( $bookmark_name ) {
+	public function has_bookmark( $bookmark_name ): bool {
 		return array_key_exists( $bookmark_name, $this->bookmarks );
 	}
 
@@ -2368,7 +2368,7 @@ public function has_bookmark( $bookmark_name ) {
 	 * @param string $bookmark_name Jump to the place in the document identified by this bookmark name.
 	 * @return bool Whether the internal cursor was successfully moved to the bookmark's location.
 	 */
-	public function seek( $bookmark_name ) {
+	public function seek( $bookmark_name ): bool {
 		if ( ! array_key_exists( $bookmark_name, $this->bookmarks ) ) {
 			_doing_it_wrong(
 				__METHOD__,
@@ -2405,7 +2405,7 @@ public function seek( $bookmark_name ) {
 	 * @param WP_HTML_Text_Replacement $b Second attribute update.
 	 * @return int Comparison value for string order.
 	 */
-	private static function sort_start_ascending( $a, $b ) {
+	private static function sort_start_ascending( WP_HTML_Text_Replacement $a, WP_HTML_Text_Replacement $b ): int {
 		$by_start = $a->start - $b->start;
 		if ( 0 !== $by_start ) {
 			return $by_start;
@@ -2437,7 +2437,7 @@ private static function sort_start_ascending( $a, $b ) {
 	 * @param string $comparable_name The attribute name in its comparable form.
 	 * @return string|boolean|null Value of enqueued update if present, otherwise false.
 	 */
-	private function get_enqueued_attribute_value( $comparable_name ) {
+	private function get_enqueued_attribute_value( string $comparable_name ) {
 		if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
 			return false;
 		}
@@ -2588,7 +2588,7 @@ public function get_attribute( $name ) {
 	 * @param string $prefix Prefix of requested attribute names.
 	 * @return array|null List of attribute names, or `null` when no tag opener is matched.
 	 */
-	public function get_attribute_names_with_prefix( $prefix ) {
+	public function get_attribute_names_with_prefix( $prefix ): ?array {
 		if (
 			self::STATE_MATCHED_TAG !== $this->parser_state ||
 			$this->is_closing_tag
@@ -2623,7 +2623,7 @@ public function get_attribute_names_with_prefix( $prefix ) {
 	 *
 	 * @return string|null Name of currently matched tag in input HTML, or `null` if none found.
 	 */
-	public function get_tag() {
+	public function get_tag(): ?string {
 		if ( null === $this->tag_name_starts_at ) {
 			return null;
 		}
@@ -2661,7 +2661,7 @@ public function get_tag() {
 	 *
 	 * @return bool Whether the currently matched tag contains the self-closing flag.
 	 */
-	public function has_self_closing_flag() {
+	public function has_self_closing_flag(): bool {
 		if ( self::STATE_MATCHED_TAG !== $this->parser_state ) {
 			return false;
 		}
@@ -2693,7 +2693,7 @@ public function has_self_closing_flag() {
 	 *
 	 * @return bool Whether the current tag is a tag closer.
 	 */
-	public function is_tag_closer() {
+	public function is_tag_closer(): bool {
 		return (
 			self::STATE_MATCHED_TAG === $this->parser_state &&
 			$this->is_closing_tag
@@ -2722,7 +2722,7 @@ public function is_tag_closer() {
 	 *
 	 * @return string|null What kind of token is matched, or null.
 	 */
-	public function get_token_type() {
+	public function get_token_type(): ?string {
 		switch ( $this->parser_state ) {
 			case self::STATE_MATCHED_TAG:
 				return '#tag';
@@ -2755,7 +2755,7 @@ public function get_token_type() {
 	 *
 	 * @return string|null Name of the matched token.
 	 */
-	public function get_token_name() {
+	public function get_token_name(): ?string {
 		switch ( $this->parser_state ) {
 			case self::STATE_MATCHED_TAG:
 				return $this->get_tag();
@@ -2801,7 +2801,7 @@ public function get_token_name() {
 	 *
 	 * @return string|null
 	 */
-	public function get_comment_type() {
+	public function get_comment_type(): ?string {
 		if ( self::STATE_COMMENT !== $this->parser_state ) {
 			return null;
 		}
@@ -2829,7 +2829,7 @@ public function get_comment_type() {
 	 *
 	 * @return string
 	 */
-	public function get_modifiable_text() {
+	public function get_modifiable_text(): string {
 		if ( null === $this->text_starts_at ) {
 			return '';
 		}
@@ -2899,7 +2899,7 @@ public function get_modifiable_text() {
 	 * @param string|bool $value The new attribute value.
 	 * @return bool Whether an attribute value was set.
 	 */
-	public function set_attribute( $name, $value ) {
+	public function set_attribute( $name, $value ): bool {
 		if (
 			self::STATE_MATCHED_TAG !== $this->parser_state ||
 			$this->is_closing_tag
@@ -3042,7 +3042,7 @@ public function set_attribute( $name, $value ) {
 	 * @param string $name The attribute name to remove.
 	 * @return bool Whether an attribute was removed.
 	 */
-	public function remove_attribute( $name ) {
+	public function remove_attribute( $name ): bool {
 		if (
 			self::STATE_MATCHED_TAG !== $this->parser_state ||
 			$this->is_closing_tag
@@ -3120,7 +3120,7 @@ public function remove_attribute( $name ) {
 	 * @param string $class_name The class name to add.
 	 * @return bool Whether the class was set to be added.
 	 */
-	public function add_class( $class_name ) {
+	public function add_class( $class_name ): bool {
 		if (
 			self::STATE_MATCHED_TAG !== $this->parser_state ||
 			$this->is_closing_tag
@@ -3141,7 +3141,7 @@ public function add_class( $class_name ) {
 	 * @param string $class_name The class name to remove.
 	 * @return bool Whether the class was set to be removed.
 	 */
-	public function remove_class( $class_name ) {
+	public function remove_class( $class_name ): bool {
 		if (
 			self::STATE_MATCHED_TAG !== $this->parser_state ||
 			$this->is_closing_tag
@@ -3165,7 +3165,7 @@ public function remove_class( $class_name ) {
 	 *
 	 * @return string The processed HTML.
 	 */
-	public function __toString() {
+	public function __toString(): string {
 		return $this->get_updated_html();
 	}
 
@@ -3178,7 +3178,7 @@ public function __toString() {
 	 *
 	 * @return string The processed HTML.
 	 */
-	public function get_updated_html() {
+	public function get_updated_html(): string {
 		$requires_no_updating = 0 === count( $this->classname_updates ) && 0 === count( $this->lexical_updates );
 
 		/*
@@ -3300,7 +3300,7 @@ private function parse_query( $query ) {
 	 *
 	 * @return bool Whether the given tag and its attribute match the search criteria.
 	 */
-	private function matches() {
+	private function matches(): bool {
 		if ( $this->is_closing_tag && ! $this->stop_on_tag_closers ) {
 			return false;
 		}
diff --git a/src/wp-includes/html-api/class-wp-html-text-replacement.php b/src/wp-includes/html-api/class-wp-html-text-replacement.php
index 4b8a6a6aa289d..65e17d48fdb4a 100644
--- a/src/wp-includes/html-api/class-wp-html-text-replacement.php
+++ b/src/wp-includes/html-api/class-wp-html-text-replacement.php
@@ -56,7 +56,7 @@ class WP_HTML_Text_Replacement {
 	 * @param int    $length Byte length of span in document being replaced.
 	 * @param string $text   Span of text to insert in document to replace existing content from start to end.
 	 */
-	public function __construct( $start, $length, $text ) {
+	public function __construct( int $start, int $length, string $text ) {
 		$this->start  = $start;
 		$this->length = $length;
 		$this->text   = $text;
diff --git a/src/wp-includes/html-api/class-wp-html-token.php b/src/wp-includes/html-api/class-wp-html-token.php
index 86dd7658cfcee..fe8636fb5e164 100644
--- a/src/wp-includes/html-api/class-wp-html-token.php
+++ b/src/wp-includes/html-api/class-wp-html-token.php
@@ -72,12 +72,12 @@ class WP_HTML_Token {
 	 *
 	 * @since 6.4.0
 	 *
-	 * @param string   $bookmark_name         Name of bookmark corresponding to location in HTML where token is found.
-	 * @param string   $node_name             Name of node token represents; if uppercase, an HTML element; if lowercase, a special value like "marker".
-	 * @param bool     $has_self_closing_flag Whether the source token contains the self-closing flag, regardless of whether it's valid.
-	 * @param callable $on_destroy            Function to call when destroying token, useful for releasing the bookmark.
+	 * @param string        $bookmark_name         Name of bookmark corresponding to location in HTML where token is found.
+	 * @param string        $node_name             Name of node token represents; if uppercase, an HTML element; if lowercase, a special value like "marker".
+	 * @param bool          $has_self_closing_flag Whether the source token contains the self-closing flag, regardless of whether it's valid.
+	 * @param callable|null $on_destroy            Optional. Function to call when destroying token, useful for releasing the bookmark.
 	 */
-	public function __construct( $bookmark_name, $node_name, $has_self_closing_flag, $on_destroy = null ) {
+	public function __construct( string $bookmark_name, string $node_name, bool $has_self_closing_flag, ?callable $on_destroy = null ) {
 		$this->bookmark_name         = $bookmark_name;
 		$this->node_name             = $node_name;
 		$this->has_self_closing_flag = $has_self_closing_flag;