ENGCOM-6920: Reflection: Fix null as first return type #25806

 - Merge Pull Request #25806 from Parakoopa/magento2:nullable-api-getters
 - Merged commits:
   1. 0cea191
   2. 99a1a98
   3. 253f881
   4. 7e3390d

Author: magento-engcom-team

lib/internal/Magento/Framework/Reflection/Test/Unit/Fixture/TSample.php

@@ -22,4 +22,20 @@ public function getName()
     {
         return '';
     }
+
+    /**
+     * @inheritdoc
+     */
+    public function getWithNull()
+    {
+        return null;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getOnlyNull()
+    {
+        return null;
+    }
 }

lib/internal/Magento/Framework/Reflection/Test/Unit/Fixture/TSampleInterface.php

@@ -18,4 +18,16 @@ public function getPropertyName();
      * Doc block without return tag.
      */
     public function getName();
+
+    /**
+     * return annotation with a null type at first position
+     * @return null|string
+     */
+    public function getWithNull();
+
+    /**
+     * return annotation with only null type
+     * @return null
+     */
+    public function getOnlyNull();
 }

lib/internal/Magento/Framework/Reflection/Test/Unit/TypeProcessorTest.php

@@ -364,6 +364,25 @@ public function testGetReturnTypeWithoutReturnTag()
         $this->typeProcessor->getGetterReturnType($methodReflection);
     }
 
+    /**
+     * Checks a case when method return annotation has a null-type at first position,
+     * and a valid type at second.
+     */
+    public function testGetReturnTypeNullAtFirstPos()
+    {
+        $expected = [
+            'type' => 'string',
+            'isRequired' => false,
+            'description' => null,
+            'parameterCount' => 0
+        ];
+
+        $classReflection = new ClassReflection(TSample::class);
+        $methodReflection = $classReflection->getMethod('getWithNull');
+
+        self::assertEquals($expected, $this->typeProcessor->getGetterReturnType($methodReflection));
+    }
+
     /**
      * Simple and complex data provider
      *

lib/internal/Magento/Framework/Reflection/TypeProcessor.php

@@ -286,7 +286,14 @@ public function getGetterReturnType($methodReflection)
     {
         $returnAnnotation = $this->getMethodReturnAnnotation($methodReflection);
         $types = $returnAnnotation->getTypes();
-        $returnType = current($types);
+        $returnType = null;
+        foreach ($types as $type) {
+            if ($type !== 'null') {
+                $returnType = $type;
+                break;
+            }
+        }
+
         $nullable = in_array('null', $types);
 
         return [
@@ -312,6 +319,7 @@ public function getExceptions($methodReflection)
             if (is_array($throwsTypes)) {
                 /** @var $throwsType \Zend\Code\Reflection\DocBlock\Tag\ThrowsTag */
                 foreach ($throwsTypes as $throwsType) {
+                    // phpcs:ignore
                     $exceptions = array_merge($exceptions, $throwsType->getTypes());
                 }
             }
@@ -513,13 +521,15 @@ public function getParamType(ParameterReflection $param)
     {
         $type = $param->detectType();
         if ($type === 'null') {
-            throw new \LogicException(sprintf(
-                '@param annotation is incorrect for the parameter "%s" in the method "%s:%s".'
-                . ' First declared type should not be null. E.g. string|null',
-                $param->getName(),
-                $param->getDeclaringClass()->getName(),
-                $param->getDeclaringFunction()->name
-            ));
+            throw new \LogicException(
+                sprintf(
+                    '@param annotation is incorrect for the parameter "%s" in the method "%s:%s".'
+                    . ' First declared type should not be null. E.g. string|null',
+                    $param->getName(),
+                    $param->getDeclaringClass()->getName(),
+                    $param->getDeclaringFunction()->name
+                )
+            );
         }
         if ($type === 'array') {
             // try to determine class, if it's array of objects