# PHPStan configuration for WordPress Core.

#

# To overload this configuration, copy this file to phpstan.neon and adjust as needed.

#

# https://phpstan.org/config-reference

includes:

# The base configuration file for using PHPStan with the WordPress core codebase.

- tests/phpstan/base.neon

# Type-specifying extension so PHPUnit assertions (e.g. assertArrayHasKey(),

# assertInstanceOf(), assertNotNull()) narrow types in the analysis. Only the

# extension is included, not phpstan-phpunit's rules.neon, to avoid introducing

# new strict rules.

- vendor/phpstan/phpstan-phpunit/extension.neon

# Preexisting errors that should be ignored, one baseline per error identifier

# so that the remaining work on each is visible as a single shrinking file.

# Each is meant to reach zero and be deleted, taking its line below with it.

# https://phpstan.org/user-guide/baseline

#

# Regenerate with `composer phpstan:baselines`, which rewrites both the files

# and the list between the markers. Do not edit that list by hand.

# phpstan:baselines start

- tests/phpstan/baselines/argument.type.neon

- tests/phpstan/baselines/argument.unresolvableType.neon

- tests/phpstan/baselines/assign.propertyType.neon

- tests/phpstan/baselines/binaryOp.invalid.neon

- tests/phpstan/baselines/booleanAnd.alwaysFalse.neon

- tests/phpstan/baselines/booleanAnd.leftAlwaysTrue.neon

- tests/phpstan/baselines/booleanAnd.rightAlwaysTrue.neon

- tests/phpstan/baselines/booleanNot.alwaysFalse.neon

- tests/phpstan/baselines/booleanNot.alwaysTrue.neon

- tests/phpstan/baselines/class.notFound.neon

- tests/phpstan/baselines/deadCode.unreachable.neon

- tests/phpstan/baselines/empty.offset.neon

- tests/phpstan/baselines/empty.property.neon

- tests/phpstan/baselines/empty.variable.neon

- tests/phpstan/baselines/function.alreadyNarrowedType.neon

- tests/phpstan/baselines/function.resultUnused.neon

- tests/phpstan/baselines/identical.alwaysFalse.neon

- tests/phpstan/baselines/identical.alwaysTrue.neon

- tests/phpstan/baselines/if.alwaysFalse.neon

- tests/phpstan/baselines/if.alwaysTrue.neon

- tests/phpstan/baselines/isset.offset.neon

- tests/phpstan/baselines/isset.property.neon

- tests/phpstan/baselines/method.childParameterType.neon

- tests/phpstan/baselines/method.unused.neon

- tests/phpstan/baselines/notIdentical.alwaysTrue.neon

- tests/phpstan/baselines/nullCoalesce.property.neon

- tests/phpstan/baselines/offsetAccess.nonOffsetAccessible.neon

- tests/phpstan/baselines/offsetAccess.notFound.neon

- tests/phpstan/baselines/offsetAssign.valueType.neon

- tests/phpstan/baselines/parameter.defaultValue.neon

- tests/phpstan/baselines/parameter.notFound.neon

- tests/phpstan/baselines/parameterByRef.type.neon

- tests/phpstan/baselines/parameterByRef.unusedType.neon

- tests/phpstan/baselines/property.defaultValue.neon

- tests/phpstan/baselines/property.nonObject.neon

- tests/phpstan/baselines/property.notFound.neon

- tests/phpstan/baselines/property.private.neon

- tests/phpstan/baselines/property.protected.neon

- tests/phpstan/baselines/return.type.neon

- tests/phpstan/baselines/return.unusedType.neon

- tests/phpstan/baselines/varTag.noVariable.neon

- tests/phpstan/baselines/variable.undefined.neon

# phpstan:baselines end

parameters:

# https://phpstan.org/user-guide/rule-levels

level: 5

reportUnmatchedIgnoredErrors: true

# The following ignored errors are not intended to be fixed, as distinct from the baselines

# included above.

#

# A baseline records work still to be done. Every entry in one is in scope to be fixed, and

# each file is meant to reach zero and then be deleted. An entry here is the opposite: a

# decision that the code is right as written and the report is not actionable, whether

# because PHPStan cannot see what makes the code safe, or because satisfying it would mean

# changing code that has no other reason to change.

#

# So prefer fixing an error, and baseline it when it cannot be fixed yet. Add it here only

# when it should never be fixed, and say why.

ignoreErrors:

# Level 0:

- # Inner functions aren't supported by PHPStan.

message: '#Function wxr_[a-z_]+ not found#'

path: src/wp-admin/includes/export.php

-

identifier: function.inner

path: src/wp-admin/includes/export.php

count: 13

-

identifier: function.inner

path: src/wp-admin/includes/file.php

count: 1

-

identifier: function.inner

path: src/wp-includes/canonical.php

count: 1

# In core, @internal is advisory for extenders: it marks a symbol that plugins should not rely on. Core itself is

# one codebase and its own uses of these symbols are intended. PHPStan scopes @internal by root namespace, and

# since core symbols live in the global namespace, it reports every use outside the declaring class or file.

#

# The identifier depends on where the symbol is used (e.g. new.internalClass, parameter.internalInterface,

# varTag.internalTrait), so the entry matches on the message instead, which always names the symbol right after

# "internal <kind>". The name must not contain a backslash, so uses of @internal symbols from namespaced

# third-party libraries like SimplePie and Requests are still reported. A bundled library in the global

# namespace cannot be told apart from core that way, so it must be excluded by its prefix instead. Currently

# that is only sodium_compat (ParagonIE_), which marks much of its API as @internal. These checks are only

# enabled by bleedingEdge; functions, class constants, instantiations, and static calls are checked from level 0,

# and methods, properties, and type references from level 2.

-

message: '#\binternal (?:static )?(?:class|interface|trait|enum|function|method|constant|property) (?!ParagonIE_)\w++(?!\\)#'

reportUnmatched: false

# Level 2:

# ValueError is PHP 8.0+; core throws it conditionally so the docblocks are correct for WP's 7.4+ range,

# but bleedingEdge's version-aware check treats the class as non-existent against the PHP 7.4 floor.

-

message: '#^PHPDoc tag @throws with type InvalidArgumentException\|ValueError is not subtype of Throwable$#'

path: src/wp-includes/compat.php

reportUnmatched: false

# Level 5:

# substr_compare()'s $length has always accepted null, meaning "compare the full length". PHP 7.4 spelled

# that `int $length = null`, where the null default makes the parameter implicitly nullable, and PHP 8.0

# only made it explicit as `?int $length = null`. The behavior never differed: verified on PHP 7.4 that

# passing null compares the whole string rather than coercing to a length of 0.

#

# PHPStan reads the two spellings from two sources and only one is right. Its PHP 8 stub carries `?int`,

# but the pre-8.0 `resources/functionMap.php` records the type as plain `int`, having dropped the implicit

# nullability when it was transcribed from the old manual. Because `phpVersion.min` is 70400, the legacy

# map wins and null is reported as invalid.

#

# This lives here rather than in a baseline because a baseline entry records work still to be done, and

# there is none: the call is correct on every version WordPress supports, and the fault is in PHPStan's

# data. Passing an explicit length purely to satisfy it would change working code to suit a tooling bug.

# `reportUnmatched: false` so this entry lapses quietly if PHPStan corrects the map.

-

message: '#^Parameter \#4 \$length of function substr_compare expects int, null given\.$#'

path: src/wp-includes/html-api/class-wp-html-tag-processor.php

reportUnmatched: false

# HTML API:

# These errors are ignored for the sake of making it easier to keep the HTML Processor in sync with the HTML spec.

-

message: '#^Comparison operation "\>" between 999\|1000 and 0 is always true\.$#'

identifier: greater.alwaysTrue

count: 1

path: src/wp-includes/html-api/class-wp-html-processor.php

-

message: '#^Comparison operation "\>\=" between 0 and 8 is always false\.$#'

identifier: greaterOrEqual.alwaysFalse

count: 1

path: src/wp-includes/html-api/class-wp-html-processor.php

-

message: '#^Left side of && is always true\.$#'

identifier: booleanAnd.leftAlwaysTrue

count: 1

path: src/wp-includes/html-api/class-wp-html-processor.php

-

message: '#^Unreachable statement \- code above always terminates\.$#'

identifier: deadCode.unreachable

count: 15

path: src/wp-includes/html-api/class-wp-html-processor.php

-

message: '#^If condition is always true\.$#'

identifier: if.alwaysTrue

count: 2

path: src/wp-includes/html-api/class-wp-html-processor.php

-

# The early return at the start of step() narrows $last_error to null, and PHPStan does not see that

# bookmark_token() sets it to ERROR_EXCEEDED_MAX_BOOKMARKS before throwing, whether it is called directly

# in step() or via insert_virtual_node() in a step_*() method. So it reports that the checks in both catch

# blocks of step() can never match, when in fact they do whenever bookmarks run out.

message: '#^Strict comparison using \=\=\= between ''exceeded\-max…'' and null will always evaluate to false\.$#'

identifier: identical.alwaysFalse

count: 2

path: src/wp-includes/html-api/class-wp-html-processor.php