Merge pull request #12 from moufmouf/query_descriptions

Adding descriptions for queries and mutations

Author: moufmouf

src/ControllerQueryProvider.php

@@ -18,6 +18,7 @@
 use TheCodingMachine\GraphQL\Controllers\Annotations\Mutation;
 use TheCodingMachine\GraphQL\Controllers\Annotations\Query;
 use TheCodingMachine\GraphQL\Controllers\Annotations\Right;
+use TheCodingMachine\GraphQL\Controllers\Reflection\CommentParser;
 use TheCodingMachine\GraphQL\Controllers\Security\AuthenticationServiceInterface;
 use TheCodingMachine\GraphQL\Controllers\Security\AuthorizationServiceInterface;
 use Youshido\GraphQL\Field\Field;
@@ -107,6 +108,7 @@ private function getFieldsByAnnotations(string $annotationName): array
             $queryAnnotation = $this->annotationReader->getMethodAnnotation($standardPhpMethod, $annotationName);
 
             if ($queryAnnotation !== null) {
+                $docBlock = new CommentParser($refMethod->getDocComment());
                 if (!$this->isAuthorized($standardPhpMethod)) {
                     continue;
                 }
@@ -122,7 +124,7 @@ private function getFieldsByAnnotations(string $annotationName): array
                 } catch (TypeMappingException $e) {
                     throw TypeMappingException::wrapWithReturnInfo($e, $refMethod);
                 }
-                $queryList[] = new QueryField($methodName, $type, $args, [$this->controller, $methodName], $this->hydrator);
+                $queryList[] = new QueryField($methodName, $type, $args, [$this->controller, $methodName], $this->hydrator, $docBlock->getComment());
             }
         }
 

src/QueryField.php

@@ -29,14 +29,17 @@ class QueryField extends AbstractField
      * @param callable $resolve
      * @param array $additionalConfig
      */
-    public function __construct(string $name, TypeInterface $type, array $arguments, callable $resolve, HydratorInterface $hydrator, array $additionalConfig = [])
+    public function __construct(string $name, TypeInterface $type, array $arguments, callable $resolve, HydratorInterface $hydrator, ?string $comment, array $additionalConfig = [])
     {
         $this->hydrator = $hydrator;
         $config = [
             'name' => $name,
             'type' => $type,
             'args' => array_map(function(array $item) { return $item['type']; }, $arguments)
         ];
+        if ($comment) {
+            $config['description'] = $comment;
+        }
 
         $config['resolve'] = function ($source, array $args, ResolveInfo $info) use ($resolve, $arguments) {
             $toPassArgs = [];

src/Reflection/CommentParser.php

@@ -0,0 +1,73 @@
+<?php
+
+
+namespace TheCodingMachine\GraphQL\Controllers\Reflection;
+
+
+class CommentParser
+{
+    private $comment;
+
+    public function __construct(string $docBlock)
+    {
+        $lines = $this->getAllLinesWithoutStars($docBlock);
+
+        // First, let's go to the first Annotation.
+        // Anything before is the pure comment.
+
+        $oneAnnotationFound = false;
+        // Is the line an annotation? Let's test this with a regexp.
+        foreach ($lines as $line) {
+            if ($oneAnnotationFound === false && preg_match("/^[@][a-zA-Z]/", $line) === 0) {
+                $this->comment .= $line."\n";
+            } else {
+                //$this->parseAnnotation($line);
+                $oneAnnotationFound = true;
+            }
+        }
+
+        $this->comment = rtrim($this->comment, "\n");
+    }
+
+    /**
+     * @param string $docComment
+     * @return string[]
+     */
+    private function getAllLinesWithoutStars(string $docComment): array
+    {
+        if (strpos($docComment, '/**') === 0) {
+            $docComment = substr($docComment, 3);
+        }
+
+        // Let's remove all the \r...
+        $docComment = str_replace("\r", '', $docComment);
+
+        $commentLines = explode("\n", $docComment);
+        $commentLinesWithoutStars = array_map(function(string $line) {
+            return ltrim($line, " \t*");
+        }, $commentLines);
+
+        // Let's remove the trailing /:
+        $lastComment = $commentLinesWithoutStars[count($commentLinesWithoutStars)-1];
+        $commentLinesWithoutStars[count($commentLinesWithoutStars)-1] = substr($lastComment, 0, strlen($lastComment)-1);
+
+        if ($commentLinesWithoutStars[count($commentLinesWithoutStars)-1] == "") {
+            array_pop($commentLinesWithoutStars);
+        }
+
+        if (isset($commentLinesWithoutStars[0]) && $commentLinesWithoutStars[0] === '') {
+            $commentLinesWithoutStars = array_slice($commentLinesWithoutStars, 1);
+        }
+        return $commentLinesWithoutStars;
+    }
+
+    /**
+     * Returns the comment out of a Docblock, ignoring all annotations
+     *
+     * @return string
+     */
+    public function getComment(): string
+    {
+        return $this->comment;
+    }
+}

tests/Reflection/CommentParserTest.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace TheCodingMachine\GraphQL\Controllers\Reflection;
+
+use PHPUnit\Framework\TestCase;
+
+class CommentParserTest extends TestCase
+{
+    public function testParse()
+    {
+        $commentParser = new CommentParser(<<<EOF
+/**
+ * Foo
+ * Bar
+ *
+ * @param string \$id yop
+ */
+EOF
+        );
+
+        $this->assertSame("Foo\nBar", $commentParser->getComment());
+    }
+}