phpcs.xml.dist

<?xml version="1.0"?>
<ruleset name="Integration with WorkOS">
	<description>Coding standards for the Integration with WorkOS plugin.</description>

	<!-- Scan these files -->
	<file>./src</file>
	<file>./integration-workos.php</file>
	<file>./uninstall.php</file>

	<!-- Exclude vendor, node_modules, and JS source (use ESLint for JS) -->
	<exclude-pattern>*/vendor/*</exclude-pattern>
	<exclude-pattern>*/node_modules/*</exclude-pattern>
	<exclude-pattern>*/tests/*</exclude-pattern>
	<exclude-pattern>*.js</exclude-pattern>

	<!-- Use WordPress Coding Standards -->
	<rule ref="WordPress">
		<!-- Allow short array syntax -->
		<exclude name="Universal.Arrays.DisallowShortArraySyntax" />

		<!-- PSR-4 autoloading requires PascalCase filenames, not class- prefixed -->
		<exclude name="WordPress.Files.FileName.NotHyphenatedLowercase" />
		<exclude name="WordPress.Files.FileName.InvalidClassFileName" />
	</rule>

	<!-- Direct DB queries are required for custom tables (not using WP post/meta API) -->
	<rule ref="WordPress.DB.DirectDatabaseQuery">
		<exclude name="WordPress.DB.DirectDatabaseQuery.DirectQuery" />
		<exclude name="WordPress.DB.DirectDatabaseQuery.NoCaching" />
	</rule>

	<!-- meta_key/meta_value queries are intentional for user lookups by WorkOS ID -->
	<rule ref="WordPress.DB.SlowDBQuery.slow_db_query_meta_key">
		<severity>0</severity>
	</rule>
	<rule ref="WordPress.DB.SlowDBQuery.slow_db_query_meta_value">
		<severity>0</severity>
	</rule>

	<!-- base64 is required for JWT/JWK/PKCE cryptographic operations, not obfuscation -->
	<rule ref="WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode">
		<exclude-pattern>*/Api/Client.php</exclude-pattern>
	</rule>
	<rule ref="WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode">
		<exclude-pattern>*/Api/Client.php</exclude-pattern>
		<exclude-pattern>*/Auth/Login.php</exclude-pattern>
	</rule>

	<!-- OAuth callbacks do not use WordPress nonces; they use WorkOS state tokens -->
	<rule ref="WordPress.Security.NonceVerification.Recommended">
		<exclude-pattern>*/Auth/*.php</exclude-pattern>
	</rule>

	<!-- wp_login is a core WP hook name we must fire to maintain compatibility -->
	<rule ref="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound">
		<exclude-pattern>*/Auth/Login.php</exclude-pattern>
		<exclude-pattern>*/UI/Ajax.php</exclude-pattern>
	</rule>

	<!--
		Webhook hook names use dot notation to mirror WorkOS event types
		(e.g. workos_webhook_user.updated). This is intentional and required
		for the dynamic routing in Webhook/Receiver.php.
	-->
	<rule ref="WordPress.NamingConventions.ValidHookName.UseUnderscores">
		<exclude-pattern>*/Webhook/Receiver.php</exclude-pattern>
		<exclude-pattern>*/Sync/UserSync.php</exclude-pattern>
		<exclude-pattern>*/Sync/DirectorySync.php</exclude-pattern>
		<exclude-pattern>*/Organization/Manager.php</exclude-pattern>
		<exclude-pattern>*/Contracts/Controller.php</exclude-pattern>
	</rule>

	<!-- Plugin.php uses camelCase for public getters and private bootstrap methods (established API) -->
	<rule ref="WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid">
		<exclude-pattern>*/Plugin.php</exclude-pattern>
	</rule>

	<!-- $default is a standard WP parameter name (get_option, get_post_meta, etc.) -->
	<rule ref="Universal.NamingConventions.NoReservedKeywordParameterNames.defaultFound">
		<severity>0</severity>
	</rule>

	<!-- Check for PHP cross-version compatibility -->
	<config name="testVersion" value="7.4-" />
	<rule ref="PHPCompatibilityWP" />

	<!-- WordPress minimum versions -->
	<config name="minimum_wp_version" value="6.2" />

	<!-- Text domain -->
	<rule ref="WordPress.WP.I18n">
		<properties>
			<property name="text_domain" type="array">
				<element value="integration-workos" />
			</property>
		</properties>
	</rule>

	<!-- Prefixes -->
	<rule ref="WordPress.NamingConventions.PrefixAllGlobals">
		<properties>
			<property name="prefixes" type="array">
				<element value="workos" />
				<element value="WorkOS" />
			</property>
		</properties>
	</rule>
</ruleset>