Skip to content

PHPStan: Introduce phpstan-strict-rules - #86460

Merged
westonruter merged 18 commits into
trunkfrom
add/phpstan-strict-rules
Nov 12, 2026
Merged

westonruter merged 18 commits into
trunkfrom
add/phpstan-strict-rules

Conversation

@westonruter

@westonruter westonruter commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

What?

Follow up to #86333, which this is stacked on. The WordPress core counterpart is WordPress/wordpress-develop#15399, committed in r65265.

Adds phpstan-strict-rules as a development dependency, and enables by default the rules that the code already complies with, as WordPress core now does.

Why?

These rules already pass, so enabling them keeps new code from regressing on them. Several also back up rules of the WordPress Coding Standards: the loose comparison rule backs Universal.Operators.StrictComparisons, the short ternary rule Universal.Operators.DisallowShortTernary, the backtick rule Generic.PHP.BacktickOperator, and the strict function calls rule WordPress.PHP.StrictInArray. The rules that are not enabled can be tried in a local phpstan.neon to work toward complying with them.

How?

Each rule group was measured with every strict rule enabled over phpstan.neon.dist. These are enabled, and report no errors:

  • Disallow loose comparisons (disallowedLooseComparison).
  • Disallow the backtick operator (disallowedBacktick).
  • Disallow implicit array creation (disallowedImplicitArrayCreation).
  • Disallow short ternaries (disallowedShortTernary).
  • Disallow $this in closures (closureUsesThis).
  • Require inherited method names to match in case (matchingInheritedMethodNames).
  • Require switch case types to match the condition (switchConditionsMatchingType).
  • Disallow calling a constructor as a method (illegalConstructorMethodCall).
  • Require the strict argument of in_array(), array_search(), array_keys(), and base64_decode() (strictFunctionCalls). Its one error was the Legacy Widget block's base64_decode() call, which now decodes in strict mode. The block now also requires the encoded and hash values of its instance attribute to be strings, rendering nothing otherwise, since a non-string encoded made base64_decode() throw a TypeError on PHP 8. A value the editor encoded decodes as before.

The rules are registered individually in phpstan.neon.dist, rather than by including the package's rules.neon, because that file also makes several PHPStan parameters stricter, such as checkDynamicProperties and reportMaybesInMethodSignatures, 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 coding guidelines document how to opt into the other rules with a local phpstan.neon. That example was tested to load and report only the rules it enables, along with the errors from the stricter parameters.

Follow-up candidates

These were evaluated and left for later:

  • numericOperandsInArithmeticOperators reports no errors, and catches arithmetic on non-numeric values that level 5 lets through. Its rules need an OperatorRuleHelper service, which rules.neon registers. Registering one in phpstan.neon.dist would leave two once a local config includes rules.neon, and PHPStan then fails to load the configuration with "Multiple services of type PHPStan\Rules\Operators\OperatorRuleHelper found". It can be enabled by registering a helper with autowired: false and the ten rules as services passed that helper explicitly, so that the one from rules.neon stays the only autowired one.
  • dynamicCallOnStaticMethod has three errors, all $this->process_blocks_custom_css() calls to a public static method in WP_Theme_JSON_Gutenberg, which static:: fixes. Core's WP_Theme_JSON has the same three calls, so they are best fixed in core as well, and the rule enabled once the class is synced.

These are not worth enabling for now:

Rule Errors Reason
requireParentConstructorCall 1 WP_Icons_Registry_Gutenberg::__construct() skips the parent constructor on purpose, as its docblock explains.
overwriteVariablesWithLoop 1 Two consecutive foreach ( … as &$node ) loops in WP_Theme_JSON_Gutenberg, which is safe since both are by reference.
uselessCast 2 One is an (int) cast of a printf() argument that WPCS counts as escaping it.
strictArrayFilter 6 array_filter() without a callback is idiomatic, and the calls are in package PHP that core also ships.
noVariableVariables 5 Variable property access, such as $post->$field, is a legitimate pattern here.
booleansInConditions about 300 Too many to address in one change.
disallowedEmpty 812 empty() is idiomatic in WordPress, and WPCS does not discourage it.

Testing Instructions

  1. Run composer update, then npm run build and composer phpstan. No errors are reported.
  2. Add a loose comparison such as if ( $a == 'x' ) to a file in lib/, and run composer phpstan again. It is reported as equal.notAllowed.
  3. Create a phpstan.neon with the example from the coding guidelines, and run composer phpstan. The configuration loads, and only the opted-in rules, plus the stricter parameters of rules.neon, report errors.
  4. For the Legacy Widget block, add a legacy widget, such as a Text widget, in the widgets editor or a post, save, and check that it still renders on the front end.

Use of AI Tools

Written with Claude Code using Claude Opus 5.5 (medium effort): measuring which strict rules the code complies with, testing the configuration and the local opt-in example, and writing the configuration, documentation, and Legacy Widget changes, all reviewed by me.

westonruter and others added 5 commits November 4, 2026 14:59
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
`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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
@westonruter westonruter added the [Type] Build Tooling Issues or PRs related to build tooling label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground Preview in Storybook

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

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

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.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric b420a40 trunk % Change
timeToFirstByte 56.45 ms +6.29% -3.54% 56.6 ms +5.92% -3.09% -0.27%
largestContentfulPaint 92 ms +4.35% -8.7% 88 ms +4.55% -4.55% 4.55%
lcpMinusTtfb 32.35 ms +17.16% -8.19% 29.7 ms +12.96% -2.86% 8.92%
wpBeforeTemplate 29.69 ms +9.2% -1.62% 29.95 ms +9.82% -2% -0.87%
wpTemplate 22.68 ms +3.4% -4.63% 21.92 ms +8.85% -2.92% 3.47%
wpTotal 52.61 ms +6.5% -3.25% 52.8 ms +3.64% -3.56% -0.36%
wpMemoryUsage 7.72 MB +0% -0% 7.68 MB +0% -0% 0.43%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric b420a40 trunk % Change
timeToFirstByte 48.2 ms +6.74% -3.22% 48.1 ms +6.34% -3.85% 0.21%
largestContentfulPaint 84 ms +4.76% -0% 84 ms +2.38% -4.76% 0%
lcpMinusTtfb 36.7 ms +4.36% -6.13% 34.35 ms +5.82% -1.75% 6.84%
wpBeforeTemplate 27.17 ms +10.16% -1.66% 26.87 ms +11.83% -1.64% 1.12%
wpTemplate 17.14 ms +6.3% -4.2% 16.88 ms +5.45% -1.9% 1.54%
wpTotal 44.62 ms +7.17% -2.24% 44.93 ms +7.06% -4.32% -0.69%
wpMemoryUsage 6.41 MB +0% -0% 6.37 MB +0% -0% 0.53%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric b420a40 trunk % Change
mediaProcessingJpeg 407.87 ms +0.7% -1.04% 400.39 ms +0.64% -0.14% 1.87%
mediaProcessingAvif 6130.82 ms +0.23% -0.37% 6161.78 ms +0.05% -0.3% -0.5%
mediaProcessingJpegToAvif 4239.82 ms +0.24% -0.25% 4244.55 ms +0.32% -0.56% -0.11%

media-upload

Metric b420a40 trunk % Change
jpegUploadProcessing 1990.06 ms +3.4% -1.19% 1530.92 ms +30.31% -1.81% 29.99%
pngUploadProcessing 277.51 ms +11.66% -1.19% 284.67 ms +0.91% -1.88% -2.52%
largeJpegUploadProcessing 1965.96 ms +1.01% -21.58% 1753.22 ms +14.22% -13.3% 12.13%
multipleImageUploadProcessing 2071.31 ms +1.16% -0.23% 2092 ms +1.98% -2.08% -0.99%

post-editor

Metric b420a40 trunk % Change
serverResponse 269.11 ms +3.15% -9.2% 252.03 ms +8.18% -6.13% 6.78%
firstPaint 290.17 ms +4.61% -8.49% 267.79 ms +9.47% -4.39% 8.36%
domContentLoaded 534.22 ms +2.26% -0.91% 512.42 ms +2.27% -0.3% 4.25%
loaded 534.97 ms +2.27% -0.9% 513.07 ms +2.27% -0.3% 4.27%
firstContentfulPaint 304.81 ms +3.32% -0.85% 298.81 ms +2.4% -1.89% 2.01%
firstBlock 1421.17 ms +1.69% -1.35% 1387.51 ms +0.93% -2.45% 2.43%
type 12.93 ms +9.13% -7.81% 12.08 ms +3.73% -9.19% 7.04%
typeWithoutInspector 12.78 ms +3.52% -11.89% 12.98 ms +4.01% -9.78% -1.54%
typeWithTopToolbar 16.87 ms +3.85% -5.28% 16.18 ms +6.43% -7.35% 4.26%
typeContainer 6.28 ms +9.87% -11.31% 6.23 ms +9.31% -9.79% 0.8%
focus 81.11 ms +8.03% -3.39% 74.87 ms +4.53% -6.14% 8.33%
firstFocus 176.51 ms +0% -0% 162.33 ms +0% -0% 8.74%
selectAll 243.75 ms +1.61% -0.25% 266.7 ms +4.55% -1.18% -8.61%
undo 20.8 ms +8.61% -5.34% 23.4 ms +7.95% -7.09% -11.11%
listViewOpen 48.78 ms +3.96% -8.75% 52.17 ms +6.31% -8.4% -6.5%
inserterOpen 28.06 ms +2.17% -6.09% 28.88 ms +9.45% -5.26% -2.84%
inserterHover 7.97 ms +3.89% -6.52% 9.16 ms +7.53% -10.04% -12.99%
inserterSearch 6.06 ms +6.6% -3.47% 6.55 ms +10.08% -6.87% -7.48%
loadPatterns 428.34 ms +6.14% -4.06% 467.15 ms +4.77% -6.54% -8.31%
wpTotal 262.26 ms +3% -9.43% 245.23 ms +8.07% -6.26% 6.94%
wpMemoryUsage 14.77 MB +0% -0% 14.74 MB +0% -0% 0.24%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric b420a40 trunk % Change
serverResponse 259.99 ms +2.57% -1.18% 244.41 ms +1.56% -0.83% 6.37%
firstPaint 303.17 ms +3.45% -12.42% 292.9 ms +7.45% -5.13% 3.51%
domContentLoaded 546.56 ms +2.25% -1.94% 565.19 ms +3.04% -4.87% -3.3%
loaded 547.41 ms +2.24% -1.96% 565.89 ms +3.05% -4.86% -3.27%
firstContentfulPaint 313.19 ms +0.63% -1.33% 328.46 ms +1.92% -4.18% -4.65%
firstBlock 1685.2 ms +1.86% -2.88% 1676.96 ms +2.76% -2.32% 0.49%
type 12.07 ms +8.45% -4.97% 12.7 ms +4.49% -8.43% -4.96%
navigate 75.31 ms +16.52% -9.71% 72.14 ms +1.16% -2% 4.39%
loadPatterns 957.27 ms +9.52% -9.29% 967.32 ms +5.51% -10.41% -1.04%
loadPages 897.37 ms +0.49% -0.33% 898.1 ms +2.09% -1.99% -0.08%
wpTotal 253.45 ms +2.63% -1.19% 236.97 ms +2.07% -0.6% 6.95%
wpMemoryUsage 12.79 MB +0% -0% 12.75 MB +0% -0% 0.27%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

29ff6c9 Run

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

Navigates the items list via UP/DOWN arrow keys in /test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator:  getByLabel('Page Two')
Expected: focused
Received: inactive
Timeout:  5000ms

Call log:
  - Expect "toBeFocused" getByLabel('Page Two') with timeout 5000ms
  - waiting for getByLabel('Page Two')
    14 × locator resolved to <button type="button" tabindex="-1" aria-pressed="false" id="view-list-0-184-item-wrapper" class="dataviews-view-list__item" aria-labelledby="view-list-0-184-label" aria-describedby="view-list-0-184-description"></button>
       - unexpected value "inactive"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js:146:49
does not select blocks in the canvas preview when editing from the sidebar in /test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator: getByRole('combobox', { name: 'Search or type URL' })
Expected: focused
Timeout: 5000ms
Error: element(s) not found

Call log:
  - Expect "toBeFocused" getByRole('combobox', { name: 'Search or type URL' }) with timeout 5000ms
  - waiting for getByRole('combobox', { name: 'Search or type URL' })

    at LinkControl.useLinkControlSearch (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js:416:47)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js:179:21

29ff6c9 Run

westonruter and others added 3 commits November 6, 2026 15:27
Resolves the conflict in the coding guidelines, where trunk split the
PHPStan paragraph into subsections. Trunk's structure is kept, and the
recommendation of `--fix` for out-of-date baseline entries is applied
to its "The baseline" subsection.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
Brings in trunk by way of the base branch, which was merged with it.
The analysis still reports no errors with the strict rules enabled.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
@dknauss

dknauss commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

Tested the Legacy Widget decoding change on PHP 8.3. Strict base64_decode() decodes valid encodings to the same bytes as the loose mode, including with 76-column line breaks, a trailing newline and surrounding spaces, so existing encoded instances keep decoding as before. Input that isn't base64 now returns false at decode instead of reaching the hash_equals() check; it rendered nothing before either, so there's no visible change. I didn't test the strict rules themselves.

westonruter and others added 4 commits November 9, 2026 18:11
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
Base automatically changed from update/phpstan-2.3.5 to trunk November 11, 2026 16:58
@westonruter
westonruter marked this pull request as ready for review November 11, 2026 16:59
@westonruter
westonruter requested review from ramonjd and a lite review from Copilot November 11, 2026 16:59

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The change alters published @wordpress/widgets runtime behavior without the required Unreleased changelog entry documenting the consumer-visible Legacy Widget fix.

1 open issue
What changed in this PR

Adds phpstan-strict-rules to Gutenberg’s development tooling and enables the rules already satisfied by the codebase, while hardening Legacy Widget instance decoding against invalid input.

Changes:

  • Registers supported strict PHPStan rules individually and prevents automatic loading of the package’s broader configuration.
  • Documents how contributors can opt into additional strict rules locally.
  • Uses strict Base64 decoding and validates Legacy Widget instance values before rendering.
File Description
phpstan.neon.dist Enables compatible phpstan-strict-rules checks and registers them individually.
packages/​widgets/​src/​blocks/​legacy-widget/​index.php Validates encoded widget data and uses strict Base64 decoding before rendering.
docs/​contributors/​code/​coding-guidelines.md Documents the strict-rules configuration and local opt-in process.
composer.json Adds phpstan/phpstan-strict-rules and prevents automatic loading of its broader configuration.

Review effort: Lite

westonruter and others added 5 commits November 11, 2026 09:17
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
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>
Claude-Session: https://claude.ai/code/session_01Tnky3GdCg3QL5KeMvuQvwf
Claude-Code-Session-Id: 5bac4eea-faaa-40e6-8440-b696b7773ba6
Comment on lines +40 to +46
$encoded = $attributes['instance']['encoded'];
$hash = $attributes['instance']['hash'];
if ( ! is_string( $encoded ) || ! is_string( $hash ) ) {
return '';
}
$serialized_instance = base64_decode( $encoded, true );
if ( false === $serialized_instance || ! hash_equals( wp_hash( $serialized_instance ), $hash ) ) {

@westonruter westonruter Nov 11, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ramonjd This is a fix in the class of errors you identified in #66598 (comment).

With block attributes, passing a non-string in to base64_decode() would cause a fatal error in PHP 8. For example:

<!-- wp:legacy-widget {"idBase":"text","instance":{"encoded":["x"],"hash":"h"}} /-->

So the is_string() check for the encoded value is the main fix here.

The addition of the strict param further validates that the string is valid base64 data. Since there's also a hash check on the decoded data, it's not really important. But it shouldn't hurt. It would only impact blocks where someone intentionally added stray non-base64 chars to the base64 data.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Focused PHPUnit tests are still needed to verify that array and non-base64 encoded inputs are safely rejected while valid encoded instances continue to render.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Add tests for malformed and valid encoded widget instances

packages/​widgets/​src/​blocks/​legacy-widget/​index.php:46

The new malformed-input paths are untested: an array encoded value must return an empty render instead of throwing, and a non-base64 character must be rejected while a valid encoded instance still renders. The repository has PHPUnit coverage for comparable block render callbacks, so please add focused tests for these branches.

1 resolved since last review

Review effort: Lite

@westonruter
westonruter requested a review from Mamaduka November 12, 2026 17:07

@Mamaduka Mamaduka left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice! Can't say I'm an expert when it comes to PHPStan, but changes makes sense.

@westonruter
westonruter merged commit 33cad93 into trunk Nov 12, 2026
91 checks passed
@westonruter
westonruter deleted the add/phpstan-strict-rules branch November 12, 2026 18:01
@github-actions github-actions Bot added this to the Gutenberg 24.5 milestone Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Type] Build Tooling Issues or PRs related to build tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants