phpcs.xml.dist

<?xml version="1.0"?>
<ruleset name="Pioneer Theme Coding Standards">
    <description>PHP CodeSniffer configuration for Pioneer WordPress theme.</description>

    <!-- What to scan -->
    <file>.</file>

    <!-- Exclude paths -->
    <exclude-pattern>/vendor/*</exclude-pattern>
    <exclude-pattern>/node_modules/*</exclude-pattern>
    <exclude-pattern>/assets/dist/*</exclude-pattern>
    <exclude-pattern>/tests/*</exclude-pattern>
    <exclude-pattern>/inc/acf-pro/*</exclude-pattern>

    <!-- How to scan -->
    <arg value="sp"/> <!-- Show sniff and progress -->
    <arg name="basepath" value="."/>
    <arg name="colors"/>
    <arg name="extensions" value="php"/>
    <arg name="parallel" value="8"/>

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

        <!-- Allow short ternary -->
        <exclude name="Universal.Operators.DisallowShortTernary"/>

        <!-- Don't require file comments for every file -->
        <exclude name="Squiz.Commenting.FileComment.Missing"/>
        <exclude name="Squiz.Commenting.FileComment.MissingPackageTag"/>
        <exclude name="Squiz.Commenting.FileComment.SpacingAfterComment"/>

        <!-- Allow single-line control structures -->
        <exclude name="Generic.ControlStructures.InlineControlStructure.NotAllowed"/>

        <!-- More relaxed inline documentation -->
        <exclude name="Squiz.Commenting.FunctionComment.Missing"/>
        <exclude name="Squiz.Commenting.FunctionComment.MissingParamTag"/>
        <exclude name="Squiz.Commenting.FunctionComment.MissingParamComment"/>
        <exclude name="Squiz.Commenting.FunctionComment.ParamCommentFullStop"/>
        <exclude name="Squiz.Commenting.FunctionComment.MissingParamName"/>
        <exclude name="Squiz.Commenting.FunctionComment.ParamNameNoMatch"/>
        <exclude name="Squiz.Commenting.FunctionComment.ThrowsNoFullStop"/>
        <exclude name="Squiz.Commenting.FunctionComment.ThrowsNotCapital"/>
        <exclude name="Squiz.Commenting.InlineComment.InvalidEndChar"/>
        <exclude name="Squiz.Commenting.VariableComment.Missing"/>
        <exclude name="Squiz.Commenting.VariableComment.MissingVar"/>
        <exclude name="Squiz.Commenting.ClassComment.Missing"/>
        <exclude name="Squiz.Commenting.ClassComment.SpacingAfter"/>
        <exclude name="Squiz.PHP.CommentedOutCode.Found"/>

        <!-- Allow exit without message -->
        <exclude name="WordPress.Security.EscapeOutput.OutputNotEscaped"/>

        <!-- Allow non-Yoda conditions (more readable) -->
        <exclude name="WordPress.PHP.YodaConditions.NotYoda"/>

        <!-- Flexible file naming for templates/blocks -->
        <exclude name="WordPress.Files.FileName.InvalidClassFileName"/>
        <exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/>

        <!-- Allow mixed functions and classes in settings modules -->
        <exclude name="Universal.Files.SeparateFunctionsFromOO.Mixed"/>

        <!-- Allow reserved keyword parameter names -->
        <exclude name="Universal.NamingConventions.NoReservedKeywordParameterNames"/>

        <!-- Allow debug functions when wrapped properly -->
        <exclude name="WordPress.PHP.DevelopmentFunctions.error_log_error_log"/>

        <!-- Allow alternative file functions for optimization -->
        <exclude name="WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents"/>
        <exclude name="WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents"/>
        <exclude name="WordPress.WP.AlternativeFunctions.unlink_unlink"/>
        <exclude name="WordPress.WP.AlternativeFunctions.strip_tags_strip_tags"/>

        <!-- Allow date() for display purposes -->
        <exclude name="WordPress.DateTime.RestrictedFunctions.date_date"/>

        <!-- Translator comments are helpful but not required for simple placeholders -->
        <exclude name="WordPress.WP.I18n.MissingTranslatorsComment"/>

        <!-- Allow lowercase doc comment starts -->
        <exclude name="Generic.Commenting.DocComment.ShortNotCapital"/>

        <!-- Allow unused function parameters (common in WordPress hooks) -->
        <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter"/>

        <!-- Allow lonely if (sometimes clearer than elseif) -->
        <exclude name="Universal.ControlStructures.DisallowLonelyIf.Found"/>

        <!-- Allow missing @throws tag -->
        <exclude name="Squiz.Commenting.FunctionCommentThrowTag.Missing"/>
    </rule>

    <!-- Walker class methods must match parent signature (no visibility change) -->
    <rule ref="PSR2.Methods.MethodDeclaration.Underscore">
        <exclude-pattern>/inc/class-accessible-walker.php</exclude-pattern>
    </rule>
    <rule ref="Squiz.Scope.MethodScope.Missing">
        <exclude-pattern>/inc/class-accessible-walker.php</exclude-pattern>
    </rule>

    <!-- Admin table classes use WP patterns that are safe -->
    <rule ref="WordPress.Security.EscapeOutput">
        <exclude-pattern>/inc/image-optimizer/class-queue-admin.php</exclude-pattern>
    </rule>

    <!-- Allow non-prefixed hook names when applying core WordPress filters -->
    <rule ref="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound">
        <exclude-pattern>/inc/class-accessible-walker.php</exclude-pattern>
        <exclude-pattern>/inc/ai-helpers.php</exclude-pattern>
        <exclude-pattern>/inc/theme-settings/modules/*</exclude-pattern>
        <exclude-pattern>/templates/*</exclude-pattern>
    </rule>

    <!-- Allow inline scripts for performance (Vite integration) -->
    <rule ref="WordPress.WP.EnqueuedResources.NonEnqueuedScript">
        <exclude-pattern>/inc/class-pioneer-theme.php</exclude-pattern>
        <exclude-pattern>/inc/class-components.php</exclude-pattern>
    </rule>

    <!-- Disable global prefix requirement for templates/partials/blocks (local scope) -->
    <rule ref="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound">
        <exclude-pattern>/partials/*</exclude-pattern>
        <exclude-pattern>/templates/*</exclude-pattern>
        <exclude-pattern>/blocks/*</exclude-pattern>
    </rule>

    <!-- Allow overriding WP globals in template context -->
    <rule ref="WordPress.WP.GlobalVariablesOverride.Prohibited">
        <exclude-pattern>/partials/*</exclude-pattern>
        <exclude-pattern>/templates/*</exclude-pattern>
    </rule>

    <!-- Relax variable naming for partials (extracted from args) -->
    <rule ref="WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase">
        <exclude-pattern>/partials/*</exclude-pattern>
    </rule>

    <!-- WordPress Core Security -->
    <rule ref="WordPress.Security"/>

    <!-- WordPress VIP rules (performance focused) -->
    <rule ref="WordPress.DB"/>
    <rule ref="WordPress.DateTime"/>
    <rule ref="WordPress.WP"/>

    <!-- Minimum PHP version -->
    <config name="minimum_supported_wp_version" value="5.8"/>
    <config name="testVersion" value="7.4-"/>

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

    <!-- Prefix for functions and classes (excluding templates/partials/helpers) -->
    <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
        <properties>
            <property name="prefixes" type="array">
                <element value="pioneer"/>
                <element value="Pioneer"/>
            </property>
        </properties>
        <exclude-pattern>/partials/*</exclude-pattern>
        <exclude-pattern>/templates/*</exclude-pattern>
        <exclude-pattern>/blocks/*</exclude-pattern>
        <exclude-pattern>/inc/image-optimizer/helpers.php</exclude-pattern>
        <exclude-pattern>/inc/image-optimizer/performance-helpers.php</exclude-pattern>
    </rule>
</ruleset>