.phpcs.xml.dist

<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Coding Standard for PHPUnit Polyfills" xsi:noNamespaceSchemaLocation="./vendor/squizlabs/php_codesniffer/phpcs.xsd">
    <description>Check the code of PHPUnit Polyfills.</description>

    <!--
    #############################################################################
    COMMAND LINE ARGUMENTS
    https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml
    #############################################################################
    -->

    <file>.</file>

    <!-- Only check PHP files. -->
    <arg name="extensions" value="php"/>

    <!-- Show progress, show the error codes for each message (source). -->
    <arg value="ps"/>

    <!-- Strip the filepaths down to the relevant bit. -->
    <arg name="basepath" value="./"/>

    <!-- Check up to 8 files simultaneously. -->
    <arg name="parallel" value="8"/>

	<!-- Cache the results between runs. -->
	<arg name="cache" value="./.cache/phpcs.cache"/>


	<!--
	#############################################################################
	USE THE YoastCS RULESET
	#############################################################################
	-->

	<rule ref="Yoast">
		<!-- Duplicate classes is by design and part of the cross-version compatibility mechanism. -->
		<exclude name="Generic.Classes.DuplicateClassName"/>

		<!-- Exclude some rules which conflicts with the naming conventions used in PHPUnit. -->
		<exclude name="Yoast.Files.FileName"/>
		<exclude name="WordPress.NamingConventions.ValidVariableName"/>
		<exclude name="WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid"/>

		<!-- Exclude some rules which are irrelevant.
			 The code in this package is not run in the context of a WordPress plugin. -->
		<exclude name="WordPress.DB"/>
		<exclude name="WordPress.PHP.DevelopmentFunctions.error_log_var_export"/>
		<exclude name="WordPress.PHP.DiscouragedPHPFunctions.system_calls_popen"/>
		<exclude name="WordPress.Security"/>
		<exclude name="WordPress.WP"/>
		<exclude name="Yoast.Yoast.AlternativeFunctions"/>
		<exclude name="Yoast.NamingConventions.ObjectNameDepth.MaxExceeded"/>
	</rule>

	<!-- While PHPCompatibility is already included in the Yoast ruleset, it uses
		 the PHPCompatibilityWP ruleset, which excludes rules polyfilled by WP.
		 Setting the severity for all PHPCompatibility rules to 5 prevents WP
		 polyfilled functionality from not being flagged in this repo. -->
	<rule ref="PHPCompatibility">
		<severity>5</severity>

		<!-- These PHP 7.0+ classes are polyfilled for this repo. -->
		<exclude name="PHPCompatibility.Classes.NewClasses.errorFound"/>
		<exclude name="PHPCompatibility.Classes.NewClasses.typeerrorFound"/>
	</rule>

	<!-- Enforce PSR1 compatible namespaces. -->
	<rule ref="PSR1.Classes.ClassDeclaration"/>


	<!--
	#############################################################################
	SNIFF SPECIFIC CONFIGURATION
	#############################################################################
	-->

	<rule ref="Yoast.NamingConventions.NamespaceName">
		<properties>
			<property name="prefixes" type="array">
				<element value="Yoast\PHPUnitPolyfills"/>
			</property>
			<property name="src_directory" type="array">
				<element value="src"/>
			</property>
		</properties>
	</rule>


	<!--
	#############################################################################
	SELECTIVE EXCLUSIONS
	Exclude specific files for specific sniffs and/or exclude sub-groups in sniffs.
	#############################################################################
	-->

	<!-- The polyfills for the PHP native exceptions can not have a namespace
		 and making those the only files with a file comment would create more,
		 not less inconsistency. -->
	<rule ref="Yoast.Commenting.FileComment">
		<exclude-pattern>/src/Exceptions/*Error\.php$</exclude-pattern>
	</rule>

	<!-- Deliberately empty Catch statements. -->
	<rule ref="Generic.CodeAnalysis.EmptyStatement.DetectedCatch">
		<exclude-pattern>/src/Helpers/ResourceHelper\.php$</exclude-pattern>
		<exclude-pattern>/src/Polyfills/AssertClosedResource*\.php$</exclude-pattern>
	</rule>

	<!-- Targetted error silencing. This is okay. -->
	<rule ref="WordPress.PHP.NoSilencedErrors">
		<exclude-pattern>/src/Helpers/ResourceHelper\.php$</exclude-pattern>
		<exclude-pattern>/src/Polyfills/AssertClosedResource*\.php$</exclude-pattern>
	</rule>

	<!-- The TestCase for PHPUnit 8+ will only ever be loaded on PHP 7.2+. -->
	<!-- The TestListenerDefaultImplementation for PHPUnit 7+ will only ever be loaded on PHP 7.1+. -->
	<rule ref="PHPCompatibility.FunctionDeclarations.NewReturnTypeDeclarations.voidFound">
		<exclude-pattern>/src/TestCases/TestCasePHPUnitGte8\.php$</exclude-pattern>
		<exclude-pattern>/src/TestListeners/TestListenerDefaultImplementationPHPUnitGte7\.php$</exclude-pattern>
	</rule>

	<!-- The TestListenerDefaultImplementation for PHPUnit 7+ will only ever be loaded on PHP 7.1+. -->
	<rule ref="PHPCompatibility.Interfaces.NewInterfaces.throwableFound">
		<exclude-pattern>/src/TestListeners/TestListenerDefaultImplementationPHPUnitGte7\.php$</exclude-pattern>
	</rule>

	<!-- The TestListenerDefaultImplementation for PHPUnit 7+ will only ever be loaded on PHP 7.1+. -->
	<rule ref="PHPCompatibility.FunctionDeclarations.NewParamTypeDeclarations.floatFound">
		<exclude-pattern>/src/TestListeners/TestListenerDefaultImplementationPHPUnitGte7\.php$</exclude-pattern>
	</rule>

	<!-- The @throws tags in the docblocks are correct, but the sniff can't analyse this correctly. -->
	<rule ref="Squiz.Commenting.FunctionCommentThrowTag.Missing">
		<exclude-pattern>/src/Polyfills/AssertFileDirectory\.php$</exclude-pattern>
		<exclude-pattern>/src/Polyfills/ExpectException\.php$</exclude-pattern>
	</rule>

	<!-- Make some allowances for test files. -->
	<rule ref="WordPress.PHP.DevelopmentFunctions">
		<exclude-pattern>/tests/*\.php$</exclude-pattern>
	</rule>

	<!-- Covers annotations are in the test classes, not the trait. -->
	<rule ref="Yoast.Commenting.TestsHaveCoversTag.Missing">
		<exclude-pattern>/tests/TestCases/TestCaseTestTrait\.php$</exclude-pattern>
		<exclude-pattern>/tests/Polyfills/Fixtures/*\.php$</exclude-pattern>
	</rule>

	<!-- These fixtures for the assertEqualObject() tests will only be loaded on PHP 7+/8+ respectively. -->
	<rule ref="PHPCompatibility.FunctionDeclarations.NewReturnTypeDeclarations">
		<exclude-pattern>/tests/Polyfills/Fixtures/ChildValueObject\.php$</exclude-pattern>
		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObject\.php$</exclude-pattern>
		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObjectUnion\.php$</exclude-pattern>
	</rule>
	<rule ref="PHPCompatibility.FunctionDeclarations.NewParamTypeDeclarations.UnionTypeFound">
		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObjectUnion\.php$</exclude-pattern>
		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObjectUnionNoReturnType\.php$</exclude-pattern>
	</rule>
	<rule ref="PHPCompatibility.Operators.NewOperators.t_spaceshipFound">
		<exclude-pattern>/tests/Polyfills/Fixtures/ValueObject\.php$</exclude-pattern>
	</rule>

</ruleset>