phpcs.xml

<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="Laranail Toolkit Coding Standard">
    <description>PSR-12 conformance lint for laranail/toolkit (formatting is owned by Pint).</description>

    <arg value="p"/>
    <arg value="s"/>
    <arg name="colors"/>

    <!-- `ignore_warnings_on_exit` was removed in PHP_CodeSniffer 4.0, and CI
         resolves 4.x. It silently stopped applying, so warnings started gating
         the build: 186 of them, exit code 2, zero errors. The sniffs that
         produced them are excluded below by name instead, which says which
         warnings are tolerated and why; a blanket "warnings never fail" hid
         that distinction anyway. -->

    <!-- Paths to check -->
    <file>src</file>
    <file>tests</file>

    <!-- Exclude paths -->
    <exclude-pattern>vendor/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
    <!-- Fixtures + the api-surface scanner are data/tooling, not style-governed source. -->
    <exclude-pattern>tests/Fixtures/*</exclude-pattern>

    <!-- PSR-12 base. Pint owns formatting; exclude the one sniff that fights
         Pint's single-line empty bodies (`) {}`, valid under PER style). -->
    <rule ref="PSR12">
        <!-- Pint owns formatting; exclude the sniffs that fight its PER-style
             single-line empty bodies (`class Foo {}` / `) {}`). -->
        <exclude name="Squiz.WhiteSpace.ScopeClosingBrace.ContentBefore"/>
        <exclude name="PSR2.Classes.ClassDeclaration.OpenBraceNewLine"/>
        <!-- Single-line promoted-constructor empty bodies (`__construct(...) {}`)
             that Pint produces. -->
        <exclude name="Squiz.Functions.MultiLineFunctionDeclaration.BraceOnSameLine"/>
        <!-- Pint emits `new class()` (no space) for anonymous classes; this
             PSR-12 sniff wants `new class ()`. Pint owns formatting. -->
        <exclude name="PSR12.Classes.AnonClassDeclaration.SpaceAfterKeyword"/>
        <!-- Concatenation spacing. PSR-12 wants `$a . $b`; Pint's laravel preset
             emits `$a.$b`. Running phpcbf over this took PHPCS to 0 errors and
             left 108 files dirty for Pint - the two cannot both be satisfied, and
             this file's premise is that Pint wins. Measured: 876 of the 1078
             errors were these two codes. -->
        <exclude name="PSR12.Operators.OperatorSpacing.NoSpaceAfter"/>
        <exclude name="PSR12.Operators.OperatorSpacing.NoSpaceBefore"/>
        <!-- `new Foo` vs `new Foo()`. Pint's new_with_parentheses fixer owns this,
             and the anon-class case above is already carved out for the same
             reason. The remaining 202 errors were this one code. -->
        <exclude name="PSR12.Classes.ClassInstantiation.MissingParentheses"/>
        <!-- Pint's `global_namespace_import.import_functions` emits
             `use function dirname;` in its own group, separated by a blank line
             from the class imports. PSR-12's file-header sniff reads that blank
             line as the header ending and reports every class import after it as
             out of order. Same conflict as the entries above, same resolution. -->
        <exclude name="PSR12.Files.FileHeader.IncorrectOrder"/>
    </rule>

    <!-- Line length. Pint's shared config aligns `=>` within a block, which
         LENGTHENS lines by design, so the two tools pull in opposite directions
         on exactly the lines Pint just rewrote. 183 of the 186 findings here were
         this one sniff. Pint owns formatting; this is that premise applied. -->
    <rule ref="Generic.Files.LineLength">
        <severity>0</severity>
    </rule>

    <!-- A Pest test file both declares a class and runs top-level closures. That
         is what a Pest file IS, so the sniff cannot be satisfied without
         restructuring the suite around a rule that exists for autoloadable
         production code. -->
    <rule ref="PSR1.Files.SideEffects.FoundWithSymbols">
        <exclude-pattern>tests/*</exclude-pattern>
    </rule>

    <!-- Test methods follow PHPUnit's snake_case convention. -->
    <rule ref="PSR1.Methods.CamelCapsMethodName.NotCamelCaps">
        <exclude-pattern>tests/*</exclude-pattern>
    </rule>

    <!-- Tests may colocate small fixture classes alongside the test class. -->
    <rule ref="PSR1.Classes.ClassDeclaration.MultipleClasses">
        <exclude-pattern>tests/*</exclude-pattern>
    </rule>

    <!-- Clean-code (built-in sniffs only) -->
    <rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
    <rule ref="Generic.CodeAnalysis.EmptyStatement"/>
    <rule ref="Generic.CodeAnalysis.UnconditionalIfStatement"/>
    <rule ref="Generic.CodeAnalysis.UnnecessaryFinalModifier"/>
    <rule ref="Generic.CodeAnalysis.UselessOverridingMethod"/>
    <rule ref="Squiz.WhiteSpace.SuperfluousWhitespace"/>
</ruleset>