phpcs.xml

<?xml version="1.0"?>
<ruleset name="Newspack Monorepo Coding Standards">
	<description>Single shared PHPCS configuration for all Newspack plugins, themes, and packages.</description>

	<arg value="sp"/>
	<arg name="colors"/>
	<arg name="extensions" value="php"/>
	<arg name="parallel" value="8"/>

	<!-- Shared base rule sets. -->
	<rule ref="WordPress-Extra"/>
	<rule ref="WordPress-Docs"/>
	<rule ref="WordPress-VIP-Go"/>

	<!-- Project-wide exclusions. AGENTS.md: short array syntax is allowed,
	     Yoda conditions not required. -->
	<rule ref="WordPress">
		<exclude name="Universal.Arrays.DisallowShortArraySyntax.Found"/>
		<exclude name="Universal.Operators.DisallowStandalonePostIncrementDecrement.PostIncrementFound"/>
		<exclude name="Squiz.Functions.MultiLineFunctionDeclaration.SpaceAfterFunction"/>
		<exclude name="WordPress.PHP.YodaConditions.NotYoda"/>
		<exclude name="Generic.Formatting.MultipleStatementAlignment.NotSameWarning"/>
		<exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed"/>
		<exclude name="Universal.NamingConventions.NoReservedKeywordParameterNames"/>
		<exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.Found"/>
	</rule>

	<!-- Custom capabilities defined by Newspack plugins (newspack-plugin,
	     newspack-multibranded-site). Listed at root so WP.Capabilities does
	     not flag legitimate cap names. -->
	<rule ref="WordPress.WP.Capabilities">
		<properties>
			<property name="custom_capabilities" type="array">
				<element value="newspack_view_others_media"/>
				<element value="manage_woocommerce"/>
			</property>
		</properties>
	</rule>

	<!-- Test doubles duplicate class names on purpose: a stand-in for a class
	     another plugin ships, or a second stub of the same thing for an
	     isolated case. The sniff cannot tell either from a genuine duplicate.
	     It also sees a pair only when both files land in the same forked batch,
	     and that boundary moves whenever a PHP file is added anywhere, so it
	     reports against whichever pull request shifted it rather than the one
	     that introduced the duplicate. -->
	<rule ref="Generic.Classes.DuplicateClassName">
		<exclude-pattern>*/tests/*</exclude-pattern>
	</rule>

	<!-- republication-tracker-tool's main file is named without the standard
	     class-<name>.php convention; keep that exception monorepo-wide. -->
	<rule ref="WordPress.Files.FileName.InvalidClassFileName">
		<exclude-pattern>*/plugins/republication-tracker-tool/*</exclude-pattern>
	</rule>

	<!-- Newspack custom sniffs. ForbiddenMethods (loose) applies broadly so
	     callers across the monorepo are nudged toward
	     Newspack_Newsletters_Contacts. ForbiddenContactsMethods (strict, with
	     service-providers/ exemption) only makes sense inside the newsletters
	     plugin, where it disciplines internal callers. The first ref registers
	     the standard; the per-sniff refs that follow only refine scope. -->
	<rule ref="./phpcsSniffs"/>
	<rule ref="phpcsSniffs.Newsletters.ForbiddenMethods">
		<exclude-pattern>*/plugins/newspack-newsletters/*</exclude-pattern>
	</rule>
	<rule ref="phpcsSniffs.Newsletters.ForbiddenContactsMethods">
		<include-pattern>*/plugins/newspack-newsletters/*</include-pattern>
	</rule>

	<!-- ConstantDocblock exists to keep the constants catalog complete, so its
	     scope tracks what the catalog actually reads. bin/constants-scanner.php
	     skips tests/, where a defined() guard is a suite toggling a flag rather
	     than production code consuming one; a docblock there would document
	     nothing the catalog could pick up. -->
	<rule ref="phpcsSniffs.Constants.ConstantDocblock">
		<exclude-pattern>*/tests/*</exclude-pattern>
	</rule>

	<!-- newspack-theme has classic-theme conventions that pre-date the
	     stricter commenting/indent sniffs WordPress-Extra enables; preserve
	     the prior per-theme exclusions rather than reformat the theme. -->
	<rule ref="Squiz.Commenting.FileComment.SpacingAfterComment">
		<exclude-pattern>*/themes/newspack-theme/*</exclude-pattern>
	</rule>
	<rule ref="Squiz.Commenting.FunctionComment.MissingParamTag">
		<exclude-pattern>*/themes/newspack-theme/*</exclude-pattern>
	</rule>
	<rule ref="Squiz.Commenting.InlineComment.InvalidEndChar">
		<exclude-pattern>*/themes/newspack-theme/*</exclude-pattern>
	</rule>
	<rule ref="Generic.WhiteSpace.ScopeIndent.Incorrect">
		<exclude-pattern>*/themes/newspack-theme/*</exclude-pattern>
	</rule>

	<rule ref="PHPCompatibilityWP"/>
	<config name="testVersion" value="8.0-"/>
	<config name="minimum_wp_version" value="6.6"/>

	<!-- PHPCS discovers and autoloads sniffs by the `<Name>Sniff.php` PascalCase
	     convention, so our own sniffs cannot follow the WordPress file-naming
	     rules without ceasing to be loadable. -->
	<rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
		<exclude-pattern>*/phpcsSniffs/*</exclude-pattern>
	</rule>
	<rule ref="WordPress.Files.FileName.InvalidClassFileName">
		<exclude-pattern>*/phpcsSniffs/*</exclude-pattern>
	</rule>

	<!-- Same conflict, on the other side of the API: PHPCS exposes its own
	     helpers as camelCase properties (Tokens::$emptyTokens), which a sniff
	     has to name exactly to use them. -->
	<rule ref="WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase">
		<exclude-pattern>*/phpcsSniffs/*</exclude-pattern>
	</rule>

	<!-- Scan only in-scope monorepo code. This list is the single source of
	     truth for "what counts as our PHP": CI lints it (see the PHPCS jobs in
	     .github/workflows/ci.yml) and the pre-commit hook derives its scope
	     from it, so the two can't drift.

	     `bin/` is deliberately absent. It is Docker dev tooling, not WordPress
	     runtime code, and the WordPress-VIP-Go standard encodes platform
	     assumptions that don't hold there — a read-only filesystem, an HTML
	     output context, restricted hooks. Bringing it in would mean ~40
	     suppressions asserting "this is a CLI script" against ~8 real fixes. -->
	<file>plugins</file>
	<file>themes</file>
	<file>packages</file>
	<file>config</file>
	<file>e2e</file>
	<file>phpcsSniffs</file>

	<!-- Build output, deps, autogenerated asset manifests, and test fixtures. -->
	<exclude-pattern>*/node_modules/*</exclude-pattern>
	<exclude-pattern>*/vendor/*</exclude-pattern>
	<exclude-pattern>*/dev-lib/*</exclude-pattern>
	<exclude-pattern>*/dist/*</exclude-pattern>
	<exclude-pattern>*/build/*</exclude-pattern>
	<exclude-pattern>*/release/*</exclude-pattern>
	<exclude-pattern>*/assets/dist/*</exclude-pattern>
	<exclude-pattern>*/*.asset.php</exclude-pattern>
	<exclude-pattern>*/tests/fixtures/*</exclude-pattern>

	<!-- These two suites break WordPress runtime rules deliberately: stub
	     classes, several object structures per file, direct filesystem calls,
	     assignment to $GLOBALS['post']. Linting them would mean ~50
	     suppressions asserting "this is a test double" against no real fix. -->
	<exclude-pattern>*/plugins/newspack-blocks/tests/*</exclude-pattern>
	<exclude-pattern>*/themes/newspack-theme/tests/*</exclude-pattern>
</ruleset>