PHPCS-267 Add a warning against the mixed return type

Signed-off-by: Björn Lange <[email protected]>

Author: b3nl

README.md

@@ -135,9 +135,6 @@ The base for the BestIt Standard is [PSR-12](https://github.com/php-fig/fig-stan
 | BestIt.DocTags.RequiredMethodTags.TagOccurrenceMin | You MUST provide the required tags. The error is registered for every tag specifically. | no |
 | BestIt.DocTags.RequiredPropertyTags.TagOccurrenceMax | You MUST provide only the maximum amount of required tags. For example, only one return per method is allowed. The error is registered for every tag specifically. | no |
 | BestIt.DocTags.RequiredPropertyTags.TagOccurrenceMin | You MUST provide the required tags. The error is registered for every tag specifically. | no |
-| BestIt.DocTags.ReturnTag.MissingReturnDescription | You SHOULD provide a description your return. | no |
-| BestIt.DocTags.ReturnTag.MixedType | You SHOULD provide a native return and prevent "mixed". | no |
-| BestIt.DocTags.ReturnTag.TagContentFormatInvalid | You MUST provide a special tag format. | no |
 | BestIt.DocTags.TagSorting.MissingNewlineBetweenTags | You SHOULD separate tag groups and the final return with a newline. | yes by class |
 | BestIt.DocTags.TagSorting.WrongTagSorting | You SHOULD sort the tags by their occurrence and then alphabetically, but @return SHOULD be the last. | yes by class |
 | BestIt.DocTags.ThrowsTag.MissingThrowDescription | You SHOULD provide a description your throw tag. | no |
@@ -187,6 +184,7 @@ The base for the BestIt Standard is [PSR-12](https://github.com/php-fig/fig-stan
 | BestIt.TypeHints.PropertyTypeHint.MissingAnyTypeHint | MUST have any type hint if possible. | yes |
 | BestIt.TypeHints.PropertyTypeHint.MissingNativeTypeHint | MUST have a native type hint (matching the doc block.) | yes |
 | BestIt.TypeHints.ReturnTypeDeclaration.MissingReturnTypeHint | Every function or method MUST have a type hint if the return annotation is valid. | yes |
+| BestIt.TypeHints.SuggestExplicitReturnType.MixedType | You SHOULD not use a mixed type but an explicit native return type. | yes |
 | Generic.Formatting.SpaceAfterCast | There MUST be a space after cast. |
 | Generic.Arrays.DisallowLongArraySyntax | Every array syntax MUST be in short array syntax. |
 | SlevomatCodingStandard.Classes.ClassConstantVisibility.MissingConstantVisibility | Constants MUST be marked with a visibility. |

src/Standards/BestIt/Sniffs/DocTags/ReturnTagSniff.php

@@ -8,11 +8,10 @@
 use BestIt\CodeSniffer\CodeWarning;
 use BestIt\Sniffs\AbstractSniff;
 use BestIt\Sniffs\DocPosProviderTrait;
-use BestIt\Sniffs\FunctionRegistrationTrait;
 use BestIt\Sniffs\SuppressingTrait;
-use SlevomatCodingStandard\Helpers\Annotation;
 use SlevomatCodingStandard\Helpers\Annotation\ReturnAnnotation;
 use SlevomatCodingStandard\Helpers\FunctionHelper;
+use SlevomatCodingStandard\Helpers\TokenHelper;
 use SlevomatCodingStandard\Helpers\TypeHintHelper;
 use function array_filter;
 use function array_intersect;
@@ -23,6 +22,7 @@
 use function strtolower;
 use function substr;
 use function version_compare;
+use const T_FUNCTION;
 
 /**
  * Class ReturnTypeDeclarationSniff
@@ -33,7 +33,6 @@
 class ReturnTypeDeclarationSniff extends AbstractSniff
 {
     use DocPosProviderTrait;
-    use FunctionRegistrationTrait;
     use SuppressingTrait;
 
     /**
@@ -114,13 +113,12 @@ private function addReturnType(): void
 
     /**
      * Returns true if this sniff may run.
-     *
      * @return bool
      */
     protected function areRequirementsMet(): bool
     {
         return !$this->isSniffSuppressed(static::CODE_MISSING_RETURN_TYPE) && !$this->hasReturnType() &&
-            !in_array($this->getFunctionName(), $this->methodsWithoutVoid);
+            $this->token['code'] === T_FUNCTION && !in_array($this->getFunctionName(), $this->methodsWithoutVoid);
     }
 
     /**
@@ -309,7 +307,7 @@ private function loadFunctionName(): string
     /**
      * Loads the return annotation for this method.
      *
-     * @return null\ReturnAnnotation
+     * @return null|ReturnAnnotation
      */
     protected function loadReturnAnnotation(): ?ReturnAnnotation
     {
@@ -337,8 +335,13 @@ protected function processToken(): void
         }
     }
 
+    public function register(): array
+    {
+        return TokenHelper::$functionTokenCodes;
+    }
+
     /**
-     * Sets up the test.
+     * Sets up the sniff.
      *
      * @return void
      */

src/Standards/BestIt/Sniffs/TypeHints/ReturnTypeDeclarationSniff.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BestIt\Sniffs\TypeHints;
+
+use BestIt\CodeSniffer\CodeWarning;
+use BestIt\Sniffs\AbstractSniff;
+use BestIt\Sniffs\SuppressingTrait;
+use SlevomatCodingStandard\Helpers\FunctionHelper;
+use SlevomatCodingStandard\Helpers\TokenHelper;
+use SlevomatCodingStandard\Helpers\TypeHint;
+
+class SuggestExplicitReturnTypeSniff extends AbstractSniff
+{
+    use SuppressingTrait;
+
+    public const CODE_MIXED_TYPE = 'MixedType';
+
+    private const MESSAGE_MIXED_TYPE = 'We suggest that you avoid the "mixed" type and declare the ' .
+        'required types in detail.';
+
+    private function isMixedTypeHint(): bool
+    {
+        $typeHint = FunctionHelper::findReturnTypeHint($this->getFile(), $this->getStackPos());
+
+        return ($typeHint instanceof TypeHint) && ($typeHint->getTypeHint() === 'mixed');
+    }
+
+    protected function processToken(): void
+    {
+        if ($this->isMixedTypeHint() && !$this->isSniffSuppressed(self::CODE_MIXED_TYPE)) {
+            throw (new CodeWarning(static::CODE_MIXED_TYPE, self::MESSAGE_MIXED_TYPE, $this->stackPos))
+                ->setToken($this->token);
+        }
+    }
+
+    public function register(): array
+    {
+        return TokenHelper::$functionTokenCodes;
+    }
+}

src/Standards/BestIt/Sniffs/TypeHints/SuggestExplicitReturnTypeSniff.php

@@ -10,6 +10,16 @@ public function __construct()
         // Do nothing.
     }
 
+    /**
+     * Returns true if there is a matching tag.
+     *
+     * @return bool
+     */
+    protected function areRequirementsMet(): bool
+    {
+        return false;
+    }
+
     /**
      * @return bool
      */