phpcs.xml.dist

<?xml version="1.0"?>
<ruleset name="ffcertificate">
    <description>WordPress Coding Standards for Free Form Certificate.</description>

    <!-- Default to scanning the project root. CI passes specific paths. -->
    <file>.</file>

    <!-- Exclusions -->
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
    <exclude-pattern>*/build/*</exclude-pattern>
    <exclude-pattern>*/dist/*</exclude-pattern>
    <exclude-pattern>*/languages/*</exclude-pattern>
    <exclude-pattern>*/html/*</exclude-pattern>
    <exclude-pattern>*/includes/libraries/*</exclude-pattern>
    <exclude-pattern>*/libs/*</exclude-pattern>
    <exclude-pattern>*/tests/*</exclude-pattern>
    <!-- CI/dev helper scripts (e.g. .github/scripts/shard-tests.php) are not
         plugin runtime code and don't follow the WordPress runtime standards. -->
    <exclude-pattern>*/.github/*</exclude-pattern>
    <exclude-pattern>*.min.js</exclude-pattern>
    <exclude-pattern>*.min.css</exclude-pattern>

    <arg name="basepath" value="."/>
    <arg name="extensions" value="php"/>
    <arg name="colors"/>
    <arg name="parallel" value="8"/>
    <arg value="ps"/>

    <!-- Rules -->
    <rule ref="WordPress-Extra">
        <exclude name="Generic.PHP.LowerCaseConstant"/>
    </rule>
    <rule ref="WordPress-Docs"/>

    <!-- PHP version compatibility -->
    <config name="testVersion" value="8.1-"/>
    <rule ref="PHPCompatibilityWP"/>

    <config name="minimum_wp_version" value="6.2"/>

    <rule ref="WordPress.WP.I18n">
        <properties>
            <property name="text_domain" type="array">
                <element value="ffcertificate"/>
            </property>
        </properties>
    </rule>

    <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
        <properties>
            <property name="prefixes" type="array">
                <element value="ffc"/>
                <element value="FFC"/>
                <element value="FreeFormCertificate"/>
                <element value="ffcertificate"/>
            </property>
        </properties>
    </rule>

    <!-- PSR-4 autoloading: class filenames don't follow WP naming. -->
    <rule ref="WordPress.Files.FileName">
        <exclude name="WordPress.Files.FileName.InvalidClassFileName"/>
    </rule>

    <!-- PSR-4 naming conventions: camelCase methods and properties are intentional. -->
    <rule ref="WordPress.NamingConventions.ValidFunctionName">
        <exclude name="WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid"/>
    </rule>
    <rule ref="WordPress.NamingConventions.ValidVariableName">
        <exclude name="WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase"/>
    </rule>

    <!-- Prefix "ffc"/"FFC" is the established convention for this plugin.
         PHPCS requires 4+ char prefixes, but ffc/FFC is already the project standard. -->
    <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
        <exclude name="WordPress.NamingConventions.PrefixAllGlobals.ShortPrefixPassed"/>
        <exclude name="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedConstantFound"/>
        <exclude name="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedClassFound"/>
        <exclude name="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound"/>
        <exclude name="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound"/>
        <exclude name="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound"/>
    </rule>

    <!-- Custom capabilities used by the plugin. -->
    <rule ref="WordPress.WP.Capabilities">
        <properties>
            <property name="custom_capabilities" type="array">
                <!-- End-user (own_) caps. -->
                <element value="ffc_view_own_certificates"/>
                <element value="ffc_download_own_certificates"/>
                <element value="ffc_view_own_certificate_history"/>
                <element value="ffc_book_own_appointments"/>
                <element value="ffc_view_own_appointments"/>
                <element value="ffc_cancel_own_appointments"/>
                <element value="ffc_view_own_audience_bookings"/>
                <!-- Admin module caps — manage (vê e edita). -->
                <element value="ffc_bypass_appointments"/>
                <element value="ffc_bypass_appointment_capacity"/>
                <element value="ffc_manage_certificates"/>
                <element value="ffc_export_certificates"/>
                <element value="ffc_edit_certificates"/>
                <element value="ffc_manage_appointments"/>
                <element value="ffc_manage_audiences"/>
                <element value="ffc_manage_reregistration"/>
                <element value="ffc_manage_custom_fields"/>
                <element value="ffc_view_activity_log"/>
                <element value="ffc_view_as_user"/>
                <element value="ffc_manage_settings"/>
                <element value="ffc_manage_forms"/>
                <element value="ffc_view_forms"/>
                <element value="ffc_view_forms_api"/>
                <!-- Admin module caps — view (só vê) tier of the 3-state model. -->
                <element value="ffc_view_certificates"/>
                <element value="ffc_view_appointments"/>
                <element value="ffc_view_audiences"/>
                <element value="ffc_view_reregistration"/>
                <element value="ffc_view_custom_fields"/>
                <element value="ffc_view_settings"/>
                <!-- Virtual meta-cap (computed via user_has_cap, not role-granted): gates Settings-page entry. -->
                <element value="ffc_view_settings_page"/>
                <!-- URL shortener domain (GAP B). -->
                <element value="ffc_view_url_shortener"/>
                <element value="ffc_manage_url_shortener"/>
                <!-- Recruitment caps. -->
                <element value="ffc_manage_recruitment"/>
                <element value="ffc_view_recruitment"/>
                <element value="ffc_import_recruitment"/>
                <element value="ffc_call_recruitment"/>
                <element value="ffc_view_recruitment_pii"/>
                <element value="ffc_manage_recruitment_settings"/>
                <element value="ffc_manage_recruitment_reasons"/>
                <element value="ffc_view_recruitment_settings"/>
                <element value="ffc_view_recruitment_reasons"/>
                <!-- Destructive delete tier (GAP E). -->
                <element value="ffc_delete_certificates"/>
                <element value="ffc_delete_appointments"/>
                <element value="ffc_delete_audiences"/>
                <element value="ffc_delete_reregistration"/>
                <element value="ffc_delete_custom_fields"/>
                <element value="ffc_delete_recruitment"/>
                <element value="ffc_delete_url_shortener"/>
                <!-- Legacy names kept only for migration paths (pre-6.2.0 +
                     the 4.5.0 self_scheduling slug reversed by the taxonomy
                     migration). Not used in live current_user_can() gates. -->
                <element value="view_own_certificates"/>
                <element value="download_own_certificates"/>
                <element value="view_certificate_history"/>
                <element value="ffc_view_self_scheduling"/>
            </property>
        </properties>
    </rule>

    <!-- Common parameter names that happen to be PHP reserved keywords. -->
    <rule ref="Universal.NamingConventions.NoReservedKeywordParameterNames">
        <exclude name="Universal.NamingConventions.NoReservedKeywordParameterNames.namespaceFound"/>
        <exclude name="Universal.NamingConventions.NoReservedKeywordParameterNames.newFound"/>
        <exclude name="Universal.NamingConventions.NoReservedKeywordParameterNames.classFound"/>
        <exclude name="Universal.NamingConventions.NoReservedKeywordParameterNames.matchFound"/>
        <exclude name="Universal.NamingConventions.NoReservedKeywordParameterNames.stringFound"/>
        <exclude name="Universal.NamingConventions.NoReservedKeywordParameterNames.defaultFound"/>
    </rule>

    <!-- Hook callbacks have fixed signatures; unused trailing params are expected. -->
    <rule ref="Generic.CodeAnalysis.UnusedFunctionParameter">
        <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed"/>
        <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.Found"/>
    </rule>

    <!-- False positives: inline comments with code-like syntax (e.g. option values). -->
    <rule ref="Squiz.PHP.CommentedOutCode">
        <exclude name="Squiz.PHP.CommentedOutCode.Found"/>
    </rule>

    <!--
        #563 Sprint 1 — submission pipeline guards throw SubmissionRejected
        carrying a wp_send_json_error() *payload array*, never an HTML-output
        message. The exception is always caught by the FormProcessor
        orchestrator and routed through wp_send_json_error() (JSON), so the
        sniff's concern (an uncaught exception message echoed to the page)
        cannot occur here. Escaping these translated strings with esc_html()
        would corrupt apostrophes in the user-facing JSON messages. Scope the
        exclusion narrowly to the guard directory.
    -->
    <rule ref="WordPress.Security.EscapeOutput.ExceptionNotEscaped">
        <exclude-pattern>*/includes/frontend/submission/*</exclude-pattern>
    </rule>
    <!--
        Enabled deliberately (#1028). This sniff is NOT part of WordPress-Extra
        — it lives only in the full WordPress standard — so it had never run
        here, while ~44 annotations across the codebase were written as if it
        did. All 50 sites it reports were read individually: every one is the
        same false positive, where sanitisation happens in the next statement
        rather than the same expression, and each now carries a suppression
        stating which call sanitises it. Enabling it is what makes the next
        unsanitised read fail CI instead of passing unnoticed.
    -->
    <rule ref="WordPress.Security.ValidatedSanitizedInput"/>

    <!--
        Enabled deliberately (#1028), the second of the two sniffs the
        suppression audit found had never run: like ValidatedSanitizedInput it
        lives only in the full WordPress standard, not in WordPress-Extra.
        Its 129 sites were classified before being annotated — 25 are
        transaction control that touches no table, 47 are writes to the
        plugin's own ffc_* tables (which WordPress has no API for), 3 are
        schema changes, and of the 54 reads most cannot be cached for a
        reason rather than merely are not: a migration must read live state, a
        uniqueness probe must not be served from cache, an export cursor reads
        each page once. The reads where caching is a genuine open question say
        so at the site and are tracked separately.
    -->
    <rule ref="WordPress.DB.DirectDatabaseQuery"/>

</ruleset>