Merge c12cb42 into 4e441b3

Author: Vincz

UPGRADE-0.12.md

@@ -35,3 +35,48 @@ UPGRADE FROM 0.11 to 0.12
            App\GraphQL\:
                resource: ../GraphQL
        ```
+
+
+### Relay Paginator, Connections & Edges
+
+-   Following the [paginator update](docs/helpers/relay-paginator.md) and the use of interfaces for Relay Connection & Edge, getters & setters must be use to manipulate Connection, Edge and PageInfo Properties
+
+Before :
+
+```php
+$connection->edges = $edges;
+$connection->totalCount = 10;
+...
+$edge->cursor = $cursor;
+$edge->node = $node;
+
+```
+
+After :
+
+```php
+$connection->setEdges($edges);
+$connection->setTotalCount(10);
+...
+$edge->setCursor($cursor);
+$edge->setNode($node);
+```
+
+Connection builder method are no more accessible statically:
+
+Before:
+
+```php
+use Overblog\GraphQLBundle\Relay\Connection\ConnectionBuilder;
+
+ConnectionBuilder::connectionFromArray([]);
+```
+
+After:
+
+```php
+use Overblog\GraphQLBundle\Relay\Connection\ConnectionBuilder;
+
+$connectionBuilder = new ConnectionBuilder();
+$connectionBuilder->connectionFromArray([]);
+```

docs/helpers/relay-paginator.md

@@ -261,3 +261,53 @@ public function resolveList($args)
     return $pagination->forward($args);
 }
 ```
+
+
+#### Customize the way the connection & edges are built
+
+Sometimes, you want to add fields to your Connection or Edges. In order to do so, you'll have to pass a custom instance of `ConnectionBuilder` to your Paginator as follow:  
+
+```php
+use Overblog\GraphQLBundle\Relay\Connection\ConnectionBuilder;
+
+public function resolveSomething(Argument $args)
+{
+    $connectionBuilder = new ConnectionBuilder( 
+        function(iterable $edges, PageInfo $pageInfo) : FriendsConnection {
+            $connection = new FriendsConnection($edges, $pageInfo)
+            $connection->setAverageAge(calculateAverage($edges));
+            return $connection;
+        },
+        function(string $cursor, UserFriend $entity, int $index):FriendEdge {
+            $edge = new FriendEdge($cursor, $entity->getUser());
+            $edge->setFriendshipTime($entity->getCreatedAt());
+            return $edge;
+        }
+    );
+
+    $paginator = new Paginator(function ($offset, $limit) use ($backend) {
+        return $backend->getData($offset);
+    }, true, $connectionBuilder);
+}
+```
+
+The `ConnectionBuilder` constructor accepts two parameters. The first one is a callback to build the Connection object, and the second one is a callback to build an Edge object.  
+
+The connection callback will be call with the following parameters :
+
+- `edges` An array of edges object implementing `Overblog\GraphQLBundle\Relay\Connection\EdgeInterface`
+- `pageInfo` a PageInfo object `Overblog\GraphQLBundle\Relay\Connection\Output\PageInfo`
+
+This callback MUST return an instance of `Overblog\GraphQLBundle\Relay\Connection\ConnectionInterface`
+
+
+The edge callback will be call with the following parameters :
+
+- `cursor` The cursor
+- `value` A value returned by the paginator data fetcher
+- `index` The index of the value
+
+This callback MUST return an instance of `Overblog\GraphQLBundle\Relay\Connection\EdgeInterface`
+
+If no callback are specified for the `ConnectionBuilder`, it'll generate instance of `Overblog\GraphQLBundle\Relay\Connection\Output\Connection` and `Overblog\GraphQLBundle\Relay\Connection\Output\Edge`
+

src/Relay/Connection/Output/ConnectionBuilder.php renamed to src/Relay/Connection/ConnectionBuilder.php

@@ -2,9 +2,12 @@
 
 declare(strict_types=1);
 
-namespace Overblog\GraphQLBundle\Relay\Connection\Output;
+namespace Overblog\GraphQLBundle\Relay\Connection;
 
 use Overblog\GraphQLBundle\Definition\Argument;
+use Overblog\GraphQLBundle\Relay\Connection\Output\Connection;
+use Overblog\GraphQLBundle\Relay\Connection\Output\Edge;
+use Overblog\GraphQLBundle\Relay\Connection\Output\PageInfo;
 
 /**
  * Class ConnectionBuilder.
@@ -15,6 +18,26 @@ class ConnectionBuilder
 {
     public const PREFIX = 'arrayconnection:';
 
+    /**
+     * If set, used to generate the connection object.
+     *
+     * @var callable
+     */
+    protected $connectionCallback;
+
+    /**
+     * If set, used to generate the edge object.
+     *
+     * @var callable
+     */
+    protected $edgeCallback;
+
+    public function __construct(callable $connectionCallback = null, callable $edgeCallback = null)
+    {
+        $this->connectionCallback = $connectionCallback;
+        $this->edgeCallback = $edgeCallback;
+    }
+
     /**
      * A simple function that accepts an array and connection arguments, and returns
      * a connection object for use in GraphQL. It uses array offsets as pagination,
@@ -23,11 +46,11 @@ class ConnectionBuilder
      * @param array          $data
      * @param array|Argument $args
      *
-     * @return Connection
+     * @return ConnectionInterface
      */
-    public static function connectionFromArray(array $data, $args = []): Connection
+    public function connectionFromArray(array $data, $args = []): ConnectionInterface
     {
-        return static::connectionFromArraySlice(
+        return $this->connectionFromArraySlice(
             $data,
             $args,
             [
@@ -46,12 +69,12 @@ public static function connectionFromArray(array $data, $args = []): Connection
      *
      * @return mixed a promise
      */
-    public static function connectionFromPromisedArray($dataPromise, $args = [])
+    public function connectionFromPromisedArray($dataPromise, $args = [])
     {
-        self::checkPromise($dataPromise);
+        $this->checkPromise($dataPromise);
 
         return $dataPromise->then(function ($data) use ($args) {
-            return static::connectionFromArray($data, $args);
+            return $this->connectionFromArray($data, $args);
         });
     }
 
@@ -68,11 +91,11 @@ public static function connectionFromPromisedArray($dataPromise, $args = [])
      * @param array|Argument $args
      * @param array          $meta
      *
-     * @return Connection
+     * @return ConnectionInterface
      */
-    public static function connectionFromArraySlice(array $arraySlice, $args, array $meta): Connection
+    public function connectionFromArraySlice(array $arraySlice, $args, array $meta): ConnectionInterface
     {
-        $connectionArguments = self::getOptionsWithDefaults(
+        $connectionArguments = $this->getOptionsWithDefaults(
             $args instanceof Argument ? $args->getRawArguments() : $args,
             [
                 'after' => '',
@@ -81,7 +104,7 @@ public static function connectionFromArraySlice(array $arraySlice, $args, array
                 'last' => null,
             ]
         );
-        $arraySliceMetaInfo = self::getOptionsWithDefaults(
+        $arraySliceMetaInfo = $this->getOptionsWithDefaults(
             $meta,
             [
                 'sliceStart' => 0,
@@ -97,8 +120,8 @@ public static function connectionFromArraySlice(array $arraySlice, $args, array
         $sliceStart = $arraySliceMetaInfo['sliceStart'];
         $arrayLength = $arraySliceMetaInfo['arrayLength'];
         $sliceEnd = $sliceStart + $arraySliceLength;
-        $beforeOffset = static::getOffsetWithDefault($before, $arrayLength);
-        $afterOffset = static::getOffsetWithDefault($after, -1);
+        $beforeOffset = $this->getOffsetWithDefault($before, $arrayLength);
+        $afterOffset = $this->getOffsetWithDefault($after, -1);
 
         $startOffset = \max($sliceStart - 1, $afterOffset, -1) + 1;
         $endOffset = \min($sliceEnd, $beforeOffset, $arrayLength);
@@ -131,23 +154,40 @@ public static function connectionFromArraySlice(array $arraySlice, $args, array
         $edges = [];
 
         foreach ($slice as $index => $value) {
-            $edges[] = new Edge(static::offsetToCursor($startOffset + $index), $value);
+            $cursor = $this->offsetToCursor($startOffset + $index);
+            if ($this->edgeCallback) {
+                $edge = ($this->edgeCallback)($cursor, $value, $index);
+                if (!($edge instanceof EdgeInterface)) {
+                    throw new \InvalidArgumentException(\sprintf('The $edgeCallback of the ConnectionBuilder must return an instance of EdgeInterface'));
+                }
+            } else {
+                $edge = new Edge($cursor, $value);
+            }
+            $edges[] = $edge;
         }
 
         $firstEdge = $edges[0] ?? null;
         $lastEdge = \end($edges);
         $lowerBound = $after ? ($afterOffset + 1) : 0;
         $upperBound = $before ? $beforeOffset : $arrayLength;
 
-        return new Connection(
-            $edges,
-            new PageInfo(
-                $firstEdge instanceof Edge ? $firstEdge->cursor : null,
-                $lastEdge instanceof Edge ? $lastEdge->cursor : null,
-                null !== $last ? $startOffset > $lowerBound : false,
-                null !== $first ? $endOffset < $upperBound : false
-            )
+        $pageInfo = new PageInfo(
+            $firstEdge instanceof EdgeInterface ? $firstEdge->getCursor() : null,
+            $lastEdge instanceof EdgeInterface ? $lastEdge->getCursor() : null,
+            null !== $last ? $startOffset > $lowerBound : false,
+            null !== $first ? $endOffset < $upperBound : false
         );
+
+        if ($this->connectionCallback) {
+            $connection = ($this->connectionCallback)($edges, $pageInfo);
+            if (!($connection instanceof ConnectionInterface)) {
+                throw new \InvalidArgumentException(\sprintf('The $connectionCallback of the ConnectionBuilder must return an instance of ConnectionInterface'));
+            }
+
+            return $connection;
+        }
+
+        return new Connection($edges, $pageInfo);
     }
 
     /**
@@ -160,12 +200,12 @@ public static function connectionFromArraySlice(array $arraySlice, $args, array
      *
      * @return mixed a promise
      */
-    public static function connectionFromPromisedArraySlice($dataPromise, $args, array $meta)
+    public function connectionFromPromisedArraySlice($dataPromise, $args, array $meta)
     {
-        self::checkPromise($dataPromise);
+        $this->checkPromise($dataPromise);
 
         return $dataPromise->then(function ($arraySlice) use ($args, $meta) {
-            return static::connectionFromArraySlice($arraySlice, $args, $meta);
+            return $this->connectionFromArraySlice($arraySlice, $args, $meta);
         });
     }
 
@@ -177,7 +217,7 @@ public static function connectionFromPromisedArraySlice($dataPromise, $args, arr
      *
      * @return null|string
      */
-    public static function cursorForObjectInConnection(array $data, $object): ?string
+    public function cursorForObjectInConnection(array $data, $object): ? string
     {
         $offset = null;
 
@@ -195,7 +235,7 @@ public static function cursorForObjectInConnection(array $data, $object): ?strin
             return null;
         }
 
-        return static::offsetToCursor($offset);
+        return $this->offsetToCursor($offset);
     }
 
     /**
@@ -208,12 +248,12 @@ public static function cursorForObjectInConnection(array $data, $object): ?strin
      *
      * @return int
      */
-    public static function getOffsetWithDefault(?string $cursor, int $defaultOffset): int
+    public function getOffsetWithDefault(?string $cursor, int $defaultOffset): int
     {
         if (empty($cursor)) {
             return $defaultOffset;
         }
-        $offset = static::cursorToOffset($cursor);
+        $offset = $this->cursorToOffset($cursor);
 
         return !\is_numeric($offset) ? $defaultOffset : (int) $offset;
     }
@@ -225,7 +265,7 @@ public static function getOffsetWithDefault(?string $cursor, int $defaultOffset)
      *
      * @return string
      */
-    public static function offsetToCursor($offset): string
+    public function offsetToCursor($offset): string
     {
         return \base64_encode(static::PREFIX.$offset);
     }
@@ -237,7 +277,7 @@ public static function offsetToCursor($offset): string
      *
      * @return string
      */
-    public static function cursorToOffset($cursor): string
+    public function cursorToOffset($cursor): string
     {
         if (null === $cursor) {
             return '';
@@ -246,12 +286,12 @@ public static function cursorToOffset($cursor): string
         return \str_replace(static::PREFIX, '', \base64_decode($cursor, true));
     }
 
-    private static function getOptionsWithDefaults(array $options, array $defaults)
+    private function getOptionsWithDefaults(array $options, array $defaults)
     {
         return $options + $defaults;
     }
 
-    private static function checkPromise($value): void
+    private function checkPromise($value): void
     {
         if (!\is_callable([$value, 'then'])) {
             throw new \InvalidArgumentException('This is not a valid promise.');

src/Relay/Connection/ConnectionInterface.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Overblog\GraphQLBundle\Relay\Connection;
+
+use Overblog\GraphQLBundle\Relay\Connection\Output\PageInfo;
+
+interface ConnectionInterface
+{
+    /**
+     * Get the connection edges.
+     *
+     * @return iterable|EdgeInterface[]
+     */
+    public function getEdges();
+
+    /**
+     * Set the connection edges.
+     *
+     * @param iterable|EdgeInterface[] $edges
+     */
+    public function setEdges(iterable $edges);
+
+    /**
+     * Get the page info.
+     *
+     * @return PageInfoInterface
+     */
+    public function getPageInfo(): ?PageInfoInterface;
+
+    /**
+     * Set the page info.
+     *
+     * @param PageInfoInterface $pageInfo
+     */
+    public function setPageInfo(PageInfoInterface $pageInfo);
+
+    /**
+     * Get the total count.
+     *
+     * @return int
+     */
+    public function getTotalCount(): ?int;
+
+    /**
+     * Set the total count.
+     *
+     * @param int $totalCount
+     */
+    public function setTotalCount(int $totalCount);
+}