phpcs.xml.dist

<?xml version="1.0"?>
<ruleset name="Telex">
    <description>PHP_CodeSniffer ruleset for the Telex plugin.</description>

    <!-- Scan all PHP files in the plugin root, includes/, and lib/ -->
    <file>telex.php</file>
    <file>uninstall.php</file>
    <file>includes/</file>
    <file>tests/</file>
    <file>lib/</file>

    <!-- Exclude vendor and build output -->
    <exclude-pattern>vendor/*</exclude-pattern>
    <exclude-pattern>build/*</exclude-pattern>
    <exclude-pattern>node_modules/*</exclude-pattern>
    <!-- JS tests are linted by ESLint, not PHPCS -->
    <exclude-pattern>tests/js/*</exclude-pattern>

    <!-- WordPress coding standards (full enforcement on plugin code) -->
    <rule ref="WordPress-Extra">
        <!-- lib/ uses PSR-12 conventions; WordPress style rules don't apply there. -->
        <exclude-pattern>lib/*</exclude-pattern>
    </rule>
    <rule ref="WordPress-Docs">
        <exclude-pattern>lib/*</exclude-pattern>
    </rule>
    <!-- PHPCompatibility for lib/ (security-relevant, compatible with PSR-12) -->
    <rule ref="PHPCompatibilityWP">
        <include-pattern>lib/*</include-pattern>
    </rule>

    <!-- PHP version baseline — PHP 8.2+ features are allowed -->
    <config name="testVersion" value="8.2-" />

    <!-- Minimum WP version for deprecation checks -->
    <config name="minimum_wp_version" value="6.7" />

    <!-- Require short array syntax [] throughout (PHP 5.4+) -->
    <rule ref="Generic.Arrays.DisallowLongArraySyntax" />
    <!-- Suppress the conflicting rule from phpcsstandards/phpcsextra -->
    <rule ref="Universal.Arrays.DisallowShortArraySyntax.Found">
        <severity>0</severity>
    </rule>

    <!-- Relax line-length for complex strings -->
    <rule ref="WordPress.WP.AlternativeFunctions">
        <!-- Allow file_put_contents in the fatal handler (last resort) -->
        <exclude name="WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents" />
        <!-- Allow direct unlink/rmdir in controlled cleanup paths -->
        <exclude name="WordPress.WP.AlternativeFunctions.unlink_unlink" />
        <exclude name="WordPress.WP.AlternativeFunctions.file_system_operations_rmdir" />
    </rule>

    <!-- Allow PHP 8.2 readonly, enums, match, named args -->
    <rule ref="PHPCompatibilityWP">
        <properties>
            <property name="testVersion" value="8.2-" />
        </properties>
    </rule>

    <!-- Enum files and test files use non-hyphenated names — suppress WP filename rules.
         Test files must be named after their class for PHPUnit 11 test discovery. -->
    <rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
        <exclude-pattern>includes/Enums/*</exclude-pattern>
        <exclude-pattern>tests/*</exclude-pattern>
    </rule>
    <rule ref="WordPress.Files.FileName.InvalidClassFileName">
        <exclude-pattern>includes/class-telex-dtos.php</exclude-pattern>
    </rule>

    <!-- DTOs and HTTP client/exception live in single files by design.
         Test files routinely define stub/helper classes alongside the test case. -->
    <rule ref="Generic.Files.OneObjectStructurePerFile">
        <exclude-pattern>includes/class-telex-dtos.php</exclude-pattern>
        <exclude-pattern>includes/class-telex-wp-http-client.php</exclude-pattern>
        <exclude-pattern>tests/*</exclude-pattern>
    </rule>

    <!-- Test helper stubs (Stub_Psr18_Client, etc.) follow class naming inside
         their test file rather than living in class-stub-*.php files. -->
    <rule ref="WordPress.Files.FileName.InvalidClassFileName">
        <exclude-pattern>tests/*</exclude-pattern>
    </rule>

    <!-- Test_Telex_SDK.php uses Nyholm\Psr7 directly; wp_json_encode is available
         but json_encode is fine here as these target pure SDK logic. -->
    <rule ref="WordPress.WP.AlternativeFunctions.json_encode_json_encode">
        <exclude-pattern>tests/*</exclude-pattern>
    </rule>

    <!-- PHPCompatibility false positive: $this IS valid in PHP 8.1 backed enum methods -->
    <rule ref="PHPCompatibility.Variables.ForbiddenThisUseContexts.OutsideObjectContext">
        <exclude-pattern>includes/Enums/*</exclude-pattern>
    </rule>

    <!-- base64_encode/decode are used for AES-256-GCM token storage, not obfuscation -->
    <rule ref="WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode">
        <severity>0</severity>
    </rule>
    <rule ref="WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode">
        <severity>0</severity>
    </rule>

    <!-- Tests intentionally use lowercase 'wordpress' as array keys; suppress
         the CapitalPDangit sniff for the entire tests/ directory. -->
    <rule ref="WordPress.WP.CapitalPDangit">
        <exclude-pattern>tests/*</exclude-pattern>
    </rule>

    <!-- Tool-directive inline comments (@phpstan-ignore, @phpstan-var, phpcs:ignore)
         are machine-readable annotations, not prose sentences, so the trailing-
         punctuation requirement does not apply to them. -->
    <rule ref="Squiz.Commenting.InlineComment.InvalidEndChar">
        <severity>0</severity>
    </rule>

    <!-- PHPStan @var annotations use array-shape syntax (array{key: type}) that
         PHPCS's heuristic misidentifies as commented-out PHP code. These are
         legitimate type narrowing annotations, not dead code. -->
    <rule ref="Squiz.PHP.CommentedOutCode.Found">
        <severity>0</severity>
    </rule>
</ruleset>