psalm.xml

<?xml version="1.0"?>
<psalm
    errorLevel="1"
    resolveFromConfigFile="true"
    findUnusedCode="true"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="https://getpsalm.org/schema/config"
    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
    autoloader="vendor/autoload.php"
>
    <projectFiles>
        <directory name="." />
        <ignoreFiles>
            <directory name="vendor" />
            <directory name="node_modules" />
            <directory name="assets" />
            <directory name="bin" />
            <directory name="docs-src" />
            <directory name="src/tools" />
            <directory name="tests" />
        </ignoreFiles>
    </projectFiles>

    <issueHandlers>

        <!--
            ============================================
            PSALM 6.7+ STRICT MODE SUPPRESSIONS
            ============================================
            These issues were introduced by Psalm 6.7.0's stricter checks.
            MissingOverrideAttribute: requires PHP 8.3+ #[\Override] on every override
            ClassMustBeFinal: wants all non-extended classes to be final
            InvalidOperand/PossiblyInvalidOperand: false positives for int concatenation
            MixedArgumentTypeCoercion: stricter coercion checks
        -->
        <MissingOverrideAttribute errorLevel="suppress" />
        <ClassMustBeFinal errorLevel="suppress" />
        <InvalidOperand errorLevel="suppress" />
        <PossiblyInvalidOperand errorLevel="suppress" />
        <MixedArgumentTypeCoercion errorLevel="suppress" />

        <!--
            ============================================
            VIEW TEMPLATE PATTERN SUPPRESSIONS
            ============================================
            Views use PHP's include pattern where variables set in controllers
            become available in the included view file. Psalm cannot trace this.
        -->
        <UndefinedGlobalVariable>
            <errorLevel type="suppress">
                <directory name="src/Modules/Admin/Views" />
                <directory name="src/Modules/Book/Views" />
                <directory name="src/Modules/Dictionary/Views" />
                <directory name="src/Modules/Feed/Views" />
                <directory name="src/Modules/Home/Views" />
                <directory name="src/Modules/Language/Views" />
                <directory name="src/Modules/Review/Views" />
                <directory name="src/Modules/Tags/Views" />
                <directory name="src/Modules/Text/Views" />
                <directory name="src/Modules/User/Views" />
                <directory name="src/Modules/Vocabulary/Views" />
            </errorLevel>
        </UndefinedGlobalVariable>

        <!-- Mixed* issues in views and curl constant usage -->
        <MixedArgument>
            <errorLevel type="suppress">
                <directory name="src/Modules/Dictionary/Infrastructure/Translation" />
                <directory name="src/Modules/Book/Views" />
                <directory name="src/Modules/Dictionary/Views" />
                <directory name="src/Modules/Home/Views" />
                <directory name="src/Modules/Tags/Views" />
                <directory name="src/Modules/Vocabulary/Views" />
                <directory name="src/Shared/UI/Assets" />
            </errorLevel>
        </MixedArgument>

        <MixedArrayAccess>
            <errorLevel type="suppress">
                <directory name="src/Modules/Book/Views" />
            </errorLevel>
        </MixedArrayAccess>

        <MixedAssignment>
            <errorLevel type="suppress">
                <directory name="src/Modules/Book/Views" />
            </errorLevel>
        </MixedAssignment>

        <MixedOperand>
            <errorLevel type="suppress">
                <directory name="src/Modules/Book/Views" />
            </errorLevel>
        </MixedOperand>

        <!-- Type checks for safety with dynamic data -->
        <RedundantCondition>
            <errorLevel type="suppress">
                <directory name="src/Modules/Admin/Views" />
                <directory name="src/Modules/Book/Application" />
                <directory name="src/Modules/Book/Views" />
                <directory name="src/Modules/Dictionary/Views" />
                <directory name="src/Modules/Feed/Http" />
                <directory name="src/Modules/Feed/Views" />
                <directory name="src/Modules/Home/Views" />
                <directory name="src/Modules/Language/Views" />
                <directory name="src/Modules/Review/Views" />
                <directory name="src/Modules/Tags/Views" />
                <directory name="src/Modules/Text/Http" />
                <directory name="src/Modules/Text/Views" />
                <directory name="src/Modules/User/Views" />
                <directory name="src/Modules/Vocabulary/Views" />
            </errorLevel>
        </RedundantCondition>

        <RedundantConditionGivenDocblockType>
            <errorLevel type="suppress">
                <directory name="src/Modules/Admin/Views" />
                <directory name="src/Modules/Book/Views" />
                <directory name="src/Modules/Dictionary/Infrastructure" />
                <directory name="src/Modules/Feed/Views" />
                <directory name="src/Modules/Feed/Application" />
                <directory name="src/Modules/Home/Views" />
                <directory name="src/Modules/Language/Views" />
                <directory name="src/Modules/Review/Views" />
                <directory name="src/Modules/Tags/Views" />
                <directory name="src/Modules/Text/Views" />
                <directory name="src/Modules/User/Views" />
                <directory name="src/Modules/Vocabulary/Views" />
            </errorLevel>
        </RedundantConditionGivenDocblockType>

        <TypeDoesNotContainType>
            <errorLevel type="suppress">
                <directory name="src/Modules/Admin/Views" />
                <directory name="src/Modules/Dictionary/Views" />
                <directory name="src/Modules/Feed/Http" />
                <directory name="src/Modules/Language/Views" />
                <directory name="src/Modules/Review/Infrastructure" />
                <directory name="src/Modules/Tags/Views" />
                <directory name="src/Modules/User/Views" />
            </errorLevel>
        </TypeDoesNotContainType>

        <!-- Type annotations document expected types for dynamic data -->
        <UnnecessaryVarAnnotation>
            <errorLevel type="suppress">
                <directory name="src/Modules/Book/Application" />
                <directory name="src/Modules/Dictionary/Views" />
                <directory name="src/Modules/Feed/Views" />
                <directory name="src/Modules/Feed/Application" />
                <directory name="src/Modules/Feed/Http" />
                <directory name="src/Modules/Home/Views" />
                <directory name="src/Modules/Language/Views" />
                <directory name="src/Modules/Review/Views" />
                <directory name="src/Modules/Tags/Views" />
                <directory name="src/Modules/Text/Views" />
                <directory name="src/Modules/Text/Application" />
                <directory name="src/Modules/User/Views" />
                <directory name="src/Modules/User/Application" />
                <directory name="src/Modules/Vocabulary/Views" />
                <directory name="src/Modules/Vocabulary/Application" />
                <directory name="src/Modules/Vocabulary/Infrastructure" />
                <directory name="src/Modules/Vocabulary/Http" />
            </errorLevel>
        </UnnecessaryVarAnnotation>


        <!--
            ============================================
            CONTROLLER/ROUTING PATTERN SUPPRESSIONS
            ============================================
            Controllers use include to render views, making local variables
            available to the view. Also, controller methods are called via
            routing, not direct PHP calls.
        -->

        <!-- Variables set before include are passed to view files -->
        <UnusedVariable>
            <errorLevel type="suppress">
                <directory name="src/backend/Controllers" />
                <directory name="src/Modules/Book/Http" />
                <directory name="src/Modules/Book/Views" />
                <directory name="src/Modules/Dictionary/Http" />
                <directory name="src/Modules/Dictionary/Infrastructure" />
                <directory name="src/Modules/Feed/Http" />
                <directory name="src/Modules/Feed/Application" />
                <directory name="src/Modules/Home/Http" />
                <directory name="src/Modules/Language/Http" />
                <directory name="src/Modules/Language/Views" />
                <directory name="src/Modules/Review/Application" />
                <directory name="src/Modules/Tags/Infrastructure" />
                <directory name="src/Modules/Tags/Application" />
                <directory name="src/Modules/Text/Http" />
                <directory name="src/Modules/Text/Application" />
                <directory name="src/Modules/User/Http" />
                <directory name="src/Modules/Vocabulary/Http" />
                <directory name="src/Modules/Vocabulary/Views" />
                <directory name="src/Modules/Vocabulary/Application" />
            </errorLevel>
        </UnusedVariable>

        <!-- Unused foreach values - often intentional when only key is needed -->
        <UnusedForeachValue>
            <errorLevel type="suppress">
                <directory name="src/Modules" />
            </errorLevel>
        </UnusedForeachValue>

        <!-- Parameters used by included view files or for interface consistency -->
        <UnusedParam>
            <errorLevel type="suppress">
                <directory name="src/Modules/Book/Application" />
                <directory name="src/Modules/Book/Http" />
                <directory name="src/Modules/Text/Http" />
                <directory name="src/Modules/Review/Application" />
                <directory name="src/Modules/User/Application" />
            </errorLevel>
        </UnusedParam>

        <!-- Controllers use dynamic include paths for view templates -->
        <UnresolvableInclude>
            <errorLevel type="suppress">
                <directory name="src/backend/Controllers" />
                <directory name="src/Modules/Book/Http" />
                <directory name="src/Modules/Text/Http" />
            </errorLevel>
        </UnresolvableInclude>

        <!--
            ============================================
            ROUTING/DI/API PATTERN SUPPRESSIONS
            ============================================
            Methods called via routing, DI container, or API endpoints
            appear unused to static analysis.
        -->

        <!-- Public methods called via routing or DI container -->
        <PossiblyUnusedMethod>
            <errorLevel type="suppress">
                <directory name="src/backend/Controllers" />
                <directory name="src/backend/Api" />
                <file name="src/Shared/Infrastructure/Globals.php" />
                <directory name="src/Modules" />
                <directory name="src/Shared" />
            </errorLevel>
        </PossiblyUnusedMethod>

        <!-- Route params required by interface but not always used -->
        <PossiblyUnusedParam>
            <errorLevel type="suppress">
                <directory name="src/backend/Controllers" />
                <directory name="src/Modules" />
                <directory name="src/Shared" />
            </errorLevel>
        </PossiblyUnusedParam>

        <!-- Return values may not be used by all callers -->
        <PossiblyUnusedReturnValue>
            <errorLevel type="suppress">
                <directory name="src/Modules" />
                <directory name="src/Shared" />
            </errorLevel>
        </PossiblyUnusedReturnValue>

        <!-- Classes used via DI container or routing -->
        <UnusedClass>
            <errorLevel type="suppress">
                <directory name="src/backend/Controllers" />
                <directory name="src/backend/Api" />
                <directory name="src/Modules" />
            </errorLevel>
        </UnusedClass>

        <!--
            ============================================
            DOMAIN/INFRASTRUCTURE PATTERN SUPPRESSIONS
            ============================================
            Properties and methods for ORM mapping, interface compliance,
            and future API use.
        -->

        <!-- Properties for ORM mapping or future use -->
        <PossiblyUnusedProperty>
            <errorLevel type="suppress">
                <directory name="src/Modules" />
            </errorLevel>
        </PossiblyUnusedProperty>

        <UnusedProperty>
            <errorLevel type="suppress">
                <directory name="src/Modules" />
            </errorLevel>
        </UnusedProperty>

        <!-- Interface implementations may have different parameter names -->
        <ParamNameMismatch>
            <errorLevel type="suppress">
                <file name="src/Shared/Infrastructure/Globals.php" />
                <directory name="src/Modules" />
                <directory name="src/Shared" />
            </errorLevel>
        </ParamNameMismatch>

        <!-- Repository implementations may have more specific param types -->
        <MoreSpecificImplementedParamType>
            <errorLevel type="suppress">
                <directory name="src/Modules" />
            </errorLevel>
        </MoreSpecificImplementedParamType>

        <!-- Repository implementations may have less specific return types -->
        <LessSpecificImplementedReturnType>
            <errorLevel type="suppress">
                <file name="src/Shared/Infrastructure/Globals.php" />
                <directory name="src/Modules" />
                <directory name="src/Shared" />
            </errorLevel>
        </LessSpecificImplementedReturnType>

    </issueHandlers>
</psalm>