phpstan.neon.dist

# PHPStan configuration for WordPress Core.
#
# To override this configuration, create a phpstan.neon which includes this file and adjusts
# its parameters as needed, rather than copying it, so that the copy does not go stale. See
# tests/phpstan/README.md for examples.
#
# 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.leftAlwaysTrue.neon
	- tests/phpstan/baselines/booleanNot.alwaysTrue.neon
	- tests/phpstan/baselines/class.notFound.neon
	- tests/phpstan/baselines/deadCode.unreachable.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/if.alwaysFalse.neon
	- tests/phpstan/baselines/if.alwaysTrue.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/offsetAccess.nonOffsetAccessible.neon
	- tests/phpstan/baselines/offsetAccess.notFound.neon
	- tests/phpstan/baselines/offsetAssign.valueType.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/return.type.neon
	- tests/phpstan/baselines/return.unusedType.neon
	- tests/phpstan/baselines/varTag.noVariable.neon
	- tests/phpstan/baselines/variable.undefined.neon
	# phpstan:baselines end

# Rules from phpstan-strict-rules which core already complies with, or which enforce the
# WordPress Coding Standards. The others are not enabled until the code complies with them,
# but they can be enabled in a local phpstan.neon to work toward that. See
# tests/phpstan/README.md.
#
# These are registered individually, rather than by including phpstan-strict-rules' rules.neon
# with only these enabled, because that file also makes several PHPStan parameters stricter
# even when its rules are disabled.
# https://github.com/phpstan/phpstan-strict-rules
rules:
	- PHPStan\Rules\DisallowedConstructs\DisallowedBacktickRule
	- PHPStan\Rules\DisallowedConstructs\DisallowedShortTernaryRule
	- PHPStan\Rules\Functions\ClosureUsesThisRule
	- PHPStan\Rules\Methods\WrongCaseOfInheritedMethodRule

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