phpcs.xml

<?xml version="1.0"?>
<ruleset name="Altolith">
	<description>Modern PSR-12 based PHPCS configuration with WordPress security rules</description>

	<!-- Files to check -->
	<file>.</file>

	<!-- Exclude patterns -->
	<exclude-pattern>*/vendor/*</exclude-pattern>
	<exclude-pattern>*/node_modules/*</exclude-pattern>
	<exclude-pattern>*/tests/*</exclude-pattern>
	<exclude-pattern>*.js</exclude-pattern>
	<exclude-pattern>*.css</exclude-pattern>
	<exclude-pattern>*/assets/build/*</exclude-pattern>
	<exclude-pattern>phpstan-stubs.php</exclude-pattern>

	<!-- ============================================== -->
	<!-- PRIMARY STANDARD: PSR-12 (with modifications)  -->
	<!-- ============================================== -->
	<rule ref="PSR12">
		<!-- Allow multiple classes per file for backward compatibility -->
		<exclude name="PSR1.Classes.ClassDeclaration.MultipleClasses"/>
		<!-- WordPress uses side effects in main plugin file -->
		<exclude name="PSR1.Files.SideEffects.FoundWithSymbols"/>
		<!-- Use TABS for indentation, not spaces -->
		<exclude name="Generic.WhiteSpace.DisallowTabIndent"/>
	</rule>

	<!-- ============================================== -->
	<!-- INDENTATION: Use tabs (not spaces)             -->
	<!-- ============================================== -->
	<rule ref="Generic.WhiteSpace.DisallowSpaceIndent"/>
	<!-- Note: Excluding Generic.WhiteSpace.ScopeIndent as it conflicts with PSR-12 interface formatting -->
	<!-- PSR-12 handles indentation via its own rules -->

	<!-- ============================================== -->
	<!-- WORDPRESS SECURITY RULES (CRITICAL)            -->
	<!-- ============================================== -->
	
	<!-- Nonce verification -->
	<rule ref="WordPress.Security.NonceVerification"/>
	
	<!-- Data sanitization and validation -->
	<rule ref="WordPress.Security.ValidatedSanitizedInput"/>
	
	<!-- Output escaping -->
	<rule ref="WordPress.Security.EscapeOutput">
		<!-- Exception messages don't need escaping -->
		<exclude name="WordPress.Security.EscapeOutput.ExceptionNotEscaped"/>
	</rule>
	
	<!-- SQL injection prevention -->
	<rule ref="WordPress.DB.PreparedSQL"/>
	<rule ref="WordPress.DB.PreparedSQLPlaceholders"/>
	
	<!-- Safe redirects -->
	<rule ref="WordPress.Security.SafeRedirect"/>
	
	<!-- Plugin/theme file inclusion -->
	<rule ref="WordPress.Security.PluginMenuSlug"/>
	
	<!-- ============================================== -->
	<!-- WORDPRESS-SPECIFIC FUNCTIONALITY               -->
	<!-- ============================================== -->
	
	<!-- Internationalization -->
	<rule ref="WordPress.WP.I18n">
		<properties>
			<property name="text_domain" type="array">
				<element value="altolith-deploy-r2"/>
			</property>
		</properties>
	</rule>
	
	<!-- WordPress database operations -->
	<rule ref="WordPress.DB.DirectDatabaseQuery"/>
	<rule ref="WordPress.DB.SlowDBQuery"/>
	<rule ref="WordPress.DB.RestrictedFunctions"/>
	<rule ref="WordPress.DB.RestrictedClasses"/>
	
	<!-- WordPress capabilities and user roles -->
	<rule ref="WordPress.WP.Capabilities"/>
	
	<!-- Discouraged WordPress functions -->
	<rule ref="WordPress.PHP.DiscouragedPHPFunctions"/>
	<rule ref="WordPress.WP.AlternativeFunctions"/>
	<rule ref="WordPress.WP.DiscouragedConstants"/>
	<rule ref="WordPress.WP.DiscouragedFunctions"/>
	
	<!-- WordPress enqueue handling -->
	<rule ref="WordPress.WP.EnqueuedResourceParameters"/>
	
	<!-- WordPress globals -->
	<rule ref="WordPress.WP.GlobalVariablesOverride"/>
	
	<!-- Post meta and options -->
	<rule ref="WordPress.WP.PostsPerPage"/>
	
	<!-- ============================================== -->
	<!-- ADDITIONAL PHP BEST PRACTICES                  -->
	<!-- ============================================== -->
	
	<!-- Disallow eval() and similar dangerous functions -->
	<rule ref="Squiz.PHP.Eval"/>
	<rule ref="Squiz.PHP.DisallowMultipleAssignments"/>
	
	<!-- Proper use of boolean operators -->
	<rule ref="Squiz.Operators.ValidLogicalOperators"/>
	
	<!-- Array declarations -->
	<rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
	
	<!-- Proper scope keywords -->
	<rule ref="Squiz.Scope.MethodScope"/>
	<rule ref="Squiz.Scope.MemberVarScope"/>
	
	<!-- Detect duplicate class names -->
	<rule ref="Generic.Classes.DuplicateClassName"/>
	
	<!-- ============================================== -->
	<!-- DOCUMENTATION STANDARDS                        -->
	<!-- ============================================== -->
	
	<!-- Require proper function/method documentation -->
	<rule ref="Squiz.Commenting.FunctionComment">
		<!-- Don't require @return void -->
		<exclude name="Squiz.Commenting.FunctionComment.MissingReturn"/>
		<exclude name="Squiz.Commenting.FunctionComment.InvalidReturn"/>
		<!-- Relaxed for tests -->
		<severity>3</severity>
	</rule>
	
	<!-- Class documentation -->
	<rule ref="Squiz.Commenting.ClassComment">
		<!-- Don't require all tags -->
		<exclude name="Squiz.Commenting.ClassComment.Missing"/>
		<exclude name="Squiz.Commenting.ClassComment.TagNotAllowed"/>
	</rule>
	
	<!-- Variable documentation -->
	<rule ref="Squiz.Commenting.VariableComment">
		<!-- Allow missing var comments for obvious types -->
		<exclude name="Squiz.Commenting.VariableComment.Missing"/>
	</rule>
	
	<!-- ============================================== -->
	<!-- NAMING CONVENTIONS                             -->
	<!-- ============================================== -->
	
	<!-- Allow WordPress core globals in snake_case -->
	<rule ref="Squiz.NamingConventions.ValidVariableName">
		<exclude name="Squiz.NamingConventions.ValidVariableName.PrivateNoUnderscore"/>
		<exclude name="Squiz.NamingConventions.ValidVariableName.MemberNotCamelCaps"/>
		<!-- Note: WordPress core globals should have phpcs:ignore comments -->
	</rule>
	
	<rule ref="Squiz.NamingConventions.ValidFunctionName">
		<exclude name="Squiz.NamingConventions.ValidFunctionName.PrivateNoUnderscore"/>
	</rule>
	
	<!-- ============================================== -->
	<!-- PHP COMPATIBILITY                              -->
	<!-- ============================================== -->
	
	<!-- Minimum PHP version: 7.4 -->
	<config name="testVersion" value="7.4-"/>
	
	<!-- ============================================== -->
	<!-- PHPCS CONFIGURATION                            -->
	<!-- ============================================== -->
	
	<!-- Show progress and use colors -->
	<arg value="ps"/>
	<arg name="colors"/>
	
	<!-- Show sniff codes in all reports -->
	<arg value="ns"/>
	
	<!-- Check up to 20 files simultaneously -->
	<arg name="parallel" value="20"/>
	
	<!-- ============================================== -->
	<!-- EXCLUSIONS FOR PSR-4 COMPATIBILITY             -->
	<!-- ============================================== -->
	
	<!-- Allow namespaced file names -->
	<rule ref="WordPress.Files.FileName">
		<properties>
			<property name="strict_class_file_names" value="false"/>
		</properties>
		<exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/>
		<exclude name="WordPress.Files.FileName.InvalidClassFileName"/>
	</rule>
</ruleset>