Docs: Clarify the weekday range in WP_Locale::get_weekday(). - #14827

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 raulsalvat, westonruter.

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

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.

🤖 Comment by Claude Opus 5.5

Several follow-up changes were made while reviewing the new WP_Locale parameter types. "Allow edits by maintainers" is disabled on this PR, so they could not be pushed to this branch. They are proposed instead as a PR into it: rootzero00#1 (6 commits on top of fefbbea). Merging that PR adds them here.

Changes

1. Clamp the start of the week in get_calendar(). $week_begins was (int) get_option( 'start_of_week' ) with no bounds, so ( $wdcount + $week_begins ) % 7 could be negative or otherwise outside int<0, 6>, leading to an undefined key in get_weekday(). It is now clamp( (int) get_option( 'start_of_week' ), 0, 6 ), using the clamp() polyfill in compat.php.
2. Handle a missing post weekday in the_weekday() and the_weekday_date(). get_post_time() returns false when the post date cannot be parsed. That was passed straight to get_weekday(), where it was coerced to key 0, so the post was silently labeled Sunday. Now nothing is output in that case: the_weekday() returns early, and the_weekday_date() skips the weekday along with $before and $after. The filters still apply.
3. Narrow the get_post_time() return type by date format. The conditional return type now gives a literal union for each format character with a fixed range (w gives '0' through '6', m gives '01' through '12', and so on), mirroring what PHPStan infers for DateTimeInterface::format(). Open-ended numeric formats such as Y give numeric-string. Formats that wp_date() translates when $translate is set (D, l, M, F, a, and A), plus the PHP 8.2+ X and x, remain string. With w narrowed, (int) $weekday_number in the two functions above satisfies int<0, 6> without needing a clamp.
4. Pass the weekday number to get_weekday() as an int in wp_date(). $datetime->format( 'w' ) returns a string from '0' to '6', which worked only through array key coercion.
5. Return false from wp_date() when the timestamp cannot be parsed. is_numeric() accepts values that date_create( '@' . $timestamp ) rejects, such as '1e3', 1e20, ' 5', and '.5'. For those, the next line fataled with Call to a member function setTimezone() on false. Now false is returned, as documented for invalid timestamp input and as already done for non-numeric input. A data-provider test covers the four cases; each fails without the fix.
6. Keep the full month number type for get_month(). r59870 (Core-62824) made get_month() return an empty string for a month number that is not found, so that callers such as single_month_title() can pass unvalidated query var values. Narrowing its parameter to valid month numbers contradicted that and flagged 12 call sites passing zeroise() results, query vars, or database values, so the @phpstan-param was removed from get_month() only. The narrowing is kept on get_weekday(), get_month_genitive(), and get_meridiem(), which have no such fallback (test_get_weekday_undefined_index asserts the warning for an out-of-range weekday).

Upstream PHPStan fix for get_meridiem()

wp_date() passes $datetime->format( 'a' ) and $datetime->format( 'A' ) to get_meridiem(), whose parameter is now 'am'|'pm'|'AM'|'PM'. PHPStan currently infers only non-falsy-string for those formats, even though PHP formats them from hard-coded English values regardless of the locale. This was reported as phpstan/phpstan#15537 and is fixed in phpstan/phpstan-src#6838 (draft), which also covers S, D, l, M, and F. Once that is released and core updates PHPStan, the two remaining get_meridiem() errors go away with no change to core.

PHPStan error breakdown

The 14 files changed here or calling the affected functions were analyzed at three points: the trunk base of this PR (38a613a), the current PR head (fefbbea), and the head with the follow-up commits. Errors were matched by file, identifier, and message, since line numbers shift between versions.

Level 5 (CI)

There are no errors at any of the three points. Relative to trunk, the argument.type baseline loses both of its get_weekday() entries (3 errors):

Level 10

Fixed relative to the PR head: 14 errors

Seven more errors at the PR head are not fixed but go back to their trunk wording, because get_month() again expects int|string: the six mixed arguments from query vars and database rows (general-template.php:1661, 1948, 2381, 2851, and 2863, and media.php:5062) and the zeroise() call inside get_month().

Relative to trunk: 7 fixed, 2 introduced

• Fixed: the 7 method.nonObject errors in wp_date() listed above.
• Introduced: 2 argument.type errors for get_meridiem() at src/wp-includes/functions.php:294 and 297, which Infer literal types for word date format characters phpstan/phpstan-src#6838 resolves.
• Unchanged apart from wording: the zeroise() call in get_month_genitive() now reports int<1, 12>|string given instead of int|string given.

@rootzero00 please able maintainer edits for this PR and others as that will facilitate getting changes into core.