Merge branch 'feature/GQL-47' into develop

Author: mghoneimy

Changelog.md

@@ -2,6 +2,11 @@
 
 The change log describes what is "Added", "Removed", "Changed" or "Fixed" between each release.
 
+## In Progress
+
+- Add support for variables attachment to query
+- Add support for variables passing query
+- Support for input objects variables
 
 ## 1.1: 2019-04-26
 

README.md

@@ -111,6 +111,34 @@ The RawObject class being constructed is used for injecting the string into the
 into the RawObject constructor will be put in the query as it is without any custom formatting normally done by the
 query class.
 
+## Query With Variables
+```
+$gql = (new Query('companies'))
+    ->setVariables(
+        [
+            new Variable('name', 'String', true),
+            new Variable('limit', 'Int', false, 5)
+        ]
+    )
+    ->setArguments(['name' => '$name', 'first' => '$limit'])
+    ->setSelectionSet(
+        [
+            'name',
+            'serialNumber'
+        ]
+    );
+```
+This query shows how variables can be used in this package to allow for dynamic requests enabled by GraphQL standards.
+
+### The Variable Class
+The Variable class is an immutable class that represents a variable in GraphQL standards. Its constructor receives 4
+arguments:
+- name: Represents the variable name
+- type: Represents the variable type according to the GraphQL server schema
+- isRequired (Optional): Represents if the variable is required or not, it's false by default
+- defaultValue (Optional): Represents the default value to be assigned to the variable. The default value will only be
+considered if the isRequired argument is set to false.
+
 # The Query Builder
 The QueryBuilder class can be used to construct Query objects dynamically, which can be useful in some cases. It works
 very similarly to the Query class, but the Query building is divided into steps.
@@ -119,7 +147,8 @@ That's how the "Query With Input Object Argument" example can be created using t
 QueryBuilder:
 ```
 $builder = (new QueryBuilder('companies'))
-    ->setArgument('filter', new RawObject('{name_starts_with: "Face"}'))
+    ->setVariable('namePrefix', 'String', true)
+    ->setArgument('filter', new RawObject('{name_starts_with: $namePrefix}'))
     ->selectField('name')
     ->selectField('serialNumber');
 $gql = $builder->getQuery();
@@ -139,7 +168,7 @@ $client = new Client(
 ```
 
 # Running Queries
-
+## Result Formatting
 Running query with the GraphQL client and getting the results in object structure:
 ```
 $results = $client->runQuery($gql);
@@ -151,6 +180,28 @@ $results = $client->runQuery($gql, true);
 $results->getData()['Company'][1]['branches']['address']
 ```
 
+## Passing Variables to Queries
+Running queries containing variables requires passing an associative array which maps variable names (keys) to variable
+values (values) to the `runQuery` method. Here's an example:
+```
+$gql = (new Query('companies'))
+    ->setVariables(
+        [
+            new Variable('name', 'String', true),
+            new Variable('limit', 'Int', false, 5)
+        ]
+    )
+    ->setArguments(['name' => '$name', 'first' => '$limit'])
+    ->setSelectionSet(
+        [
+            'name',
+            'serialNumber'
+        ]
+    );
+$variablesArray = ['name' => 'Tech Co.', 'first' => 5];
+$results = $client->runQuery($gql, true, $variablesArray);
+```
+
 # Mutations
 Mutations follow the same rules of queries in GraphQL, they select fields on returned objects, receive arguments, and
 can have sub-fields.

src/Client.php

@@ -45,11 +45,12 @@ public function __construct(string $endpointUrl, array $authorizationHeaders = [
     /**
      * @param Query|QueryBuilderInterface $query
      * @param bool                        $resultsAsArray
+     * @param array                       $variables
      *
      * @return Results|null
      * @throws QueryError
      */
-    public function runQuery($query, bool $resultsAsArray = false): ?Results
+    public function runQuery($query, bool $resultsAsArray = false, array $variables = []): ?Results
     {
         if ($query instanceof QueryBuilderInterface) {
             $query = $query->getQuery();
@@ -59,17 +60,18 @@ public function runQuery($query, bool $resultsAsArray = false): ?Results
             throw new TypeError('Client::runQuery accepts the first argument of type Query or QueryBuilderInterface');
         }
 
-        return $this->runRawQuery((string) $query, $resultsAsArray);
+        return $this->runRawQuery((string) $query, $resultsAsArray, $variables);
     }
 
     /**
      * @param string $queryString
      * @param bool   $resultsAsArray
+     * @param array  $variables
      *
      * @return Results|null
      * @throws QueryError
      */
-    public function runRawQuery(string $queryString, $resultsAsArray = false): ?Results
+    public function runRawQuery(string $queryString, $resultsAsArray = false, array $variables = []): ?Results
     {
         // Set request headers for authorization and content type
         if (!empty($this->authorizationHeaders)) {
@@ -78,7 +80,8 @@ public function runRawQuery(string $queryString, $resultsAsArray = false): ?Resu
         $options['headers']['Content-Type'] = 'application/json';
 
         // Set query in the request body
-        $options['body'] = json_encode(['query' => (string) $queryString]);
+        $bodyArray       = ['query' => (string) $queryString, 'variables' => $variables];
+        $options['body'] = json_encode($bodyArray);
 
         // Send api request and get response
         try {

src/Exception/InvalidVariableException.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace GraphQL\Exception;
+
+use InvalidArgumentException;
+
+/**
+ * Class InvalidVariableException
+ *
+ * @package GraphQL\Exception
+ */
+class InvalidVariableException extends InvalidArgumentException
+{
+    /**
+     * InvalidVariableException constructor.
+     *
+     * @param string $message
+     */
+    public function __construct($message = "")
+    {
+        parent::__construct($message);
+    }
+}

src/Query.php

@@ -2,8 +2,10 @@
 
 namespace GraphQL;
 
+use Exception;
 use GraphQL\Exception\ArgumentException;
 use GraphQL\Exception\InvalidSelectionException;
+use GraphQL\Exception\InvalidVariableException;
 use GraphQL\Util\StringLiteralFormatter;
 
 /**
@@ -27,12 +29,26 @@ class Query
      */
     protected const OPERATION_TYPE = 'query';
 
+    /**
+     * Stores the name of the operation to be run on the server
+     *
+     * @var string
+     */
+    private $operationName;
+
     /**
      * Stores the object being queried for
      *
      * @var string
      */
-    private $object;
+    private $fieldName;
+
+    /**
+     * Stores the list of variables to be used in the query
+     *
+     * @var array|Variable[]
+     */
+    private $variables;
 
     /**
      * Stores the list of arguments used when querying data
@@ -58,14 +74,49 @@ class Query
     /**
      * GQLQueryBuilder constructor.
      *
-     * @param string $objectName
+     * @param string $fieldName
+     */
+    public function __construct(string $fieldName)
+    {
+        $this->fieldName     = $fieldName;
+        $this->operationName = '';
+        $this->variables     = [];
+        $this->arguments     = [];
+        $this->selectionSet  = [];
+        $this->isNested      = false;
+    }
+
+    /**
+     * @param string $operationName
+     *
+     * @return Query
+     */
+    public function setOperationName(string $operationName)
+    {
+        if (!empty($operationName)) {
+            $this->operationName = " $operationName";
+        }
+
+        return $this;
+    }
+
+    /**
+     * @param array $variables
+     *
+     * @return Query
      */
-    public function __construct(string $objectName)
+    public function setVariables(array $variables)
     {
-        $this->object       = $objectName;
-        $this->arguments    = [];
-        $this->selectionSet = [];
-        $this->isNested     = false;
+        $nonVarElements = array_filter($variables, function($e) {
+            return !$e instanceof Variable;
+        });
+        if (count($nonVarElements) > 0) {
+            throw new InvalidVariableException('At least one of the elements of the variables array provided is not an instance of GraphQL\\Variable');
+        }
+
+        $this->variables = $variables;
+
+        return $this;
     }
 
     /**
@@ -116,6 +167,34 @@ public function setSelectionSet(array $selectionSet): Query
         return $this;
     }
 
+    /**
+     * @return string
+     */
+    protected function constructVariables(): string
+    {
+        if (empty($this->variables)) {
+            return '';
+        }
+
+        $varsString = '(';
+        $first      = true;
+        foreach ($this->variables as $variable) {
+
+            // Append space at the beginning if it's not the first item on the list
+            if ($first) {
+                $first = false;
+            } else {
+                $varsString .= ' ';
+            }
+
+            // Append variable string value to the variables string
+            $varsString .= (string) $variable;
+        }
+        $varsString .= ')';
+
+        return $varsString;
+    }
+
     /**
      * @return string
      */
@@ -188,13 +267,23 @@ protected function constructSelectionSet(): string
     public function __toString()
     {
         $queryFormat = static::QUERY_FORMAT;
-        if (!$this->isNested && $this->object !== static::OPERATION_TYPE) {
-            $queryFormat = static::OPERATION_TYPE . " {\n" . static::QUERY_FORMAT . "\n}";
+        if (!$this->isNested && $this->fieldName !== static::OPERATION_TYPE) {
+            $queryFormat = $this->generateSignature() . " {\n" . static::QUERY_FORMAT . "\n}";
         }
         $argumentsString    = $this->constructArguments();
         $selectionSetString = $this->constructSelectionSet();
 
-        return sprintf($queryFormat, $this->object, $argumentsString, $selectionSetString);
+        return sprintf($queryFormat, $this->fieldName, $argumentsString, $selectionSetString);
+    }
+
+    /**
+     * @return string
+     */
+    protected function generateSignature(): string
+    {
+        $signatureFormat = '%s%s%s';
+
+        return sprintf($signatureFormat, static::OPERATION_TYPE, $this->operationName, $this->constructVariables());
     }
 
     /**

src/QueryBuilder/AbstractQueryBuilder.php

@@ -5,6 +5,7 @@
 use GraphQL\Exception\EmptySelectionSetException;
 use GraphQL\Query;
 use GraphQL\RawObject;
+use GraphQL\Variable;
 
 /**
  * Class AbstractQueryBuilder
@@ -18,6 +19,11 @@ abstract class AbstractQueryBuilder implements QueryBuilderInterface
      */
     private $query;
 
+    /**
+     * @var array|Variable[]
+     */
+    private $variables;
+
     /**
      * @var array
      */
@@ -36,6 +42,7 @@ abstract class AbstractQueryBuilder implements QueryBuilderInterface
     public function __construct(string $queryObject)
     {
         $this->query         = new Query($queryObject);
+        $this->variables     = [];
         $this->selectionSet  = [];
         $this->argumentsList = [];
     }
@@ -56,6 +63,7 @@ public function getQuery(): Query
             }
         }
 
+        $this->query->setVariables($this->variables);
         $this->query->setArguments($this->argumentsList);
         $this->query->setSelectionSet($this->selectionSet);
 
@@ -90,4 +98,19 @@ protected function setArgument(string $argumentName, $argumentValue)
 
         return $this;
     }
+
+    /**
+     * @param string $name
+     * @param string $type
+     * @param bool   $isRequired
+     * @param null   $defaultValue
+     *
+     * @return $this
+     */
+    protected function setVariable(string $name, string $type, bool $isRequired = false, $defaultValue = null)
+    {
+        $this->variables[] = new Variable($name, $type, $isRequired, $defaultValue);
+
+        return $this;
+    }
 }