symfony
diff --git a/‎src/Symfony/Component/Debug/DebugClassLoader.php
Lines changed: 179 additions & 0 deletions b/‎src/Symfony/Component/Debug/DebugClassLoader.php
Lines changed: 179 additions & 0 deletions
@@ -27,6 +27,32 @@
  */
 class DebugClassLoader
 {
+    private const COMMON_NON_OBJECT_RETURNED_TYPES = [
+        'false',
+        'mixed',
+        'null',
+        'resource',
+        'static',
+        'true',
+        '$this'
+    ];
+
+    private const NON_NULLABLE_RETURNABLE_TYPES = [
+        'void' => '"void"',
+    ];
+
+    private const NULLABLE_RETURNABLE_TYPES = [
+        'array' => 'an array',
+        'bool' => 'a boolean',
+        'callable' => 'a callable',
+        'float' => 'a float',
+        'int' => 'an integer',
+        'iterable' => 'an iterable',
+        'object' => 'an object',
+        'string' => 'a string',
+        'self' => 'an instance of itself',
+    ];
+
     private $classLoader;
     private $isFinder;
     private $loaded = [];
@@ -40,6 +66,7 @@ class DebugClassLoader
     private static $annotatedParameters = [];
     private static $darwinCache = ['/' => ['/', []]];
     private static $method = [];
+    private static $returnTypes = [];
 
     public function __construct(callable $classLoader)
     {
@@ -309,6 +336,8 @@ public function checkAnnotations(\ReflectionClass $refl, $class)
             }
         }
 
+        $this->checkReturnTypes($class, $parent, $refl, $ns, $len, $deprecations);
+
         if (\trait_exists($class)) {
             return $deprecations;
         }
@@ -372,6 +401,8 @@ public function checkAnnotations(\ReflectionClass $refl, $class)
                 }
             }
 
+            $this->saveReturnType($class, $method, $doc);
+
             if ($finalOrInternal || $method->isConstructor() || false === \strpos($doc, '@param') || StatelessInvocation::class === $class) {
                 continue;
             }
@@ -522,4 +553,152 @@ private function getOwnInterfaces($class, $parent)
 
         return $ownInterfaces;
     }
+
+    private function saveReturnType(string $class, \ReflectionMethod $method, string $doc): void
+    {
+        if ($method->getReturnType() instanceof \ReflectionType) {
+            return;
+        }
+
+        if (false === \strpos($doc, 'return')) {
+            return;
+        }
+
+        if (!preg_match_all('/\n\s+\* @return +(\S+)/', $doc,$matches, PREG_SET_ORDER)) {
+            return;
+        }
+
+        $types = explode('|', end($matches)[1], 3);
+
+        $nullable = false;
+
+        switch (count($types)) {
+            case 1:
+                $type = $types[0];
+
+                break;
+            case 2:
+                // fastest way to handle the null|null edge case
+                $type = 'null';
+
+                foreach (array_unique(array_map([$this, 'normalizeType'], $types)) as $i => $normalizedType) {
+                    if ('null' === $normalizedType) {
+                        $nullable = true;
+                    } else {
+                        $type = $types[$i];
+                    }
+                }
+
+                if (!$nullable) {
+                    return;
+                }
+
+                break;
+            default:
+                return;
+        }
+
+        $normalizedType = $this->normalizeType($type);
+        if (in_array($normalizedType, self::COMMON_NON_OBJECT_RETURNED_TYPES)) {
+            return;
+        }
+
+        if (isset(self::NULLABLE_RETURNABLE_TYPES[$normalizedType])) {
+            $normalizedDocReturnType = self::NULLABLE_RETURNABLE_TYPES[$normalizedType];
+            $hintedReturnType = $normalizedType;
+        } elseif (isset(self::NON_NULLABLE_RETURNABLE_TYPES[$normalizedType])) {
+            if ($nullable) {
+                return;
+            }
+
+            $normalizedDocReturnType = self::NON_NULLABLE_RETURNABLE_TYPES[$normalizedType];
+            $hintedReturnType = $normalizedType;
+        } else {
+            $normalizedDocReturnType = sprintf('an instance of "%s"', $type);
+            $hintedReturnType = $type;
+        }
+
+        if ($nullable) {
+            $normalizedDocReturnType .= ' or null';
+            $hintedReturnType = '?'.$hintedReturnType;
+        }
+
+        self::$returnTypes[$class][$method->name] = [$normalizedDocReturnType, $hintedReturnType];
+    }
+
+    /**
+     * @param string $class
+     * @param string|false $parent
+     * @param \ReflectionClass $refl
+     * @param string $ns
+     * @param int $len
+     * @param array $deprecations
+     */
+    private function checkReturnTypes(string $class, $parent, \ReflectionClass $refl, string $ns, int $len, &$deprecations): void
+    {
+        $parentsAndInterfacesThatHaveMethodsThatReturnsADocType = [];
+        foreach (array_merge($parent ? array_merge([$parent], class_parents($parent, false)) : [], class_implements($class, false)) as $use) {
+            if (isset(self::$returnTypes[$use]) && 0 !== \strncmp($ns, \str_replace('_', '\\', $use), $len)) {
+                $parentsAndInterfacesThatHaveMethodsThatReturnsADocType[] = $use;
+            }
+        }
+
+        if (empty($parentsAndInterfacesThatHaveMethodsThatReturnsADocType)) {
+            return;
+        }
+
+        foreach ($refl->getMethods(\ReflectionMethod::IS_PUBLIC | \ReflectionMethod::IS_PROTECTED) as $method) {
+            if ($method->class !== $class || $method->getReturnType() instanceof \ReflectionType) {
+                continue;
+            }
+
+            foreach ($parentsAndInterfacesThatHaveMethodsThatReturnsADocType as $name) {
+                if (!isset(self::$returnTypes[$name][$method->name])) {
+                    continue;
+                }
+
+                list($normalizedDocReturnType, $hintedReturnType) = self::$returnTypes[$name][$method->name];
+                $deprecations[] = sprintf(
+                    'The "%s::%s()" parent method returns %s. You could safely add the ": %s" return type to your method to be compatible with the next major version of its parent.',
+                    $class,
+                    $method->name,
+                    $normalizedDocReturnType,
+                    $hintedReturnType
+                );
+
+                break;
+            }
+        }
+    }
+
+    private function normalizeType(string $type): string
+    {
+        $lcType = mb_strtolower($type);
+
+        if (
+            isset(self::NULLABLE_RETURNABLE_TYPES[$lcType]) ||
+            isset(self::NON_NULLABLE_RETURNABLE_TYPES[$lcType]) ||
+            isset(self::COMMON_NON_OBJECT_RETURNED_TYPES[$lcType]))
+        {
+            return $lcType;
+        }
+
+        if ('[]' === substr($lcType, -2)) {
+            return 'array';
+        }
+
+        if ('integer' === $lcType) {
+            return 'int';
+        }
+
+        if ('boolean' === $lcType) {
+            return 'bool';
+        }
+
+        if (1 === preg_match('/^callable *\(/', $lcType)) {
+            return 'callable';
+        }
+
+        return $lcType;
+    }
 }