Skip to content

Resolve offsetSet() template types for ArrayAccess offset writes - #6903

Open
westonruter wants to merge 8 commits into
phpstan:2.3.xfrom
westonruter:fix-arrayaccess-offsetset-method-template
Open

westonruter wants to merge 8 commits into
phpstan:2.3.xfrom
westonruter:fix-arrayaccess-offsetset-method-template

Conversation

@westonruter

@westonruter westonruter commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

An offset write $object[$offset] = $value was checked against the parameters of offsetSet() taken from getOnlyVariant(), so method-level template types were never resolved. With an offsetSet() declared like this:

/**
 * @template TOffset of key-of<TArray>
 * @param TOffset $offset
 * @param TArray[TOffset] $value
 */
public function offsetSet(mixed $offset, mixed $value): void;

the accepted offset type stayed the unresolved TOffset, and the accepted value type stayed TArray[TOffset]. As a result, every write was rejected, valid ones included (offsetAssign.dimType and offsetAssign.valueType). An explicit $object->offsetSet($offset, $value) call was already accepted, since a method call resolves the templates from its arguments.

Compound assignments had the same problem on the read side. A plain read $object[$offset] is analysed as a simulated offsetGet() call, so it already resolved @return TArray[TOffset]. But ??=, +=, and .= read the current value through ObjectType::getOffsetValueType(), which also used getOnlyVariant(). For Options<array{name: string, age: int}>, $options['age'] ??= 5 was reported as "does not accept int|string", and $options['age'] += 1 was inferred as an error type.

Changes

  • ObjectType::setOffsetValueType() selects the offsetSet() variant from the written offset and value types, and ObjectType::getOffsetValueType() selects the offsetGet() variant from the offset type, with ParametersAcceptorSelector::selectFromTypes(), as a method call does.
  • When the method has a single variant without template or late-resolvable types (ArrayObject, most collections), that variant is used as is, without resolution. On a file of 6,000 writes and compound assignments to an ArrayObject and a plain ArrayAccess<int, int> class, resolving every access cost about 15% more user CPU time. With this fast path, the difference is about 2% without the turbo extension and about 1% with it, which is within the noise of that measurement (6 interleaved runs each).
  • OffsetAccessValueAssignmentRule checks the value against the written offset (null for an append) instead of mixed, so TArray[TOffset], or a conditional type such as ($offset is null ? int : string), resolves for that key. When the offset itself is rejected, the rule falls back to mixed, since OffsetAccessAssignmentRule already reports that offset. An accepted write costs one setOffsetValueType() call.
  • The native ObjectType in turbo-ext gets the same changes. turbo-ext/tests/type-family.php gains observations on a templated ArrayAccess fixture, an offset-conditional one, and a generic ArrayObject. Against a build of the native ObjectType without these changes, 96 of them differ from the PHP twin. turbo-ext/src/generated/ObjectType.h is regenerated for the new private method.

Left unchanged:

  • ObjectType::hasOffsetValueType() still reads offsetSet() through getOnlyVariant(). For ArrayAccess, it answers only no or maybe, and the bound of the unresolved TOffset (key-of<TArray>) already gives the right "no". Resolving the template gave identical results for unset, isset, ??, compound assignments, and union keys.
  • AssignHandler::collectOffsetSetUsage() also still uses getOnlyVariant(). With unresolvedTemplateArguments enabled, an array-access write already infers the same template arguments as the equivalent explicit offsetSet() call.

Known limitation and a possible follow-up

setOffsetValueType() returns a single ErrorType whether the offset or the value is rejected. So OffsetAccessValueAssignmentRule tells the two apart by probing: it checks the write, then the offset alone, and then the value against a mixed offset when the offset itself is rejected. As a result, when an offset is only partly accepted, a wrong value for its accepted part is not reported separately. For example, with Options<array{name: string, age: int}> and 'age'|'nope' $key, $options[$key] = 'foo' gets only Cannot assign offset 'age'|'nope' … from OffsetAccessAssignmentRule, not also a value error for 'age'. The line is still reported once. Before this change, it got both errors, as did every valid write.

A way to remove the probing would be for ObjectType to expose the accepted offset and value types of the resolved offsetSet() variant. The rule could then check the value against the value type for the accepted part of the offset, with no mixed fallback, and a rejected write would cost one variant resolution instead of up to three. That would add API to ObjectType (and its native twin), so it is left out of this PR. It could be added if wanted.

Tests

The regression fixture starts with the issue's playground snippet verbatim. Further cases follow it: an unknown key, an append, a wrong value for a second key, an array<string, mixed> map, compound assignments, and union keys. tests/PHPStan/Analyser/nsrt/bug-8549.php covers the inferred types of reads and compound assignments. Each new test fails without its source change and passes with it. The full test suite passes with and without the turbo extension loaded, as does turbo-ext/tests/smoke.php. make lint-turbo and make sanitize-turbo were not run locally.

Where this came up

This was found in the WordPress Gutenberg plugin, through WordPress/gutenberg#86110; the code from Gutenberg gets distributed with WordPress core. In WordPress/gutenberg#86088 all PHPStan rule level 5 errors are being addressed, including the ones surfaced by this issue. In the php-stubs/wordpress-stubs package, WP_REST_Request is declared @template T of array = array<string, mixed>, and its offsetSet() and set_param() both use the TOffset of key-of<T> / T[TOffset] pattern above. Gutenberg's attachments controller builds a request with array access:

$response_request = new WP_REST_Request( WP_REST_Server::READABLE, rest_get_route_for_post( $attachment_id ) );
$response_request['context'] = 'edit';
if ( isset( $request['_fields'] ) ) {
	$response_request['_fields'] = $request['_fields'];
}

PHPStan reported both writes, although T is array<string, mixed> and both are valid:

Cannot assign offset 'context' to WP_REST_Request<array<string, mixed>>.  (offsetAssign.dimType)
WP_REST_Request<array<string, mixed>> does not accept string.             (offsetAssign.valueType)
Cannot assign offset '_fields' to WP_REST_Request<array<string, mixed>>.  (offsetAssign.dimType)

The errors had been suppressed in Gutenberg's PHPStan baseline. That PR removes the baseline entries by rewriting the writes as $response_request->set_param( 'context', 'edit' ) and $response_request->set_param( '_fields', $request['_fields'] ). The workaround passes because set_param() is analysed as a method call, which resolves TOffset from its argument. Only the array-access path skipped that step. Array access on WP_REST_Request is idiomatic across WordPress core and plugins, though, so rewriting call sites to avoid a false positive is not a general fix.

With this change, the original array-access code passes as it is, so the baseline entries can be dropped without the rewrite. Array-access writes also get the same per-key checking a set_param() call gets. With WP_REST_Request<array{context: 'view'|'edit'|'embed', _fields?: string}>, $request['context'] = 'edit' is accepted, while $request['context'] = 'nonsense', $request['_fields'] = 1, and $request['nope'] = 'x' are reported. Before this change, all of these writes were reported, valid and invalid alike, so the errors carried no signal.

Closes phpstan/phpstan#8549

🤖 Generated with Claude Code using Claude Opus 5.5 · high effort

Disclosure: I read over the generated description and the generated code, but I won't pretend I fully understand everything. I did multiple high effort code reviews with Opus 5.5 as well.

An offset write `$object[$offset] = $value` was checked against the
parameters of offsetSet() taken from getOnlyVariant(), so method-level
template types were never resolved. With an offsetSet() declared as

    @template TOffset of key-of<T>
    @PARAM TOffset $offset
    @PARAM T[TOffset] $value

the accepted offset type stayed the unresolved TOffset and the accepted
value type T[TOffset], so every write was rejected, including valid
ones. The explicit $object->offsetSet($offset, $value) call was already
accepted, since a method call resolves the templates from its arguments.

ObjectType::setOffsetValueType() now selects the offsetSet() variant
from the written offset and value types, as a call does.
OffsetAccessValueAssignmentRule passes the written offset type, not
mixed, so T[TOffset] resolves to the value type for that key. When the
offset itself is rejected, the rule falls back to mixed, since
OffsetAccessAssignmentRule already reports that offset.

The native ObjectType in turbo-ext gets the same change.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Code-Session-Id: 781e7324-e13c-4956-a86a-9047e742d5b9
westonruter and others added 7 commits November 1, 2026 22:46
A plain read `$object[$offset]` is analysed as a simulated offsetGet()
call, so a method-level `@template TOffset of key-of<T>` with
`@return T[TOffset]` already resolved for it. Compound assignments
(`??=`, `+=`, `.=`) read the current value through
ObjectType::getOffsetValueType() instead, which took offsetGet()'s
return type from getOnlyVariant() with TOffset unresolved. For
`Options<array{name: string, age: int}>`, `$options['age'] ??= 5` read
the value as `int|string` and reported it as not accepted, and
`$options['age'] += 1` was inferred as an error type.

getOffsetValueType() now selects the offsetGet() variant from the
offset type, as setOffsetValueType() does for offsetSet().

In the native ObjectType, the getMethod() lookup and the variant
selection move into helpers that the offsetGet() and offsetSet() paths
share.

Co-Authored-By: Claude Opus 5.5 (high effort) <noreply@anthropic.com>
Claude-Code-Session-Id: 781e7324-e13c-4956-a86a-9047e742d5b9
Resolving the offsetGet()/offsetSet() variant against the offset and
value types runs on every ArrayAccess read in a compound assignment and
on every ArrayAccess write. Most ArrayAccess classes (ArrayObject,
collections, option bags) declare no method-level template types, so
the resolution only allocated a resolved variant equal to the original.

When the method has a single variant without template or late-resolvable
types, it is now used as is, as before. On a file of 6,000 writes and
compound assignments to an ArrayObject and a plain ArrayAccess<int, int>
class, analysis took about 15% more user CPU time than before the
resolution was added. It now takes about 2% more, which is within the
noise of that measurement.

The native ObjectType gets the same fast path.

Co-Authored-By: Claude Opus 5.5 (high effort) <noreply@anthropic.com>
Claude-Code-Session-Id: 781e7324-e13c-4956-a86a-9047e742d5b9
OffsetAccessValueAssignmentRule probed every write with
setOffsetValueType($dimType, mixed) to decide which offset type to check
the value against, and then called setOffsetValueType() again with the
value. It now checks the write with the written offset first, and only
if that is rejected does it probe the offset alone, falling back to a
mixed offset when the offset itself is rejected. The outcome is the
same, but an accepted write costs one setOffsetValueType() call instead
of two.

Co-Authored-By: Claude Opus 5.5 (high effort) <noreply@anthropic.com>
Claude-Code-Session-Id: 781e7324-e13c-4956-a86a-9047e742d5b9
With a union offset such as 'name'|'age', TOffset resolves to the union
and T[TOffset] to the union of the value types for those keys, so a value
of either key's type is accepted and a value of neither is reported. An
offset that is only partly known, such as 'name'|'nope', is reported once
by OffsetAccessAssignmentRule, and OffsetAccessValueAssignmentRule does
not report its value as well.

Co-Authored-By: Claude Opus 5.5 (high effort) <noreply@anthropic.com>
Claude-Code-Session-Id: 781e7324-e13c-4956-a86a-9047e742d5b9
For an append (`$object[] = $value`), OffsetAccessValueAssignmentRule
checked the value against a mixed offset, while the write itself goes
through ObjectType::setOffsetValueType() with a null offset. Since
offsetSet()'s parameters are now resolved against the written offset,
a value type depending on the offset, such as
`@param ($offset is null ? int : string) $value`, resolved to
`int|string` for the check and `$object[] = 'str'` was no longer
reported.

The rule now passes the append's null offset on to
setOffsetValueType(), and falls back to a mixed offset only when the
append itself is rejected, as for any other rejected offset.

Co-Authored-By: Claude Opus 5.5 (high effort) <noreply@anthropic.com>
Claude-Code-Session-Id: 781e7324-e13c-4956-a86a-9047e742d5b9
The native ObjectType now selects the offsetGet()/offsetSet() variant
from the offset and value types, but type-family.php only probed the
offset operations on plain ObjectType(ArrayAccess) and ArrayObject,
which never reach the template resolution.

A fixture adds an ArrayAccess class whose offsetGet() and offsetSet()
declare `@template TOffset of key-of<TArray>`, and one whose offsetSet()
value type is conditional on the offset. getOffsetValueType(),
hasOffsetValueType() and setOffsetValueType(), appends included, are
observed on them with known, unknown and union keys, alongside a generic
ArrayObject for the path without anything to resolve. Against a build of
the native ObjectType without the variant selection, 96 of these
observations differ from the PHP twin.

Co-Authored-By: Claude Opus 5.5 (high effort) <noreply@anthropic.com>
Claude-Code-Session-Id: 781e7324-e13c-4956-a86a-9047e742d5b9
The private ObjectType::selectArrayAccessVariant() added for the
ArrayAccess fast path is part of the declarations that
turbo-ext/bin/generate-declarations.php derives from the PHP class, so
turbo-ext/src/generated/ObjectType.h was stale and
turbo-ext/bin/side-by-side.php reported it.

Co-Authored-By: Claude Opus 5.5 (high effort) <noreply@anthropic.com>
Claude-Code-Session-Id: 781e7324-e13c-4956-a86a-9047e742d5b9
@westonruter
westonruter marked this pull request as ready for review November 2, 2026 17:13
@phpstan-bot

Copy link
Copy Markdown
Collaborator

This pull request has been marked as ready for review.

westonruter added a commit to WordPress/gutenberg that referenced this pull request Nov 11, 2026
* PHPStan: Update to 2.3.5

The analysis reports no errors with this release, and no baseline entry
goes stale, so the baseline is unchanged. The other PHPStan packages,
phpstan-phpunit (2.1.1), extension-installer (1.4.3), and
szepeviktor/phpstan-wordpress (2.0.4), are already at their latest
versions.

The `WP_REST_Request` offset ignores stay, since the PHPStan fix they
wait on (phpstan/phpstan-src#6903) is not yet merged.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Recommend `--fix` for out-of-date baseline entries

PHPStan 2.3.5 can fix stale ignores itself: `--fix` lowers a baseline
count that is now too high, removes an entry that matches nothing, and
removes an `@phpstan-ignore` comment that no longer ignores anything.
Verified on `tools/phpstan/baseline.neon`: an inflated count was lowered
back to its real value, leaving the rest of the file as it was.

That suits Gutenberg better than regenerating. `composer
phpstan:baselines` is PHPStan's `--generate-baseline`, which records
every error the run reports, so the job summary had to warn against
regenerating while other errors were still reported. `--fix` never adds
an entry, so it is safe to run then too.

The coding guidelines and the job summary now recommend `--fix`, and
explain that it has to be a run over all the paths, since PHPStan
reports no out-of-date entries when it analyzes only some files.

`report.ts` also reads the `fixable` flag that PHPStan's JSON report now
carries: an annotation of a fixable error says how to fix it, and the
job summary marks the error with 🔧, as PHPStan's table output does.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Add `composer phpstan:fix` to update the baseline

Removing an out-of-date baseline entry meant running
`composer phpstan -- --fix`. Leaving out the `--` makes Composer discard
the flag silently, so the analysis just reports the stale entries again.

`composer phpstan:fix` (and `npm run typecheck:php:fix`) chains two
steps, the second run only when the first succeeds:

* PHPStan with `--fix`, which lowers or removes the stale entries.
* The analysis once more, since PHPStan's `--fix` reports only what it
  fixed, and succeeds even when other errors remain. It reuses the
  result cache, so it is quick.

Both analyses use `phpstan.neon.dist`, whatever a local `phpstan.neon`
says. A configuration at another rule level can report a baselined error
with a different message, and `--fix` then removes entries the default
configuration still needs.

When nothing is fixable, PHPStan exits with 1 and stops the chain, which
the coding guidelines note.

The coding guidelines, the README, and the CI annotation and job summary
now point to the new scripts.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Point the baseline comment to `composer phpstan:fix`

The comment above the baseline include in `phpstan.neon.dist` still
recommended `composer phpstan -- --fix`.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

---------

Co-authored-by: westonruter <westonruter@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>
peterwilsoncc pushed a commit to peterwilsoncc/gutenberg-build that referenced this pull request Nov 11, 2026
* PHPStan: Update to 2.3.5

The analysis reports no errors with this release, and no baseline entry
goes stale, so the baseline is unchanged. The other PHPStan packages,
phpstan-phpunit (2.1.1), extension-installer (1.4.3), and
szepeviktor/phpstan-wordpress (2.0.4), are already at their latest
versions.

The `WP_REST_Request` offset ignores stay, since the PHPStan fix they
wait on (phpstan/phpstan-src#6903) is not yet merged.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Recommend `--fix` for out-of-date baseline entries

PHPStan 2.3.5 can fix stale ignores itself: `--fix` lowers a baseline
count that is now too high, removes an entry that matches nothing, and
removes an `@phpstan-ignore` comment that no longer ignores anything.
Verified on `tools/phpstan/baseline.neon`: an inflated count was lowered
back to its real value, leaving the rest of the file as it was.

That suits Gutenberg better than regenerating. `composer
phpstan:baselines` is PHPStan's `--generate-baseline`, which records
every error the run reports, so the job summary had to warn against
regenerating while other errors were still reported. `--fix` never adds
an entry, so it is safe to run then too.

The coding guidelines and the job summary now recommend `--fix`, and
explain that it has to be a run over all the paths, since PHPStan
reports no out-of-date entries when it analyzes only some files.

`report.ts` also reads the `fixable` flag that PHPStan's JSON report now
carries: an annotation of a fixable error says how to fix it, and the
job summary marks the error with 🔧, as PHPStan's table output does.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Add `composer phpstan:fix` to update the baseline

Removing an out-of-date baseline entry meant running
`composer phpstan -- --fix`. Leaving out the `--` makes Composer discard
the flag silently, so the analysis just reports the stale entries again.

`composer phpstan:fix` (and `npm run typecheck:php:fix`) chains two
steps, the second run only when the first succeeds:

* PHPStan with `--fix`, which lowers or removes the stale entries.
* The analysis once more, since PHPStan's `--fix` reports only what it
  fixed, and succeeds even when other errors remain. It reuses the
  result cache, so it is quick.

Both analyses use `phpstan.neon.dist`, whatever a local `phpstan.neon`
says. A configuration at another rule level can report a baselined error
with a different message, and `--fix` then removes entries the default
configuration still needs.

When nothing is fixable, PHPStan exits with 1 and stops the chain, which
the coding guidelines note.

The coding guidelines, the README, and the CI annotation and job summary
now point to the new scripts.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Point the baseline comment to `composer phpstan:fix`

The comment above the baseline include in `phpstan.neon.dist` still
recommended `composer phpstan -- --fix`.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

---------

Co-authored-by: westonruter <westonruter@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>

Source: WordPress/gutenberg@2fc1623
westonruter added a commit to WordPress/gutenberg that referenced this pull request Nov 12, 2026
* PHPStan: Update to 2.3.5

The analysis reports no errors with this release, and no baseline entry
goes stale, so the baseline is unchanged. The other PHPStan packages,
phpstan-phpunit (2.1.1), extension-installer (1.4.3), and
szepeviktor/phpstan-wordpress (2.0.4), are already at their latest
versions.

The `WP_REST_Request` offset ignores stay, since the PHPStan fix they
wait on (phpstan/phpstan-src#6903) is not yet merged.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Recommend `--fix` for out-of-date baseline entries

PHPStan 2.3.5 can fix stale ignores itself: `--fix` lowers a baseline
count that is now too high, removes an entry that matches nothing, and
removes an `@phpstan-ignore` comment that no longer ignores anything.
Verified on `tools/phpstan/baseline.neon`: an inflated count was lowered
back to its real value, leaving the rest of the file as it was.

That suits Gutenberg better than regenerating. `composer
phpstan:baselines` is PHPStan's `--generate-baseline`, which records
every error the run reports, so the job summary had to warn against
regenerating while other errors were still reported. `--fix` never adds
an entry, so it is safe to run then too.

The coding guidelines and the job summary now recommend `--fix`, and
explain that it has to be a run over all the paths, since PHPStan
reports no out-of-date entries when it analyzes only some files.

`report.ts` also reads the `fixable` flag that PHPStan's JSON report now
carries: an annotation of a fixable error says how to fix it, and the
job summary marks the error with 🔧, as PHPStan's table output does.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Introduce phpstan-strict-rules

As WordPress core now does, this adds phpstan/phpstan-strict-rules as a
development dependency, and enables by default the rules the code
already complies with, so that they are kept to:

* Disallow loose comparisons.
* Disallow the backtick operator.
* Disallow implicit array creation.
* Disallow short ternaries.
* Disallow `$this` in closures.
* Require inherited method names to match in case.
* Require switch case types to match the condition.
* Disallow calling a constructor as a method.

Each was measured with every strict rule enabled over
`phpstan.neon.dist`, and reports no errors.

The rules are registered individually rather than by including the
package's `rules.neon`, because that file also makes several PHPStan
parameters stricter even when its rules are disabled. Unlike core,
Gutenberg uses phpstan/extension-installer, which would include
`rules.neon` automatically, so composer.json tells it to ignore the
package. The loose comparison rule takes an argument, so it is
registered as a service, with the value `rules.neon` gives it.

The arithmetic operand rules also report no errors, but are left out:
they need an `OperatorRuleHelper` service, and registering one would
leave two once a local config includes `rules.neon`, which PHPStan then
fails to load. The useless cast rule has only two errors, but one of
them is a `(int)` cast that WPCS counts as escaping a `printf()`
argument.

The coding guidelines document how to opt into the other rules with a
local `phpstan.neon`, which was tested to load and report only the rules
it enables, along with the errors from the stricter parameters. The
`phpstan.neon.dist` header now says to include the file rather than copy
it, as core's does.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Legacy Widget: Validate the encoded instance before decoding it

The `instance` attribute is only validated as an object, so its nested
`encoded` and `hash` values can be of any type. A non-string `encoded`
made `base64_decode()` throw a TypeError on PHP 8. Both are now required
to be strings, and the block renders nothing otherwise, as it does for a
hash that does not match. That also makes the `(string)` cast of the
hash unnecessary.

Without its `$strict` argument, `base64_decode()` silently skips
characters outside the base64 alphabet, so a malformed `encoded` value
still decoded to some bytes, which then failed the hash check. In strict
mode it returns false instead, which is now checked explicitly, so that
false is never passed to `wp_hash()`. A value the editor encoded decodes
exactly as before.

This is the one call in the analyzed code that phpstan-strict-rules'
`StrictFunctionCallsRule` reports, which is enabled next.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Enable the strict function calls rule

`StrictFunctionCallsRule` requires the strict argument of `in_array()`,
`array_search()`, `array_keys()`, and `base64_decode()`. For the first
three it is also enforced by the WordPress.PHP.StrictInArray sniff of
the WordPress Coding Standards, and with the legacy widget's
`base64_decode()` call now strict, the code complies with it.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Docs: Give the PHPStan strict rules their own subsection

Trunk split the PHPStan section of the coding guidelines into
subsections, so the strict rules paragraph, written as part of the
single paragraph before, now follows the local configuration example.
It gets a "Strict rules" subsection of its own, and links
`phpstan.neon.dist` as the other subsections do.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Add `composer phpstan:fix` to update the baseline

Removing an out-of-date baseline entry meant running
`composer phpstan -- --fix`. Leaving out the `--` makes Composer discard
the flag silently, so the analysis just reports the stale entries again.

`composer phpstan:fix` (and `npm run typecheck:php:fix`) chains two
steps, the second run only when the first succeeds:

* PHPStan with `--fix`, which lowers or removes the stale entries.
* The analysis once more, since PHPStan's `--fix` reports only what it
  fixed, and succeeds even when other errors remain. It reuses the
  result cache, so it is quick.

Both analyses use `phpstan.neon.dist`, whatever a local `phpstan.neon`
says. A configuration at another rule level can report a baselined error
with a different message, and `--fix` then removes entries the default
configuration still needs.

When nothing is fixable, PHPStan exits with 1 and stops the chain, which
the coding guidelines note.

The coding guidelines, the README, and the CI annotation and job summary
now point to the new scripts.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Point the baseline comment to `composer phpstan:fix`

The comment above the baseline include in `phpstan.neon.dist` still
recommended `composer phpstan -- --fix`.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Widgets: Add a changelog entry for the legacy widget instance checks

The render callback of the Legacy Widget block now renders nothing for an
`instance` attribute whose `encoded` or `hash` value is not a string,
where `base64_decode()` or `hash_equals()` previously caused a fatal
error. It also decodes in strict mode, rejecting characters outside the
base64 alphabet. Both change what consumers of the package see for
malformed attributes, so they get a Bug Fixes entry.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Widgets: Say the legacy widget `TypeError` is specific to PHP 8

On PHP 7.4, `base64_decode()` and `hash_equals()` only emit a warning for
a value of the wrong type, and the hash check then fails, so the block
already rendered nothing there. The `TypeError` that crashed rendering
is thrown only on PHP 8, which the changelog entry now says.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Widgets: Limit the legacy widget `TypeError` entry to an array `encoded`

Only an array `encoded` value made `base64_decode()` throw a `TypeError`.
The `hash` value was already cast to a string before `hash_equals()`, so
a non-string `hash` caused at most an "Array to string conversion"
warning, and the block rendered nothing. The changelog entry claimed both
values could cause the error.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Widgets: Drop strict base64 decoding from the legacy widget changelog

Decoding `encoded` in strict mode changes nothing a consumer can see.
Without it, `base64_decode()` skips characters outside the base64
alphabet, so a value with stray characters decodes to the same bytes as
the clean value, passes or fails the hash check just as that value would,
and renders the same instance. The `true` argument is there for the
`strictFunctionCalls` rule, so the entry keeps only the `TypeError` fix.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Widgets: Restore strict base64 decoding to the legacy widget changelog

Decoding `encoded` in strict mode is visible to consumers after all.
Without it, `base64_decode()` skipped characters outside the base64
alphabet, so a value with stray characters decoded to the clean bytes,
passed the hash check, and the widget rendered. Strict mode now returns
false for such a value, which renders nothing before the hash is checked.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

---------

Co-authored-by: westonruter <westonruter@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: dknauss <dpknauss@git.wordpress.org>
peterwilsoncc pushed a commit to peterwilsoncc/gutenberg-build that referenced this pull request Nov 12, 2026
* PHPStan: Update to 2.3.5

The analysis reports no errors with this release, and no baseline entry
goes stale, so the baseline is unchanged. The other PHPStan packages,
phpstan-phpunit (2.1.1), extension-installer (1.4.3), and
szepeviktor/phpstan-wordpress (2.0.4), are already at their latest
versions.

The `WP_REST_Request` offset ignores stay, since the PHPStan fix they
wait on (phpstan/phpstan-src#6903) is not yet merged.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Recommend `--fix` for out-of-date baseline entries

PHPStan 2.3.5 can fix stale ignores itself: `--fix` lowers a baseline
count that is now too high, removes an entry that matches nothing, and
removes an `@phpstan-ignore` comment that no longer ignores anything.
Verified on `tools/phpstan/baseline.neon`: an inflated count was lowered
back to its real value, leaving the rest of the file as it was.

That suits Gutenberg better than regenerating. `composer
phpstan:baselines` is PHPStan's `--generate-baseline`, which records
every error the run reports, so the job summary had to warn against
regenerating while other errors were still reported. `--fix` never adds
an entry, so it is safe to run then too.

The coding guidelines and the job summary now recommend `--fix`, and
explain that it has to be a run over all the paths, since PHPStan
reports no out-of-date entries when it analyzes only some files.

`report.ts` also reads the `fixable` flag that PHPStan's JSON report now
carries: an annotation of a fixable error says how to fix it, and the
job summary marks the error with 🔧, as PHPStan's table output does.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Introduce phpstan-strict-rules

As WordPress core now does, this adds phpstan/phpstan-strict-rules as a
development dependency, and enables by default the rules the code
already complies with, so that they are kept to:

* Disallow loose comparisons.
* Disallow the backtick operator.
* Disallow implicit array creation.
* Disallow short ternaries.
* Disallow `$this` in closures.
* Require inherited method names to match in case.
* Require switch case types to match the condition.
* Disallow calling a constructor as a method.

Each was measured with every strict rule enabled over
`phpstan.neon.dist`, and reports no errors.

The rules are registered individually rather than by including the
package's `rules.neon`, because that file also makes several PHPStan
parameters stricter even when its rules are disabled. Unlike core,
Gutenberg uses phpstan/extension-installer, which would include
`rules.neon` automatically, so composer.json tells it to ignore the
package. The loose comparison rule takes an argument, so it is
registered as a service, with the value `rules.neon` gives it.

The arithmetic operand rules also report no errors, but are left out:
they need an `OperatorRuleHelper` service, and registering one would
leave two once a local config includes `rules.neon`, which PHPStan then
fails to load. The useless cast rule has only two errors, but one of
them is a `(int)` cast that WPCS counts as escaping a `printf()`
argument.

The coding guidelines document how to opt into the other rules with a
local `phpstan.neon`, which was tested to load and report only the rules
it enables, along with the errors from the stricter parameters. The
`phpstan.neon.dist` header now says to include the file rather than copy
it, as core's does.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Legacy Widget: Validate the encoded instance before decoding it

The `instance` attribute is only validated as an object, so its nested
`encoded` and `hash` values can be of any type. A non-string `encoded`
made `base64_decode()` throw a TypeError on PHP 8. Both are now required
to be strings, and the block renders nothing otherwise, as it does for a
hash that does not match. That also makes the `(string)` cast of the
hash unnecessary.

Without its `$strict` argument, `base64_decode()` silently skips
characters outside the base64 alphabet, so a malformed `encoded` value
still decoded to some bytes, which then failed the hash check. In strict
mode it returns false instead, which is now checked explicitly, so that
false is never passed to `wp_hash()`. A value the editor encoded decodes
exactly as before.

This is the one call in the analyzed code that phpstan-strict-rules'
`StrictFunctionCallsRule` reports, which is enabled next.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Enable the strict function calls rule

`StrictFunctionCallsRule` requires the strict argument of `in_array()`,
`array_search()`, `array_keys()`, and `base64_decode()`. For the first
three it is also enforced by the WordPress.PHP.StrictInArray sniff of
the WordPress Coding Standards, and with the legacy widget's
`base64_decode()` call now strict, the code complies with it.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Docs: Give the PHPStan strict rules their own subsection

Trunk split the PHPStan section of the coding guidelines into
subsections, so the strict rules paragraph, written as part of the
single paragraph before, now follows the local configuration example.
It gets a "Strict rules" subsection of its own, and links
`phpstan.neon.dist` as the other subsections do.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Add `composer phpstan:fix` to update the baseline

Removing an out-of-date baseline entry meant running
`composer phpstan -- --fix`. Leaving out the `--` makes Composer discard
the flag silently, so the analysis just reports the stale entries again.

`composer phpstan:fix` (and `npm run typecheck:php:fix`) chains two
steps, the second run only when the first succeeds:

* PHPStan with `--fix`, which lowers or removes the stale entries.
* The analysis once more, since PHPStan's `--fix` reports only what it
  fixed, and succeeds even when other errors remain. It reuses the
  result cache, so it is quick.

Both analyses use `phpstan.neon.dist`, whatever a local `phpstan.neon`
says. A configuration at another rule level can report a baselined error
with a different message, and `--fix` then removes entries the default
configuration still needs.

When nothing is fixable, PHPStan exits with 1 and stops the chain, which
the coding guidelines note.

The coding guidelines, the README, and the CI annotation and job summary
now point to the new scripts.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* PHPStan: Point the baseline comment to `composer phpstan:fix`

The comment above the baseline include in `phpstan.neon.dist` still
recommended `composer phpstan -- --fix`.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Widgets: Add a changelog entry for the legacy widget instance checks

The render callback of the Legacy Widget block now renders nothing for an
`instance` attribute whose `encoded` or `hash` value is not a string,
where `base64_decode()` or `hash_equals()` previously caused a fatal
error. It also decodes in strict mode, rejecting characters outside the
base64 alphabet. Both change what consumers of the package see for
malformed attributes, so they get a Bug Fixes entry.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Widgets: Say the legacy widget `TypeError` is specific to PHP 8

On PHP 7.4, `base64_decode()` and `hash_equals()` only emit a warning for
a value of the wrong type, and the hash check then fails, so the block
already rendered nothing there. The `TypeError` that crashed rendering
is thrown only on PHP 8, which the changelog entry now says.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Widgets: Limit the legacy widget `TypeError` entry to an array `encoded`

Only an array `encoded` value made `base64_decode()` throw a `TypeError`.
The `hash` value was already cast to a string before `hash_equals()`, so
a non-string `hash` caused at most an "Array to string conversion"
warning, and the block rendered nothing. The changelog entry claimed both
values could cause the error.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Widgets: Drop strict base64 decoding from the legacy widget changelog

Decoding `encoded` in strict mode changes nothing a consumer can see.
Without it, `base64_decode()` skips characters outside the base64
alphabet, so a value with stray characters decodes to the same bytes as
the clean value, passes or fails the hash check just as that value would,
and renders the same instance. The `true` argument is there for the
`strictFunctionCalls` rule, so the entry keeps only the `TypeError` fix.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

* Widgets: Restore strict base64 decoding to the legacy widget changelog

Decoding `encoded` in strict mode is visible to consumers after all.
Without it, `base64_decode()` skipped characters outside the base64
alphabet, so a value with stray characters decoded to the clean bytes,
passed the hash check, and the widget rendered. Strict mode now returns
false for such a value, which renders nothing before the hash is checked.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>

---------

Co-authored-by: westonruter <westonruter@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: dknauss <dpknauss@git.wordpress.org>

Source: WordPress/gutenberg@33cad93
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support for array shape for ArrayAccess classes not working.

2 participants