[huzaifaalmesbah]

Description

In src/wp-includes/compat-utf8.php, by-reference parameters in _wp_scan_utf8() (&$has_noncharacters) and _wp_utf8_codepoint_span() (&$found_code_points) accept nullable input defaults, but are always assigned non-null values on exit (bool and int respectively).

Additionally, in _wp_scan_utf8(), $has_noncharacters was previously accumulated using bitwise OR assignment (|=), which coerced the boolean variable into an integer (0 or 1). Switching to boolean accumulating assignment ($has_noncharacters = $has_noncharacters || ( ... )) ensures it remains strictly a boolean.

This PR:

1. Adds @param-out bool $has_noncharacters to _wp_scan_utf8().
2. Standardizes @param int|null and adds @param-out int $found_code_points to _wp_utf8_codepoint_span().
3. Retires and deletes tests/phpstan/baselines/parameterByRef.unusedType.neon and updates phpstan.neon.dist.
4. Decrements 2 errors in tests/phpstan/baselines/parameterByRef.type.neon.
5. Adds unit tests covering _wp_scan_utf8() and boolean noncharacter detection.

Testing Instructions

1. Run composer phpstan locally to confirm analysis passes with 0 errors.
2. Run unit tests for charset compat functions:

   npm run test:php -- --filter=Tests_Compat_wpScanUtf8
   npm run test:php -- --filter=Tests_Compat_wpScanUtf8 -c tests/phpunit/multisite.xml
   npm run test:php -- --filter=Tests_Compat_wpUtf8CodePointSpan

3. Run PHPCS to verify coding standards:

   vendor/bin/phpcs src/wp-includes/compat-utf8.php tests/phpunit/tests/compat/wpScanUtf8.php

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

Use of AI Tools

AI assistance: Yes
Tool(s): Google Antigravity
Model(s): Gemini 3.8 Flash
Used for: Assisting with static analysis archaeology, PHPStan baseline synchronization, and diff preparation; all code and tests were manually reviewed, verified, and locally run by me.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props huzaifaalmesbah, lancewillett.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

---

Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

• @propsbot add <username> to give props to a GitHub user. Requires write access.
• @propsbot remove <username> to leave a user out of the props. Requires write access.
• @propsbot refresh to refresh this list. Adding the props-bot label works too.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[Copilot]

🟢 Approval recommended

There are no active review issues for the UTF-8 output-type clarifications and related PHPStan suppression cleanup.

No open issues 🎉

What changed in this PR

This PR clarifies by-reference output types in WordPress’s UTF-8 compatibility helpers and removes the PHPStan suppressions those changes resolve.

Changes:

• Adds output-type annotations and keeps noncharacter detection strictly boolean.
• Deletes the parameterByRef.unusedType baseline and removes two resolved parameterByRef.type errors.
• Adds UTF-8 scanner tests covering ASCII, noncharacters, and ordinary multibyte text.

File	Description
tests/​phpunit/​tests/​compat/​wpScanUtf8.php	Adds scanner tests asserting boolean noncharacter results.
tests/​phpstan/​baselines/​parameterByRef.unusedType.neon	Deletes the resolved baseline.
tests/​phpstan/​baselines/​parameterByRef.type.neon	Removes two resolved boolean-type suppressions.
src/​wp-includes/​compat-utf8.php	Documents output types and replaces bitwise accumulation with boolean logic.
phpstan.neon.dist	Removes the deleted baseline’s include.

_{Review effort: Balanced}

[lancewillett]

@dmsnell could you review the _wp_scan_utf8() changes and associated coverage? This adjusts executable boolean accumulation as well as PHPStan annotations, so I am holding landing for your review. Optional test cleanup: assertTrue() and assertFalse() already check the boolean type, making the preceding assertIsBool() assertions redundant.

_{AI review · gpt-6}

[lancewillett]

@dmsnell following up on my Oct 31 request: could you review the _wp_scan_utf8() changes and their coverage when you have time?

_{AI review · claude-opus-5-5}

[dmsnell]

please verify that this doesn’t break the docs-generation. before we start changing @param declarations, we should ensure that the published docs page isn’t broken.

you can hopefully lean on dmsnell#29 to figure out how to preview the generation.

I see that this is an additional annotation beyond the @param, but it would be ideal to double-check first.

[dmsnell]

this is a misleading title. it would be clearer to show variant cases of multi-byte UTF-8 code points and extended grapheme clusters, which would clarify the behavior of the function.

let’s use a data provider and show interesting cases, and then use mb_strlen( $text, 'UTF-8' ) inside an assertSame() to verify the counts.

this way we can cover two-, three-, and four-byte sequences, spans of invalid bytes (covering the maximal subpart behavior), ZWJ sequences, and grapheme clusters.