phpcs.xml

<?xml version="1.0"?>
<ruleset name="project-coding-standards">
    <description>Coding standards for Discoverer modules</description>

    <file>src</file>
    <file>tests</file>

    <!-- Don't sniff third party libraries -->
    <exclude-pattern>./vendor/*</exclude-pattern>
    <exclude-pattern>*/thirdparty/*</exclude-pattern>

    <!-- Show progress and output sniff names on violation, and add colours -->
    <arg value="p" />
    <arg name="colors" />
    <arg value="s" />

    <!-- Use PSR-2 as a base standard -->
    <rule ref="PSR2">
        <!-- Allow non camel cased method names - some base SS method names are PascalCase or snake_case -->
        <exclude name="PSR1.Methods.CamelCapsMethodName.NotCamelCaps"/>
        <!-- This rule conflicts with Slevomat standards requiring an empty line before closing brace -->
        <exclude name="PSR2.Classes.ClassDeclaration.CloseBraceAfterBody"/>
    </rule>

    <!-- allow only class Page and PageController to be without namespace -->
    <rule ref="PSR1.Classes.ClassDeclaration.MissingNamespace">
        <exclude-pattern>Page\.php</exclude-pattern>
        <exclude-pattern>PageController\.php</exclude-pattern>
    </rule>

    <!-- Ensures that arrays are indented one tab stop -->
    <rule ref="Generic.Arrays.ArrayIndent"/>
    <!-- Makes sure that any use of double quotes strings are warranted -->
    <rule ref="Squiz.Strings.DoubleQuoteUsage"/>
    <!-- Require one space after casting -->
    <rule ref="Generic.Formatting.SpaceAfterCast">
        <properties>
            <property name="spacing" value="1" />
        </properties>
    </rule>

    <!-- All "use" statements must be used in the code. -->
    <rule ref="./vendor/slevomat/coding-standard/SlevomatCodingStandard/ruleset.xml">
        <!-- Multi or single line are both fine. Feel free to remove this exclusion if you prefer to enforce single line where they're possible -->
        <exclude name="SlevomatCodingStandard.Commenting.RequireOneLineDocComment.MultiLineDocComment"/>
        <exclude name="SlevomatCodingStandard.Commenting.DisallowOneLinePropertyDocComment.OneLinePropertyComment"/>
        <!-- We're not punishing folks for adding annotations (even if the method is self documenting) -->
        <exclude name="SlevomatCodingStandard.TypeHints.ReturnTypeHint.UselessAnnotation"/>
        <!-- There is actually a bug with this sniffer. If you use doc annotation to disable a rule, this sniffer (sometimes) throws an "Undefined index" error -->
        <exclude name="SlevomatCodingStandard.Commenting.DisallowCommentAfterCode.DisallowedCommentAfterCode"/>
        <!-- Late Static Binding is used often in SS -->
        <exclude name="SlevomatCodingStandard.Classes.DisallowLateStaticBindingForConstants"/>
        <!-- Multiline comments is what we use as a standard in SS -->
        <exclude name="SlevomatCodingStandard.Commenting.RequireOneLinePropertyDocComment"/>
        <!-- We don't require Yoda comparisons in this project -->
        <exclude name="SlevomatCodingStandard.ControlStructures.RequireYodaComparison.RequiredYodaComparison"/>
        <!-- It's quite common when extended base SS methods or extension points, that there are unused params -->
        <exclude name="SlevomatCodingStandard.Functions.UnusedParameter"/>
        <!-- There are two rules which conflict. NewWithoutParentheses and UselessParentheses. One must be disabled -->
        <!-- We allow new Class(); rather than new Class;-->
        <exclude name="SlevomatCodingStandard.ControlStructures.NewWithoutParentheses"/>
        <!-- Do not require fully qualified class names in annotation -->
        <exclude name="SlevomatCodingStandard.Namespaces.FullyQualifiedExceptions"/>
        <exclude name="SlevomatCodingStandard.Namespaces.FullyQualifiedClassNameInAnnotation.NonFullyQualifiedClassName"/>
        <exclude name="SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalConstants"/>
        <exclude name="SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalFunctions.NonFullyQualified"/>
        <!-- We generally allow the use of any namespace -->
        <exclude name="SlevomatCodingStandard.Namespaces.UseOnlyWhitelistedNamespaces"/>
        <!-- Often not possible when extending base classes from Silverstripe -->
        <exclude name="SlevomatCodingStandard.TypeHints.DeclareStrictTypes"/>
        <!-- Using mixed type is a way to get around the fact that we often cannot strictly type our methods if we -->
        <!-- are extending a base SS method -->
        <exclude name="SlevomatCodingStandard.TypeHints.DisallowMixedTypeHint"/>
        <!-- Array type hint syntax is very useful -->
        <exclude name="SlevomatCodingStandard.TypeHints.DisallowArrayTypeHintSyntax"/>
        <!-- Allow private static -->
        <exclude name="SlevomatCodingStandard.Classes.UnusedPrivateElements.UnusedProperty"/>
        <!-- Even if you strictly type, there are other reasons to add a DocComment (EG: to add @codeCoverageIgnore -->
        <exclude name="SlevomatCodingStandard.TypeHints.UselessConstantTypeHintSniff.UselessDocComment"/>
        <!-- Even if you strictly type, there are other reasons to add a DocComment (EG: to add @codeCoverageIgnore -->
        <exclude name="SlevomatCodingStandard.Commenting.UselessFunctionDocComment.UselessDocComment"/>
        <!-- No need to namespace global functions  -->
        <exclude name="SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalFunctions.NonFullyQualified"/>
        <!-- Inline doc comments are fine. We use them all the time to describe things like $dataList->first() -->
        <exclude name="SlevomatCodingStandard.PHP.RequireExplicitAssertion.RequiredExplicitAssertion"/>
        <!-- Allow "useless" annotations -->
        <exclude name="SlevomatCodingStandard.TypeHints.ParameterTypeHint.UselessAnnotation"/>
        <exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint.UselessAnnotation"/>
        <!-- Use named arguments if appropriate -->
        <exclude name="SlevomatCodingStandard.Functions.DisallowNamedArguments.DisallowedNamedArgument"/>
        <!-- We don't require arrow function -->
        <exclude name="SlevomatCodingStandard.Functions.RequireArrowFunction.RequiredArrowFunction"/>
        <!-- Allows us to use $var++ and $var\-\- to increment/decrement -->
        <exclude name="SlevomatCodingStandard.Operators.DisallowIncrementAndDecrementOperators" />
        <!-- It is acceptable within Silverstripe to pass by reference for extension hooks -->
        <exclude name="SlevomatCodingStandard.PHP.DisallowReference.DisallowedPassingByReference"/>
        <exclude name="SlevomatCodingStandard.PHP.DisallowReference.DisallowedInheritingVariableByReference"/>
        <!-- Ternary shorthand is acceptable -->
        <exclude name="SlevomatCodingStandard.ControlStructures.DisallowShortTernaryOperator.DisallowedShortTernaryOperator"/>
        <exclude name="SlevomatCodingStandard.ControlStructures.RequireMultiLineTernaryOperator.MultiLineTernaryOperatorNotUsed"/>
        <!-- SS typically uses superfluous suffixes -->
        <exclude name="SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming.SuperfluousSuffix"/>
        <exclude name="SlevomatCodingStandard.Classes.SuperfluousExceptionNaming.SuperfluousSuffix"/>
        <exclude name="SlevomatCodingStandard.Classes.SuperfluousTraitNaming.SuperfluousSuffix"/>
        <exclude name="SlevomatCodingStandard.Classes.SuperfluousAbstractClassNaming.SuperfluousPrefix"/>
        <!-- Global constants and exceptions do not need to be fully qualified -->
        <exclude name="SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalConstants.NonFullyQualified"/>
        <exclude name="SlevomatCodingStandard.Namespaces.FullyQualifiedExceptions.NonFullyQualifiedException"/>
        <!-- Don't require literal numeric seperator (EG: 1_000 to represent 1000) -->
        <exclude name="SlevomatCodingStandard.Numbers.RequireNumericLiteralSeparator.RequiredNumericLiteralSeparator"/>
        <exclude name="PSR1.Files.SideEffects.FoundWithSymbols"/>
        <!-- Allow use of superglobals -->
        <exclude name="SlevomatCodingStandard.Variables.DisallowSuperGlobalVariable.DisallowedSuperGlobalVariable"/>
        <!-- We do not require trailing commas on multiline methods. Both rules disabled, as we'll allow folks to -->
        <!-- add them if they want them, but we don't enforce either way -->
        <exclude name="SlevomatCodingStandard.Functions.TrailingCommaInCall.MissingTrailingComma"/>
        <exclude name="SlevomatCodingStandard.Functions.RequireTrailingCommaInCall.MissingTrailingComma"/>
        <exclude name="SlevomatCodingStandard.Functions.DisallowTrailingCommaInCall.DisallowedTrailingComma"/>
        <exclude name="SlevomatCodingStandard.Functions.RequireTrailingCommaInDeclaration.MissingTrailingComma"/>
        <exclude name="SlevomatCodingStandard.Functions.DisallowTrailingCommaInDeclaration.DisallowedTrailingComma"/>
        <exclude name="SlevomatCodingStandard.Functions.RequireTrailingCommaInClosureUse.MissingTrailingComma"/>
        <exclude name="SlevomatCodingStandard.Functions.DisallowTrailingCommaInClosureUse.DisallowedTrailingComma"/>
        <!-- Length does not determine complexity. We do not care if methods or files are long -->
        <exclude name="SlevomatCodingStandard.Functions.FunctionLength.FunctionLength"/>
        <exclude name="SlevomatCodingStandard.Files.FunctionLength.FunctionLength"/>
        <exclude name="SlevomatCodingStandard.Files.FileLength.FileTooLong"/>
        <exclude name="SlevomatCodingStandard.Classes.ClassLength.ClassTooLong"/>
        <!-- We'll determine what we think is too complex -->
        <exclude name="SlevomatCodingStandard.Complexity.Cognitive.ComplexityTooHigh"/>
        <!-- We can't declare classes as abstract/final because we have plenty of instances where classes are both -->
        <!-- used themselves, and also extended (EG: almost all of our DataObjects) -->
        <exclude name="SlevomatCodingStandard.Classes.RequireAbstractOrFinal.ClassNeitherAbstractNorFinal"/>
        <!-- There are two conflicting rules. We have to pick one. We've opted to *allow* Catches that do not use -->
        <!-- the Exception that was thrown (EG: We might be returning some other message) -->
        <exclude name="SlevomatCodingStandard.Exceptions.DisallowNonCapturingCatch.DisallowedNonCapturingCatch"/>
        <!-- We need to decide if we're specifically going to allow (and enforce) null safe object operators or not -->
        <!-- We've opted to enforce them -->
        <exclude name="SlevomatCodingStandard.ControlStructures.DisallowNullSafeObjectOperator.DisallowedNullSafeObjectOperator"/>
        <!-- By default, we require property promotion -->
        <exclude name="SlevomatCodingStandard.Classes.DisallowConstructorPropertyPromotion.DisallowedConstructorPropertyPromotion"/>
        <!-- Allow arrays with keys to be non-alphabetically sorted, e.g. $db arrays are often ordered specifically by how they appear in the CMS -->
        <exclude name="SlevomatCodingStandard.Arrays.AlphabeticallySortedByKeys.IncorrectKeyOrder"/>
        <!-- Self refers to the class where the call was written, and can cause errors if the method lives on a class other than where it was called -->
        <exclude name="SlevomatCodingStandard.Classes.RequireSelfReference.RequiredSelfReference"/>
        <!-- We add traversable types where they are clear -->
        <exclude name="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingTraversableTypeHintSpecification"/>
        <exclude name="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingTraversableTypeHintSpecification"/>
        <exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingTraversableTypeHintSpecification"/>
    </rule>

    <rule ref="SlevomatCodingStandard.Namespaces.UnusedUses">
        <properties>
            <property name="searchAnnotations" type="bool" value="true"/>
            <property name="ignoredAnnotationNames" type="array" value="@config"/>
        </properties>
    </rule>

    <rule ref="SlevomatCodingStandard.Files.TypeNameMatchesFileName">
        <properties>
            <!-- Set the root namespace for our src dir and phpunit dir. Please change these as required -->
            <property name="rootNamespaces" type="array" value="src=>SilverStripe\DiscovererBifrost,tests=>SilverStripe\DiscovererBifrost\Tests"/>
            <property name="ignoredNamespaces" type="array" value="Slevomat\Services"/>
        </properties>
    </rule>

    <rule ref="SlevomatCodingStandard.ControlStructures.JumpStatementsSpacing">
        <properties>
            <property name="linesCountAfterWhenLastInCaseOrDefault" value="1"/>
            <property name="linesCountAfterWhenLastInLastCaseOrDefault" value="0"/>
        </properties>
    </rule>
</ruleset>