HTML API: Add type annotations

[jonsurrell]

The HTML API benefits from adding type annotations where possible and supported. It makes development easier and helps to discover tricky bugs.

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, they can be landed independently and as bugfixes for WordPress 6.6.

Trac ticket: https://core.trac.wordpress.org/ticket/61399

This applies three fixes that appeared as part of adding type annotations to the HTML API in #6753.

• Fix a bug where a string was passed instead of a token
• Fix Tag Processor bug where null was used as int
• Fix return type error in tag processor get_token_name

Trac ticket: https://core.trac.wordpress.org/ticket/61399

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See ​GitHub Pull Requests for Code Review in the Core Handbook for more details.

[dmsnell]

In 58364:

HTML API: Fix three small type-related bugs.

This applies three fixes that appeared as part of
adding type annotations to the HTML API.

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

Props jonsurrell.
See #61399.
Follow-up to [55203], [56274].

Merged in [58364]
​https://github.com/wordpress/wordpress-develop/commit/1626aacc5f79dbab006119c74cffbe15cfeb1251

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

[jonsurrell]

@dmsnell and I talked about this. @dmsnell shared concerns around this causing crashes on sites and wanting to be careful. These are valid.

We discussed introducing type annotations on places that should be safe, meaning that they can't introduce new crashes.

• Private methods may be safe to annotate completely.
• Return types should be safe to annotate.
• Public method arguments are more risky to type and we'll avoid them for now. It's relatively easy to pass values of the wrong type and introduce runtime errors.

I'll adapt ​PR#6753 accordingly.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Closes ​https://github.com/WordPress/wordpress-develop/pull/7031 (supersedes)

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

I've removed most of the type annotations from the parameters of public APIs. I did this to address concerns about the potential to break sites due to type errors from plugins that are not actionable in any way for the sites. I've maintained the type annotations on the private APIs and internal classes.

@dmsnell What do you think about the low-level API like the token map? Should I remove types in the same way there as well?

Trac ticket: Core-61399

[dmsnell]

In 58742:

Fix phpdoc nullable types in some files.

It was found that in several places in the HTML API and its supporting files,
the wrong form of type annotation was used for optional parameters.

Instead of using ?type, this patch uses type|type-of-default-value instead,
noting where important if the parameter is optional, and if so, what its default
value is.

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

Props dmsnell, jonsurrell.
See #61399.

Thank you, @sirreal. I updated the patch with some Optional. and Default declarations.

Merged in [58742]
​https://github.com/wordpress/wordpress-develop/commit/48c0c968468b54ec2909317e1a9384c0943c0dd3

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

@sirreal I think all of this as is is probably fine, but I want to run this against the Gutenberg repository first to ensure that nothing basic is broken, since we're introducing new intentional-breaking behaviors.

Backport contains these anticipated updates in the following Gutenberg PR.

​https://github.com/WordPress/gutenberg/pull/63723

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

[dmsnell]

In 58769:

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.

Merged in [58769]
​https://github.com/dmsnell/wordpress-develop/commit/0b179899a84f6b78e49ee7d2a92a78cb1f4f1651

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to ​https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes ​https://github.com/WordPress/wordpress-develop/pull/7031.

@dmsnell @sirreal:
I see 2-3 $case_sensitivity parameters (2nd/3rd parameters of a function) that could also get a string annotation?
Or is this similar to $termination_list not getting array as the PHPDoc has the more specific string[] (which is intentional from what I understand from the PR description)?
I would actually vote for adding these as well, as the annotations not only serve documentation purposes but also prevent wrong parameter types from being passed to the function.

@TobiasBg some of the annotations were removed to prevent site crashes when improperly called. I think we are still gathering experience knowing how to handle this scenario. the PHDDoc comment adds the types, right? so IDE's should still type-check, autocomplete, and auto-document the parameters.

I've seen plenty of well-intentioned efforts to add type annotations only to realize that something was a mistake and now WordPress crashes because the types were wrong. I'm sensitive to avoid doing this out of over-eagerness.

@dmsnell: Yes, PHPDocs (correctly) adds the types for syntax highlighting, autocomplete, documentation, use in static analysis, etc. But these are pretty much "optional". Only the annotations let PHP raise an error message if a parameter has the wrong type.

And of course that's why type annotations should be added with care (and e.g. prevent with custom type checks in the code) to prevent crashes! Thus, excluding public-facing functions from this totally makes sense!

I was more referring to "inconsistencies": E.g. in [https://core.trac.wordpress.org/changeset/58769/trunk/src/wp-includes/class-wp-token-map.php trunk/src/wp-includes/class-wp-token-map.php]:
In the line
{{{PHP
public function contains( string $word, string $case_sensitivity = 'case-sensitive' ): bool {
}}}
both parameters (including $case_sensitivity) got an annotation. But a few lines below, in the line
{{{PHP
public function read_token( string $text, int $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ): ?string {
}}}
only the first parameter got an annotation while the same $case_sensitivity parameter did not (but in both cases, it's PHPdoc'ed as string).
(I'm fine with the call-by-reference parameter not getting one, as I don't know what consequences that might have.)

Similarly, in trunk/src/wp-includes/html-api/class-wp-html-open-elements.php, there's the line
{{{PHP
public function has_element_in_specific_scope( string $tag_name, $termination_list ): bool {
}}}
where only the first parameter got an annotation.

@TobiasBg happy to review a patch!

[jonsurrell]

This was fixed in [58769].