Improving error messages

Author: Zheness

src/ControllerQueryProvider.php

@@ -117,8 +117,11 @@ private function getFieldsByAnnotations(string $annotationName): array
 
                 $phpdocType = $typeResolver->resolve((string) $refMethod->getReturnType());
 
-                $type = $this->mapType($phpdocType, $refMethod->getDocBlockReturnTypes(), $standardPhpMethod->getReturnType()->allowsNull(), false);
-
+                try {
+                    $type = $this->mapType($phpdocType, $refMethod->getDocBlockReturnTypes(), $standardPhpMethod->getReturnType()->allowsNull(), false);
+                } catch (TypeMappingException $e) {
+                    throw TypeMappingException::wrapWithReturnInfo($e, $refMethod);
+                }
                 $queryList[] = new QueryField($methodName, $type, $args, [$this->controller, $methodName], $this->hydrator);
             }
         }
@@ -174,9 +177,13 @@ private function mapParameters(ReflectionMethod $refMethod, \ReflectionMethod $s
             }
             $phpdocType = $typeResolver->resolve($type);
 
-            $arr = [
-                'type' => $this->mapType($phpdocType, $parameter->getDocBlockTypes(), $allowsNull, true),
-            ];
+            try {
+                $arr = [
+                    'type' => $this->mapType($phpdocType, $parameter->getDocBlockTypes(), $allowsNull, true),
+                ];
+            } catch (TypeMappingException $e) {
+                throw TypeMappingException::wrapWithParamInfo($e, $parameter);
+            }
 
             if ($standardParameter->allowsNull()) {
                 $arr['default'] = null;
@@ -207,8 +214,7 @@ private function mapType(Type $type, array $docBlockTypes, bool $isNullable, boo
             }
             $filteredDocBlockTypes = $this->typesWithoutNullable($docBlockTypes);
             if (empty($filteredDocBlockTypes)) {
-                // TODO: improve error message
-                throw new GraphQLException("Don't know how to handle type ".((string) $type));
+                throw TypeMappingException::createFromType($type);
             } elseif (count($filteredDocBlockTypes) === 1) {
                 $graphQlType = $this->toGraphQlType($filteredDocBlockTypes[0], $mapToInputType);
             } else {

src/TypeMappingException.php

@@ -0,0 +1,66 @@
+<?php
+
+
+namespace TheCodingMachine\GraphQL\Controllers;
+
+
+use phpDocumentor\Reflection\Type;
+use phpDocumentor\Reflection\Types\Array_;
+use phpDocumentor\Reflection\Types\Mixed_;
+use Roave\BetterReflection\Reflection\ReflectionFunction;
+use Roave\BetterReflection\Reflection\ReflectionMethod;
+use Roave\BetterReflection\Reflection\ReflectionParameter;
+
+class TypeMappingException extends GraphQLException
+{
+    private $type;
+
+    public static function createFromType(Type $type)
+    {
+        $e = new self("Don't know how to handle type ".(string) $type);
+        $e->type = $type;
+        return $e;
+    }
+
+    public static function wrapWithParamInfo(TypeMappingException $previous, ReflectionParameter $parameter): TypeMappingException
+    {
+        if ($previous->type instanceof Array_) {
+            $message = sprintf('Parameter $%s in %s::%s is type-hinted to array. Please provide an additional @param in the PHPDoc block to further specify the type of the array. For instance: @param string[] $%s.',
+                $parameter->getName(),
+                $parameter->getDeclaringClass()->getName(),
+                $parameter->getDeclaringFunction()->getName(),
+                $parameter->getName());
+        } elseif ($previous->type instanceof Mixed_) {
+            $message = sprintf('Parameter $%s in %s::%s is missing a type-hint (or type-hinted to "mixed"). Please provide a better type-hint. For instance: "string $%s".',
+                $parameter->getName(),
+                $parameter->getDeclaringClass()->getName(),
+                $parameter->getDeclaringFunction()->getName(),
+                $parameter->getName());
+        } else {
+            throw new GraphQLException("Unexpected type in TypeMappingException");
+        }
+
+        $e = new self($message, 0, $previous);
+        $e->type = $previous->type;
+        return $e;
+    }
+
+    public static function wrapWithReturnInfo(TypeMappingException $previous, ReflectionMethod $method): TypeMappingException
+    {
+        if ($previous->type instanceof Array_) {
+            $message = sprintf('Return type in %s::%s is type-hinted to array. Please provide an additional @return in the PHPDoc block to further specify the type of the array. For instance: @return string[]',
+                $method->getDeclaringClass()->getName(),
+                $method->getName());
+        } elseif ($previous->type instanceof Mixed_) {
+            $message = sprintf('Return type in %s::%s is missing a type-hint (or type-hinted to "mixed"). Please provide a better type-hint.',
+                $method->getDeclaringClass()->getName(),
+                $method->getName());
+        } else {
+            throw new GraphQLException("Unexpected type in TypeMappingException");
+        }
+
+        $e = new self($message, 0, $previous);
+        $e->type = $previous->type;
+        return $e;
+    }
+}