Merge branch 'feature/GQL-12' into develop

Author: mghoneimy

README.md

@@ -151,6 +151,25 @@ $results = $client->runQuery($gql, true);
 $results->getData()['Company'][1]['branches']['address']
 ```
 
+# Mutations
+Mutations follow the same rules of queries in GraphQL, they select fields on returned objects, receive arguments, and
+can have sub-fields.
+
+Here's a sample example on how to construct and run mutations:
+```
+$mutation = (new Mutation('createCompany'))
+    ->setArguments(['companyObject' => new RawObject('{name: "Trial Company", employees: 200}')])
+    ->setSelectionSet(
+        [
+            '_id',
+            'name',
+            'serialNumber',
+        ]
+    );
+$results = $client->runQuery($mutation);
+```
+Mutations can be run by the client the same way queries are run.
+
 # Live API Example
 GraphQL Pokemon is a very cool public GraphQL API available to retrieve Pokemon data. The API is available publicly on
 the web, we'll use it to demo the capabilities of this client.
@@ -265,3 +284,27 @@ catch (QueryError $exception) {
 }
 print_r($results->getData()['pokemon']);
 ```
+
+# Running Raw Queries
+Although not the primary goal of this package, but it supports running raw string queries, just like any other client
+using the `runRawQuery` method in the `Client` class. Here's an example on how to use it:
+```
+$gql = <<<QUERY
+query {
+    pokemon(name: "Pikachu") {
+        id
+        number
+        name
+        attacks {
+            special {
+                name
+                type
+                damage
+            }
+        }
+    }
+}
+QUERY;
+
+$results = $client->runQuery($gql);
+```

examples/mutation_example.php

@@ -0,0 +1,47 @@
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use GraphQL\Client;
+use GraphQL\Exception\QueryError;
+use GraphQL\Mutation;
+use GraphQL\RawObject;
+
+// Create Client object to contact the GraphQL endpoint
+$client = new Client(
+    'api_url',
+    []  // Replace with array of extra headers to be sent with request for auth or other purposes
+);
+
+
+// Create the GraphQL mutation
+$gql = (new Mutation('createCompany'))
+    ->setArguments(['companyObject' => new RawObject('{name: "Trial Company", employees: 200}')])
+    ->setSelectionSet(
+        [
+            '_id',
+            'name',
+            'serialNumber',
+        ]
+    );
+
+// Run query to get results
+try {
+    $results = $client->runQuery($gql);
+}
+catch (QueryError $exception) {
+
+    // Catch query error and desplay error details
+    print_r($exception->getErrorDetails());
+    exit;
+}
+
+// Display original response from endpoint
+var_dump($results->getResponseObject());
+
+// Display part of the returned results of the object
+var_dump($results->getData()->pokemon);
+
+// Reformat the results to an array and get the results of part of the array
+$results->reformatResults(true);
+print_r($results->getData()['pokemon']);

examples/raw_query_example.php

@@ -0,0 +1,50 @@
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use GraphQL\Client;
+use GraphQL\Exception\QueryError;
+
+// Create Client object to contact the GraphQL endpoint
+$client = new Client(
+    'https://graphql-pokemon.now.sh/',
+    []  // Replace with array of extra headers to be sent with request for auth or other purposes
+);
+
+$gql = <<<QUERY
+query {
+    pokemon(name: "Pikachu") {
+        id
+        number
+        name
+        attacks {
+            special {
+                name
+                type
+                damage
+            }
+        }
+    }
+}
+QUERY;
+
+// Run query to get results
+try {
+    $results = $client->runRawQuery($gql);
+}
+catch (QueryError $exception) {
+
+    // Catch query error and desplay error details
+    print_r($exception->getErrorDetails());
+    exit;
+}
+
+// Display original response from endpoint
+var_dump($results->getResponseObject());
+
+// Display part of the returned results of the object
+var_dump($results->getData()->pokemon);
+
+// Reformat the results to an array and get the results of part of the array
+$results->reformatResults(true);
+print_r($results->getData()['pokemon']);

src/Mutation.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace GraphQL;
+
+/**
+ * Class Mutation
+ *
+ * @package GraphQL
+ */
+class Mutation extends Query
+{
+    /**
+     * Stores the name of the type of the operation to be executed on the GraphQL server
+     *
+     * @var string
+     */
+    protected const OPERATION_TYPE = 'mutation';
+}

src/Query.php

@@ -18,7 +18,14 @@ class Query
      *
      * @var string
      */
-    private const QUERY_FORMAT = "%s%s {\n%s\n}";
+    protected const QUERY_FORMAT = "%s%s {\n%s\n}";
+
+    /**
+     * Stores the name of the type of the operation to be executed on the GraphQL server
+     *
+     * @var string
+     */
+    protected const OPERATION_TYPE = 'query';
 
     /**
      * Stores the object being queried for
@@ -181,8 +188,8 @@ protected function constructSelectionSet(): string
     public function __toString()
     {
         $queryFormat = static::QUERY_FORMAT;
-        if (!$this->isNested && $this->object !== 'query') {
-            $queryFormat = "query {\n" . static::QUERY_FORMAT . "\n}";
+        if (!$this->isNested && $this->object !== static::OPERATION_TYPE) {
+            $queryFormat = static::OPERATION_TYPE . " {\n" . static::QUERY_FORMAT . "\n}";
         }
         $argumentsString    = $this->constructArguments();
         $selectionSetString = $this->constructSelectionSet();

tests/MutationTest.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace GraphQL\Tests;
+
+use GraphQL\Mutation;
+use PHPUnit\Framework\TestCase;
+
+class MutationTest extends TestCase
+{
+    /**
+     *
+     */
+    public function testMutationWithoutOperationType()
+    {
+        $mutation = new Mutation('createObject');
+
+        $this->assertEquals(
+            'mutation {
+createObject {
+
+}
+}',
+            (string) $mutation
+        );
+    }
+
+    /**
+     *
+     */
+    public function testMutationWithOperationType()
+    {
+        $mutation = new Mutation('mutation');
+
+        $this->assertEquals(
+            'mutation {
+
+}',
+            (string) $mutation
+        );
+    }
+
+    /**
+     * 
+     */
+    public function testMutationWithFields()
+    {
+        $mutation = (new Mutation('createObject'))
+            ->setSelectionSet(
+                [
+                    'fieldOne',
+                    'fieldTwo',
+                ]
+            );
+
+        $this->assertEquals(
+            'mutation {
+createObject {
+fieldOne
+fieldTwo
+}
+}',
+            (string) $mutation
+        );
+    }
+
+    /**
+     *
+     */
+    public function testMutationWithArgumentsAndFields()
+    {
+        $mutation = (new Mutation('createObject'))
+            ->setSelectionSet(
+                [
+                    'fieldOne',
+                    'fieldTwo',
+                ]
+            )->setArguments(
+                [
+                    'argOne' => 1,
+                    'argTwo' => 'val'
+                ]
+            );
+
+        $this->assertEquals(
+            'mutation {
+createObject(argOne: 1 argTwo: "val") {
+fieldOne
+fieldTwo
+}
+}',
+            (string) $mutation
+        );
+    }
+}

tests/QueryTest.php

@@ -46,7 +46,7 @@ public function testEmptyArguments(Query $query)
     /**
      * @covers \GraphQL\Query::__toString
      */
-    public function testExplicitQueryObject()
+    public function testQueryWithOperationType()
     {
         $query = new Query('query');