From 473bdb62a1c6f56b1799a5fb03d49ac7e16cc0d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivo=20Mei=C3=9Fner?= <info@overtronic.com>
Date: Tue, 13 Sep 2016 16:53:55 -0500
Subject: [PATCH] Updated documentation to spec April2016, upgrade instructions

---
 README.md  | 17 ++++++++++++++--
 UPGRADE.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 73 insertions(+), 2 deletions(-)
 create mode 100644 UPGRADE.md

diff --git a/README.md b/README.md
index 30c2044..29e4e04 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,8 @@ $> curl -sS https://getcomposer.org/installer | php
 $> php composer.phar require webonyx/graphql-php='dev-master'
 ```
 
+If you are upgrading, see [upgrade instructions](UPGRADE.md)
+
 ## Requirements
 PHP >=5.4
 
@@ -52,7 +54,7 @@ Examples below implement the type system described in this document.
 ### Type System
 To start using GraphQL you are expected to implement a Type system.
 
-GraphQL PHP provides several *kinds* of types to build hierarchical type system:
+GraphQL PHP provides several *kinds* of types to build a hierarchical type system:
  `scalar`, `enum`, `object`, `interface`, `union`, `listOf`, `nonNull`.
 
 #### Internal types
@@ -357,7 +359,17 @@ $queryType = new ObjectType([
 // TODOC
 $mutationType = null;
 
-$schema = new Schema($queryType, $mutationType);
+$schema = new Schema([
+    'query' => $queryType, 
+    'mutation' => $mutationType,
+    
+    // We need to pass the types that implement interfaces in case the types are only created on demand.
+    // This ensures that they are available during query validation phase for interfaces. 
+    'types' => [
+        $humanType,
+        $droidType
+    ]
+]);
 ```
 
 **Notes:**
@@ -447,6 +459,7 @@ try {
         $schema,
         $requestString,
         /* $rootValue */ null,
+        /* $context */ null, // A custom context that can be used to pass current User object etc to resolvers.
         $variableValues,
         $operationName
     );
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 0000000..9b073dd
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,58 @@
+# Upgrade
+
+## Upgrade v0.6.x > v0.7.x
+
+There are a few new breaking changes in v0.7.0 that were added to the graphql-js reference implementation 
+with the spec of April2016
+
+### 1. Context for resolver
+
+You can now pass a custom context to the `GraphQL::execute` function that is available in all resolvers. 
+This can for example be used to pass the current user etc. The new signature looks like this:
+
+```php
+GraphQL::execute(
+    $schema,
+    $query,
+    $rootObject,
+    $context,
+    $variables,
+    $operationName
+);
+```
+
+The signature of all resolve methods has changed to the following: 
+
+```php
+/**
+ * @param mixed $object The parent resolved object
+ * @param array $args Input arguments
+ * @param mixed $context The context object hat was passed to GraphQL::execute
+ * @param ResolveInfo $info ResolveInfo object
+ * @return mixed
+ */
+function resolveMyField($object, array $args, $context, ResolveInfo $info){
+    //...
+}
+```
+
+### 2. Schema constructor signature
+
+The signature of the Schema constructor now accepts an associative config array instead of positional arguments: 
+
+```php
+$schema = new Schema([
+    'query' => $queryType,
+    'mutation' => $mutationType,
+    'types' => $arrayOfTypesWithInterfaces // See 3.
+]);
+```
+
+### 3. Types can be directly passed to schema
+
+In case your implementation creates types on demand, the types might not be available when an interface
+is queried and query validation will fail. In that case, you need to pass the types that implement the
+interfaces directly to the schema, so it knows of their existence during query validation. 
+Also see webonyx/graphql-php#38
+
+If your types are created each time the Schema is created, this can be ignored.