phpcs.xml.dist

<?xml version="1.0" ?>
<ruleset name="Web Stories PHP Coding Standards Rules">
  <config name="minimum_supported_wp_version" value="6.5" />

  <rule ref="WordPress-Core">
    <type>error</type>
    <exclude name="Universal.Arrays.DisallowShortArraySyntax" />
    <exclude name="Universal.Operators.DisallowShortTernary" />
    <exclude
      name="WordPress.NamingConventions.ValidPostTypeSlug.NotStringLiteral"
    />
  </rule>

  <rule ref="PSR12.Files.FileHeader.IncorrectOrder">
    <exclude-pattern>*</exclude-pattern>
  </rule>

  <rule ref="WordPress-Docs">
    <type>error</type>
    <exclude-pattern>tests/*</exclude-pattern>
    <!-- Documentation is organized with the use of namespaces. -->
    <exclude name="Squiz.Commenting.FileComment.MissingPackageTag" />
    <exclude name="Squiz.Commenting.VariableComment.MissingVar" />
  </rule>

  <rule ref="WordPress-Extra">
    <type>error</type>
    <exclude name="WordPress.Files.FileName" />
    <exclude name="WordPress.Files.FileName.NotHyphenatedLowercase" />
  </rule>

  <rule ref="WordPress-VIP-Go">
    <type>error</type>
    <exclude-pattern>tests/*</exclude-pattern>
    <exclude
      name="WordPressVIPMinimum.Functions.RestrictedFunctions.flush_rewrite_rules_flush_rewrite_rules"
    />
  </rule>

  <rule ref="WordPress.Security.NonceVerification">
    <exclude-pattern>tests/*</exclude-pattern>
  </rule>

  <rule ref="WordPress.Security.EscapeOutput.OutputNotEscaped">
    <exclude-pattern>includes/Infrastructure/Injector/SimpleInjector.php</exclude-pattern>
  </rule>

  <rule ref="WordPress.WP.AlternativeFunctions">
     <exclude-pattern>tests/*</exclude-pattern>
  </rule>

  <rule ref="WordPress.WP.GlobalVariablesOverride.Prohibited">
    <exclude-pattern>tests/*</exclude-pattern>
  </rule>

  <rule ref="WordPress.WP.EnqueuedResources">
    <type>error</type>
    <exclude-pattern>tests/*</exclude-pattern>
  </rule>

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

  <rule ref="WordPress.NamingConventions.ValidVariableName">
    <properties>
      <property name="allowed_custom_properties" type="array">
        <element value="childNodes" />
        <element value="tagName" />
        <element value="textContent" />
        <element value="parentNode" />
        <element value="nodeType" />
        <element value="nodeName" />
        <element value="nextSibling" />
        <element value="previousSibling" />
        <element value="firstChild" />
        <element value="lastChild" />
        <element value="nodeValue" />
        <element value="ownerElement" />
        <element value="documentElement" />
        <element value="removeChild" />
        <element value="ownerDocument" />
        <element value="strictErrorChecking" />
        <element value="preserveWhiteSpace" />
      </property>
    </properties>
  </rule>

  <rule ref="VariableAnalysis.CodeAnalysis.VariableAnalysis" />

  <!-- Check for cross-version support for PHP 7.4 and higher. -->
  <config name="testVersion" value="7.4-" />
  <rule ref="PHPCompatibilityWP" />

  <!-- The main plugin file should be parsable by PHP 5.6. -->
  <rule ref="Generic.Arrays.DisallowLongArraySyntax.Found">
    <exclude-pattern>web-stories.php</exclude-pattern>
    <exclude-pattern
    >includes/compat/Web_Stories_Compatibility.php</exclude-pattern>
  </rule>

  <rule ref="WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid">
    <exclude-pattern
    >tests/phpunit/integration/includes/REST_Setup.php</exclude-pattern>
  </rule>

  <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint">
    <properties>
      <property name="enableStaticTypeHint" value="false" />
      <property name="enableMixedTypeHint" value="false" />
      <property name="enableUnionTypeHint" value="false" />
      <property name="enableIntersectionTypeHint" value="false" />
      <property name="enableStandaloneNullTrueFalseTypeHints" value="false" />
      <property name="enableNeverTypeHint" value="false" />
    </properties>

    <exclude
      name="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingTraversableTypeHintSpecification"
    />

    <!-- The main plugin file should be parsable by PHP 5.6. -->
    <exclude-pattern>web-stories.php</exclude-pattern>
    <exclude-pattern
    >includes/compat/Web_Stories_Compatibility.php</exclude-pattern>

    <!-- To ensure backward compatibility for developers using these. -->
    <exclude-pattern>includes/Interfaces/FieldState.php</exclude-pattern>
    <exclude-pattern>includes/Interfaces/FieldStateFactory.php</exclude-pattern>
    <exclude-pattern>includes/Renderer/Stories/*</exclude-pattern>
  </rule>

  <!-- Requires parameter typehints and reports useless @param annotations. -->
  <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint">
    <properties>
      <property name="enableMixedTypeHint" value="false" />
      <property name="enableUnionTypeHint" value="false" />
      <property name="enableIntersectionTypeHint" value="false" />
      <property name="enableStandaloneNullTrueFalseTypeHints" value="false" />
    </properties>

    <exclude
      name="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingTraversableTypeHintSpecification"
    />

    <!-- The main plugin file should be parsable by PHP 5.6. -->
    <exclude-pattern>web-stories.php</exclude-pattern>
    <exclude-pattern
    >includes/compat/Web_Stories_Compatibility.php</exclude-pattern>

    <!-- To ensure backward compatibility for developers using these. -->
    <exclude-pattern>includes/Interfaces/FieldState.php</exclude-pattern>
    <exclude-pattern>includes/Interfaces/FieldStateFactory.php</exclude-pattern>
    <exclude-pattern>includes/Renderer/Stories/*</exclude-pattern>

    <!-- Parent REST API controller classes in WP don't use parameter type hints, need to match their signature -->
    <exclude-pattern>includes/REST_API</exclude-pattern>

    <!-- Parent widget classes in WP don't use parameter type hints, need to match their signature -->
    <exclude-pattern>includes/Widgets</exclude-pattern>
  </rule>

  <!-- Checks whether the nullablity ? symbol is present before each nullable and optional parameter. -->
  <rule
    ref="SlevomatCodingStandard.TypeHints.NullableTypeForNullDefaultValue"
  />
  <!-- Enforce no space between closing brace and colon of return typehint. -->
  <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHintSpacing">
    <properties>
      <property name="spacesCountBeforeColon" value="0" />
    </properties>
  </rule>
  <!-- Checks that there's no whitespace between a nullability symbol and a typehint. -->
  <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHintSpacing" />
  <!-- Enforces using shorthand scalar typehint variants in phpDocs. -->
  <rule ref="SlevomatCodingStandard.TypeHints.LongTypeHints" />
  <!-- Reports useless @var annotation for constants because the type of constant is always clear. -->
  <rule ref="SlevomatCodingStandard.TypeHints.UselessConstantTypeHint" />

  <rule ref="SlevomatCodingStandard.TypeHints.DeclareStrictTypes">
      <exclude-pattern>web-stories.php</exclude-pattern>
      <exclude-pattern>includes/compat/*</exclude-pattern>
      <exclude-pattern>includes/templates/*</exclude-pattern>
  </rule>

  <rule ref="SlevomatCodingStandard.TypeHints.PropertyTypeHint">
      <exclude-pattern>web-stories.php</exclude-pattern>
      <exclude-pattern>includes/compat/*</exclude-pattern>
       <properties>
        <property name="enableMixedTypeHint" value="false" />
        <property name="enableUnionTypeHint" value="false" />
        <property name="enableIntersectionTypeHint" value="false" />
        <property name="enableStandaloneNullTrueFalseTypeHints" value="false" />
      </properties>
  </rule>

  <rule ref="SlevomatCodingStandard.Numbers.RequireNumericLiteralSeparator">
      <properties>
        <property name="minDigitsAfterDecimalPoint" value="3" />
        <property name="minDigitsBeforeDecimalPoint" value="6" />
      </properties>
  </rule>
  <!-- Disallows grouped use declarations. -->
  <rule ref="SlevomatCodingStandard.Namespaces.DisallowGroupUse" />
  <!-- Disallows leading backslash in use statement. -->
  <rule ref="SlevomatCodingStandard.Namespaces.UseDoesNotStartWithBackslash" />
  <!-- Checks whether uses at the top of a file are alphabetically sorted. -->
  <rule ref="SlevomatCodingStandard.Namespaces.AlphabeticallySortedUses" />
  <!-- Enforces one space after namespace, disallows content between namespace name and semicolon and disallows use of bracketed syntax. -->
  <rule ref="SlevomatCodingStandard.Namespaces.NamespaceDeclaration" />
  <!-- Prohibits multiple uses separated by commas. -->
  <rule ref="SlevomatCodingStandard.Namespaces.MultipleUsesPerLine" />
  <!-- Enforces one blank line before and after namespace. -->
  <rule ref="SlevomatCodingStandard.Namespaces.NamespaceSpacing">
    <properties>
      <property name="linesCountBeforeNamespace" value="1" />
      <property name="linesCountAfterNamespace" value="1" />
    </properties>
  </rule>
  <!-- Enforces one blank before first use, after last use and none between two different types of use. -->
  <rule ref="SlevomatCodingStandard.Namespaces.UseSpacing">
    <properties>
      <property name="linesCountBeforeFirstUse" value="1" />
      <property name="linesCountBetweenUseTypes" value="0" />
      <property name="linesCountAfterLastUse" value="1" />
    </properties>
  </rule>
  <!-- All references to functions, classes and constants should import using a use statement. -->
  <rule ref="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly">
     <properties>
        <property name="allowFullyQualifiedGlobalFunctions" value="true" />
        <property name="allowFullyQualifiedGlobalClasses" value="true" />
        <property name="allowFullyQualifiedGlobalConstants" value="true" />
        <property name="allowFallbackGlobalFunctions" value="true" />
        <property name="allowFallbackGlobalConstants" value="true" />
        <property
        name="allowFullyQualifiedNameForCollidingClasses"
        value="true"
      />
    </properties>
  </rule>
  <!-- Prohibits uses from the same namespace. -->
  <rule ref="SlevomatCodingStandard.Namespaces.UseFromSameNamespace" />
  <!-- Looks for unused imports from other namespaces. -->
  <rule ref="SlevomatCodingStandard.Namespaces.UnusedUses">
    <properties>
      <property name="searchAnnotations" value="true" />
    </properties>
  </rule>
  <!-- Require root namespace for special compiled PHP functions. -->
  <rule ref="SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalFunctions">
    <properties>
      <property name="includeSpecialFunctions" value="true" />
    </properties>
  </rule>

  <!-- Requires arrow functions if possible. -->
  <rule ref="SlevomatCodingStandard.Functions.RequireArrowFunction" />
  <!-- Enforces correct space usage in array functions. -->
  <rule ref="SlevomatCodingStandard.Functions.ArrowFunctionDeclaration">
    <properties>
      <property name="spacesCountAfterKeyword" value="0" />
      <property name="spacesCountBeforeArrow" value="1" />
      <property name="spacesCountAfterArrow" value="1" />
      <property name="allowMultiLine" value="true" />
    </properties>
  </rule>
  <rule ref="SlevomatCodingStandard.Functions.StaticClosure" />

  <rule ref="SlevomatCodingStandard.PHP">
    <exclude name="SlevomatCodingStandard.PHP.RequireExplicitAssertion" />
    <exclude name="SlevomatCodingStandard.PHP.DisallowReference" />
  </rule>

  <!-- Class names should be referenced via ::class constant when possible. -->
  <rule ref="SlevomatCodingStandard.Classes.ModernClassNameReference">
    <properties>
      <property name="enableOnObjects" value="false" />
    </properties>
  </rule>

  <!-- Requires declaring visibility for class constants. -->
  <rule ref="SlevomatCodingStandard.Classes.ClassConstantVisibility" />

  <rule ref="SlevomatCodingStandard.Classes.ClassStructure">
    <properties>
      <property name="groups" type="array">
        <element value="uses" />

        <element value="enum cases" />

        <!-- Public constants are first but you don't care about the order of protected or private constants -->
        <element value="public constants" />
        <element value="constants" />

        <!-- You don't care about the order among the properties. The same can be done with "properties" shortcut -->
        <element
          value="public static properties, protected static properties, private static properties"
        />
        <element
          value="public properties, protected properties, private properties"
        />

        <!-- Constructor is first, then all public methods, then protected/private methods and magic methods are last -->
        <element value="constructor" />
        <element value="all public methods" />
        <element value="methods" />
        <element value="magic methods" />
      </property>
    </properties>
  </rule>

  <rule ref="SlevomatCodingStandard.Variables">
    <exclude
      name="SlevomatCodingStandard.Variables.DisallowSuperGlobalVariable"
    />
  </rule>

  <!-- Enforces maximum cognitive complexity for functions.. -->
  <rule ref="SlevomatCodingStandard.Complexity.Cognitive">
    <properties>
      <property name="maxComplexity" value="25" />
    </properties>
  </rule>

  <!-- Requires use of null coalesce operator (??) when possible. -->
  <rule
    ref="SlevomatCodingStandard.ControlStructures.RequireNullCoalesceOperator"
  />

  <!-- Reports forbidden annotations. -->
  <rule ref="SlevomatCodingStandard.Commenting.ForbiddenAnnotations">
    <properties>
      <property name="forbiddenAnnotations" type="array">
        <element value="@package" />
        <element value="@subpackage" />
        <element value="@author" />
        <element value="@created" />
        <element value="@access" />
        <element value="@version" />
      </property>
    </properties>
  </rule>
  <!-- Require specific order of PHPDoc annotations with empty newline between specific groups. -->
  <rule ref="SlevomatCodingStandard.Commenting.DocCommentSpacing">
    <properties>
      <property name="linesCountBeforeFirstContent" value="0" />
      <property name="linesCountAfterLastContent" value="0" />
      <property name="linesCountBetweenDescriptionAndAnnotations" value="1" />
      <property name="linesCountBetweenAnnotationsGroups" value="1" />
      <property name="annotationsGroups" type="array">
        <element
          value="
          @SuppressWarnings,
          @codeCoverageIgnore
        "
        />
        <element value="@internal" />
        <element value="
					@since,
					@deprecated,
				" />
        <element value="
					@link,
					@see,
					@uses,
				" />
        <element value="
					@global,
				" />
        <element value="
					@throws,
				" />
        <element value="
					@param,
					@return,
				" />
      </property>
    </properties>

    <!-- Prevent false positives for WordPress-style array annotations. -->
    <exclude
      name="SlevomatCodingStandard.Commenting.DocCommentSpacing.IncorrectAnnotationsGroup"
    />
  </rule>

  <!-- Show details about violated sniffs -->
  <arg value="s" />

  <!-- Iterate over all PHP files by default -->
  <arg name="extensions" value="php" />
  <file>.</file>

  <!-- Strip the filepaths down to the relevant bit. -->
  <arg name="basepath" value="./" />

  <!-- Check up to 20 files simultaneously. -->
  <arg name="parallel" value="20" />

  <!-- Third-party or auto-generated code -->
  <exclude-pattern>*/build/*</exclude-pattern>
  <exclude-pattern>*/data/*</exclude-pattern>
  <exclude-pattern>packages/e2e-tests/src/plugins/*</exclude-pattern>
  <exclude-pattern>*/node_modules/*</exclude-pattern>
  <exclude-pattern>*/third-party/*</exclude-pattern>
  <exclude-pattern>*/vendor/*</exclude-pattern>
  <exclude-pattern>assets/js/*.asset.php</exclude-pattern>
  <exclude-pattern>assets/js/*.chunks.php</exclude-pattern>
  <exclude-pattern>includes/polyfills/mbstring.php</exclude-pattern>
  <exclude-pattern>tests/phpstan/*</exclude-pattern>
  <exclude-pattern
  >tests/phpunit/unit/includes/MarkupComparison.php</exclude-pattern>
</ruleset>