Merge pull request #518 from simPod/fix-internal-directives

Fix internal directives

.gitattributes

@@ -0,0 +1,13 @@
+# Set the default behavior, in case people don't have core.autocrlf set.
+* text eol=lf
+/benchmarks export-ignore
+/tests export-ignore
+/examples export-ignore
+/tools export-ignore
+.gitattributes export-ignore
+.gitignore export-ignore
+.travis.yml export-ignore
+CONTRIBUTING.md export-ignore
+mkdocs.yml export-ignore
+phpbench.json export-ignore
+phpunit.xml.dist  export-ignore

.gitignore

@@ -1,5 +1,7 @@
-.idea/
-composer.phar
+.phpcs-cache
 composer.lock
+composer.phar
+phpcs.xml
+phpstan.neon
 vendor/
-bin/
+/.idea

.scrutinizer.yml

@@ -0,0 +1,29 @@
+build:
+    nodes:
+        analysis:
+            environment:
+                php:
+                    version: 7.1
+            cache:
+                disabled: false
+                directories:
+                    - ~/.composer/cache
+            project_setup:
+                override: true
+            tests:
+                override:
+                    - php-scrutinizer-run
+
+    dependencies:
+        override:
+            - composer install --ignore-platform-reqs --no-interaction
+
+tools:
+    external_code_coverage:
+        timeout: 900
+
+build_failure_conditions:
+    - 'elements.rating(<= C).new.exists'                        # No new classes/methods with a rating of C or worse allowed
+    - 'issues.label("coding-style").new.exists'                 # No new coding style issues allowed
+    - 'issues.severity(>= MAJOR).new.exists'                    # New issues of major or higher severity
+    - 'project.metric_change("scrutinizer.test_coverage", < 0)' # Code Coverage decreased from previous inspection

.travis.yml

@@ -1,15 +1,66 @@
+dist: trusty
 language: php
 
 php:
-    - 5.4
-    - 5.5
-    - 5.6
-    - 7.0
-    - nightly
-    - hhvm
+  - 7.1
+  - 7.2
+  - 7.3
+  - 7.4snapshot
+  - nightly
 
-install:
-    - composer install --prefer-dist
+env:
+  matrix:
+  - EXECUTOR= DEPENDENCIES=--prefer-lowest
+  - EXECUTOR=coroutine DEPENDENCIES=--prefer-lowest
+  - EXECUTOR=
+  - EXECUTOR=coroutine
+
+
+cache:
+  directories:
+    - $HOME/.composer/cache
+
+before_install:
+  - mv ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/xdebug.ini{,.disabled} || echo "xdebug not available"
+  - travis_retry composer self-update
+
+install: travis_retry composer update --prefer-dist
+
+script: ./vendor/bin/phpunit --group default,ReactPromise
+
+jobs:
+  allow_failures:
+    - php: 7.4snapshot
+    - php: nightly
+
+  include:
+    - stage: Test
+      install:
+        - travis_retry composer update --prefer-dist {$DEPENDENCIES}
+
+    - stage: Test
+      env: COVERAGE
+      before_script:
+        - mv ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/xdebug.ini{.disabled,}
+        - if [[ ! $(php -m | grep -si xdebug) ]]; then echo "xdebug required for coverage"; exit 1; fi
+      script:
+        - ./vendor/bin/phpunit --coverage-php /tmp/coverage/clover_executor.cov
+        - EXECUTOR=coroutine ./vendor/bin/phpunit --coverage-php /tmp/coverage/clover_executor-coroutine.cov
+      after_script:
+        - ./vendor/bin/phpcov merge /tmp/coverage --clover /tmp/clover.xml
+        - wget https://github.com/scrutinizer-ci/ocular/releases/download/1.5.2/ocular.phar
+        - php ocular.phar code-coverage:upload --format=php-clover /tmp/clover.xml
+
+    - stage: Code Quality
+      php: 7.1
+      env: CODING_STANDARD
+      install: travis_retry composer install --prefer-dist
+      script:
+        - ./vendor/bin/phpcs
+
+    - stage: Code Quality
+      php: 7.1
+      env: STATIC_ANALYSIS
+      install: travis_retry composer install --prefer-dist
+      script: composer static-analysis
 
-script:
-    - ./bin/phpunit tests/

CHANGELOG.md

@@ -0,0 +1,200 @@
+# Changelog
+
+## Unreleased
+- Add schema validation: Input Objects must not contain non-nullable circular references (#492)
+
+#### v0.13.5
+- Fix coroutine executor when using with promise (#486) 
+
+#### v0.13.4
+- Force int when setting max query depth (#477)
+
+#### v0.13.3
+- Reverted minor possible breaking change (#476)
+
+#### v0.13.2
+- Added QueryPlan support (#436)
+- Fixed an issue with NodeList iteration over missing keys (#475)
+
+#### v0.13.1
+- Better validation of field/directive arguments
+- Support for apollo client/server persisted queries
+- Minor tweaks and fixes
+
+## v0.13.0
+This release brings several breaking changes. Please refer to [UPGRADE](UPGRADE.md) document for details.
+
+New features and notable changes:
+- PHP version required: 7.1+
+- Spec compliance: error `category` and extensions are displayed under `extensions` key when using default formatting (#389)
+- New experimental executor with improved performance (#314).<br>
+It is a one-line switch: `GraphQL::useExperimentalExecutor()`.<br>
+<br> 
+**Please try it and post your feedback at https://github.com/webonyx/graphql-php/issues/397**
+(as it may become the default one in future)
+<br>
+<br> 
+- Ported `extendSchema` from the reference implementation under `GraphQL\Utils\SchemaExtender` (#362)
+- Added ability to override standard types via `GraphQL::overrideStandardTypes(array $types)` (#401)
+- Added flag `Debug::RETHROW_UNSAFE_EXCEPTIONS` which would only rethrow app-specific exceptions (#337)
+- Several classes were renamed (see [UPGRADE.md](UPGRADE.md))
+- Schema Validation improvements 
+
+#### v0.12.6
+- Bugfix: Call to a member function getLocation() on null (#336)
+- Fixed several errors discovered by static analysis (#329)
+
+#### v0.12.5
+- Execution performance optimization for lists
+
+#### v0.12.4
+- Allow stringeable objects to be serialized by StringType (#303)
+
+#### v0.12.3
+- StandardServer: add support for the multipart/form-data content type (#300)
+
+#### v0.12.2
+- SchemaPrinter: Use multi-line block for trailing quote (#294)
+
+#### v0.12.1
+- Fixed bug in validation rule OverlappingFieldsCanBeMerged (#292)
+- Added one more breaking change note in UPGRADE.md (#291)
+- Spec compliance: remove `data` entry from response on top-level error (#281)
+
+## v0.12.0
+- RFC: Block String (multi-line strings via triple-quote """string""")
+- GraphQL Schema SDL: Descriptions as strings (including multi-line)
+- Changed minimum required PHP version to 5.6
+
+Improvements:
+- Allow extending GraphQL errors with additional properties
+- Fixed parsing of default values in Schema SDL
+- Handling several more cases in findBreakingChanges
+- StandardServer: expect `operationName` (instead of `operation`) in input
+
+
+#### v0.11.5
+- Allow objects with __toString in IDType
+
+#### v0.11.4
+- findBreakingChanges utility (see #199)
+
+#### v0.11.3
+- StandardServer: Support non pre-parsed PSR-7 request body (see #202)
+
+#### v0.11.2
+- Bugfix: provide descriptions to custom scalars (see #181)
+
+#### v0.11.1
+- Ability to override internal types via `types` option of the schema (see #174).
+
+## v0.11.0
+This release brings little changes but there are two reasons why it is released as major version:
+
+1. To follow reference implementation versions (it matches 0.11.x series of graphql-js)
+2. It may break existing applications because scalar input coercion rules are stricter now:<br>
+In previous versions sloppy client input could leak through with unexpected results. 
+For example string `"false"` accidentally sent in variables was converted to boolean `true` 
+and passed to field arguments. In the new version, such input will produce an error 
+(which is a spec-compliant behavior).
+
+Improvements: 
+- Stricter input coercion (see #171)
+- Types built with `BuildSchema` now have reference to AST node with corresponding AST definition (in $astNode property)
+- Account for query offset for error locations (e.g. when query is stored in `.graphql` file)
+
+#### v0.10.2
+- StandardServer improvement: do not raise an error when variables are passed as empty string (see #156)
+
+#### v0.10.1
+- Fixed infinite loop in the server (see #153)
+
+## v0.10.0
+This release brings several breaking changes. Please refer to [UPGRADE](UPGRADE.md) document for details.
+
+New features and notable changes:
+- Changed minimum PHP version from 5.4 to 5.5
+- Lazy loading of types without separate build step (see #69, see [docs](http://webonyx.github.io/graphql-php/type-system/schema/#lazy-loading-of-types))
+- PSR-7 compliant Standard Server (see [docs](http://webonyx.github.io/graphql-php/executing-queries/#using-server))
+- New default error formatting, which does not expose sensitive data (see [docs](http://webonyx.github.io/graphql-php/error-handling/))
+- Ability to define custom error handler to filter/log/re-throw exceptions after execution (see [docs](http://webonyx.github.io/graphql-php/error-handling/#custom-error-handling-and-formatting))
+- Allow defining schema configuration using objects with fluent setters vs array (see [docs](http://webonyx.github.io/graphql-php/type-system/schema/#using-config-class))
+- Allow serializing AST to array and re-creating AST from array lazily (see [docs](http://webonyx.github.io/graphql-php/reference/#graphqlutilsast))
+- [Apollo-style](https://dev-blog.apollodata.com/query-batching-in-apollo-63acfd859862) query batching support via server (see [docs](http://webonyx.github.io/graphql-php/executing-queries/#query-batching))
+- Schema validation, including validation of interface implementations (see [docs](http://webonyx.github.io/graphql-php/type-system/schema/#schema-validation))
+- Ability to pass custom config formatter when defining schema using [GraphQL type language](http://graphql.org/learn/schema/#type-language) (see [docs](http://webonyx.github.io/graphql-php/type-system/type-language/))
+
+Improvements:
+- Significantly improved parser performance (see #137 and #128)
+- Support for PHP7 exceptions everywhere (see #127)
+- Improved [documentation](http://webonyx.github.io/graphql-php/) and docblock comments
+
+Deprecations and breaking changes - see [UPGRADE](UPGRADE.md) document.
+
+#### v0.9.14
+- Minor change to assist DataLoader project in fixing #150 
+
+#### v0.9.13
+- Fixed PHP notice and invalid conversion when non-scalar value is passed as ID or String type (see #121) 
+
+#### v0.9.12
+- Fixed bug occurring when enum `value` is bool, null or float (see #141)
+
+#### v0.9.11
+- Ability to disable introspection (see #131)
+
+#### v0.9.10
+- Fixed issue with query complexity throwing on invalid queries (see #125)
+- Fixed "Out of memory" error when `resolveType` returns unexpected result (see #119)
+
+#### v0.9.9
+- Bugfix: throw UserError vs InvariantViolationError for errors caused by client (see #123)
+
+#### v0.9.8
+- Bugfix: use directives when calculating query complexity (see #113)
+- Bugfix: `AST\Node::__toString()` will convert node to array recursively to encode to json without errors
+
+#### v0.9.7
+- Bugfix: `ResolveInfo::getFieldSelection()` now correctly merges fragment selections (see #98)
+
+#### v0.9.6
+- Bugfix: `ResolveInfo::getFieldSelection()` now respects inline fragments
+
+#### v0.9.5
+- Fixed SyncPromiseAdapter::all() to not change the order of arrays (see #92)
+
+#### v0.9.4
+- Tools to help building schema out of Schema definition language as well as printing existing 
+schema in Schema definition language (see #91)
+
+#### v0.9.3
+- Fixed Utils::assign() bug related to detecting missing required keys (see #89)
+
+#### v0.9.2
+- Schema Definition Language: element descriptions can be set through comments (see #88)
+
+#### v0.9.1
+- Fixed: `GraphQL\Server` now properly sets promise adapter before executing query
+
+## v0.9.0
+- Deferred resolvers (see #66, see [docs](docs/data-fetching.md#solving-n1-problem))
+- New Facade class with fluid interface: `GraphQL\Server` (see #82)
+- Experimental: ability to load types in Schema lazily via custom `TypeResolutionStrategy` (see #69)
+
+
+## v0.8.0
+This release brings several minor breaking changes. Please refer to [UPGRADE](UPGRADE.md) document for details.
+
+New features:
+- Support for `null` value (as required by latest GraphQL spec)
+- Shorthand definitions for field and argument types (see #47)
+- `path` entry in errors produced by resolvers for better debugging
+- `resolveType` for interface/union is now allowed to return string name of type
+- Ability to omit name when extending type class (vs defining inline)
+
+Improvements:
+- Spec compliance improvements
+- New docs and examples
+
+## Older versions
+Look at [GitHub Releases Page](https://github.com/webonyx/graphql-php/releases).

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to GraphQL PHP
+
+## Workflow
+If your contribution requires significant or breaking changes, or if you plan to propose a major new feature,
+we recommend you to create an issue on the [GitHub](https://github.com/webonyx/graphql-php/issues) with
+a brief proposal and discuss it with us first.
+
+For smaller contributions just use this workflow:
+
+* Fork the project.
+* Add your features and or bug fixes.
+* Add tests. Tests are important for us.
+* Check your changes using `composer check-all`.
+* Add an entry to the [Changelog's Unreleases section](CHANGELOG.md#unreleased).
+* Send a pull request.
+
+## Setup the Development Environment
+First, copy the URL of your fork and `git clone` it to your local machine.
+
+```sh
+cd graphql-php
+composer install
+```
+
+## Running tests
+```sh
+./vendor/bin/phpunit
+```
+
+Some tests have annotation `@see it('<description>')`. It is used for reference to same tests in [graphql-js implementation](https://github.com/graphql/graphql-js) with the same description.
+
+## Coding Standard
+The coding standard of this project is based on [Doctrine CS](https://github.com/doctrine/coding-standard).
+
+Run the inspections:
+```sh
+./vendor/bin/phpcs
+```
+
+Apply automatic code style fixes:
+```sh
+./vendor/bin/phpcbf
+```
+
+## Static analysis
+Based on [PHPStan](https://github.com/phpstan/phpstan).
+```sh
+./vendor/bin/phpstan analyse --ansi --memory-limit 256M
+```
+
+## Running benchmarks
+Benchmarks are run via [PHPBench](https://github.com/phpbench/phpbench).
+```sh
+./vendor/bin/phpbench run .
+```

LICENSE

@@ -1,28 +1,21 @@
-Copyright (c) 2015, webonyx
-All rights reserved.
+MIT License
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+Copyright (c) 2015-present, Webonyx, LLC.
 
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
-
-* Neither the name of graphql-php nor the names of its
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,510 +1,52 @@
 # graphql-php
-
-This is a PHP port of GraphQL reference implementation based on the [specification](https://github.com/facebook/graphql)
-and the [reference implementation in JavaScript](https://github.com/graphql/graphql-js).
-
-This implementation will follow JavaScript version as close as possible until GraphQL itself stabilizes.
-
-**Current status**: version 0.4+ supports all features described by specification.
-
 [![Build Status](https://travis-ci.org/webonyx/graphql-php.svg?branch=master)](https://travis-ci.org/webonyx/graphql-php)
+[![Code Coverage](https://scrutinizer-ci.com/g/webonyx/graphql-php/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/webonyx/graphql-php)
+[![Latest Stable Version](https://poser.pugx.org/webonyx/graphql-php/version)](https://packagist.org/packages/webonyx/graphql-php)
+[![License](https://poser.pugx.org/webonyx/graphql-php/license)](https://packagist.org/packages/webonyx/graphql-php)
 
-## Table of Contents
+This is a PHP implementation of the GraphQL [specification](https://github.com/facebook/graphql)
+based on the [reference implementation in JavaScript](https://github.com/graphql/graphql-js).
 
-- [Overview](#overview)
-- [Installation](#installing-graphql-php)
-- [Type System](#type-system)
-    - [Internal Types](#internal-types)
-    - [Enums](#enums)
-    - [Interfaces](#interfaces)
-    - [Objects](#objects)
-    - Unions (TODOC)
-    - [Fields](#fields)
-- [Schema definition](#schema)
-- [Query Resolution and Data Fetching](#query-resolution)
-- [HTTP endpoint example](#http-endpoint)
-- [More Examples](#more-examples)
-- [Complementary Tools](#complementary-tools)
-
-## Overview
-GraphQL is intended to be a replacement for REST APIs. [Read more](http://facebook.github.io/react/blog/2015/05/01/graphql-introduction.html) about rationale behind it.
-
-This PHP implementation is a thin wrapper around your existing data layer and business logic. It doesn't dictate how these layers are implemented or which storage engines are used. Instead it provides tools for creating API for your existing app. These tools include:
-- Type system
-- Schema validation and introspection
-- Ability to parse and execute GraphQL queries against type system
-
-Actual data fetching has to be implemented on the user land.
-
-## Installing graphql-php
+## Installation
+Via composer:
 ```
-$> curl -sS https://getcomposer.org/installer | php
-$> php composer.phar require webonyx/graphql-php='dev-master'
+composer require webonyx/graphql-php
 ```
 
-## Requirements
-PHP >=5.4
+## Documentation
+Full documentation is available on the [Documentation site](https://webonyx.github.io/graphql-php/) as well 
+as in the [docs](docs/) folder of the distribution.
 
-## Getting Started
-First, make sure to read [Getting Started](https://github.com/facebook/graphql#getting-started) section of GraphQL documentation.
-Examples below implement the type system described in this document.
+If you don't know what GraphQL is, visit this [official website](http://graphql.org) 
+by the Facebook engineering team.
 
-### Type System
-To start using GraphQL you are expected to implement a Type system.
+## Examples
+There are several ready examples in the [examples](examples/) folder of the distribution with specific 
+README file per example.
 
-GraphQL PHP provides several *kinds* of types to build hierarchical type system:
- `scalar`, `enum`, `object`, `interface`, `union`, `listOf`, `nonNull`.
+## Contributors
 
-#### Internal types
-Only several `scalar` types are implemented out of the box:
-`ID`, `String`, `Int`, `Float`, `Boolean`
+This project exists thanks to [all the people](https://github.com/webonyx/graphql-php/graphs/contributors) who contribute. [[Contribute](CONTRIBUTING.md)].
 
-As well as two internal modifier types: `ListOf` and `NonNull`.
+## Backers
 
-All internal types are exposed as static methods of `GraphQL\Type\Definition\Type` class:
+<a href="https://opencollective.com/webonyx-graphql-php#backers" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/backers.svg?width=890"></a>
 
-```php
-use GraphQL\Type\Definition\Type;
+## Sponsors
 
-// Internal Scalar types:
-Type::string();  // String type
-Type::int();     // Int type
-Type::float();   // Float type
-Type::boolean(); // Boolean type
-Type::id();      // ID type
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/webonyx-graphql-php#sponsor)]
 
-// Internal wrapping types:
-Type::nonNull(Type::string()) // String! type
-Type::listOf(Type::string())  // String[] type
-```
+<a href="https://opencollective.com/webonyx-graphql-php/sponsor/0/website" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/sponsor/0/avatar.svg"></a>
+<a href="https://opencollective.com/webonyx-graphql-php/sponsor/1/website" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/sponsor/1/avatar.svg"></a>
+<a href="https://opencollective.com/webonyx-graphql-php/sponsor/2/website" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/sponsor/2/avatar.svg"></a>
+<a href="https://opencollective.com/webonyx-graphql-php/sponsor/3/website" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/sponsor/3/avatar.svg"></a>
+<a href="https://opencollective.com/webonyx-graphql-php/sponsor/4/website" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/sponsor/4/avatar.svg"></a>
+<a href="https://opencollective.com/webonyx-graphql-php/sponsor/5/website" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/sponsor/5/avatar.svg"></a>
+<a href="https://opencollective.com/webonyx-graphql-php/sponsor/6/website" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/sponsor/6/avatar.svg"></a>
+<a href="https://opencollective.com/webonyx-graphql-php/sponsor/7/website" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/sponsor/7/avatar.svg"></a>
+<a href="https://opencollective.com/webonyx-graphql-php/sponsor/8/website" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/sponsor/8/avatar.svg"></a>
+<a href="https://opencollective.com/webonyx-graphql-php/sponsor/9/website" target="_blank"><img src="https://opencollective.com/webonyx-graphql-php/sponsor/9/avatar.svg"></a>
 
-Other types must be implemented by your application. Most often you will work with `enum`, `object`, `interface` and `union` type *kinds* to build a type system.
+## License
 
-#### Enums
-Enum types represent a set of allowed values for an object field. Let's define `enum` type describing the set of episodes of original Star Wars trilogy:
-
-```php
-use GraphQL\Type\Definition\EnumType;
-
-/**
- * The original trilogy consists of three movies.
- *
- * This implements the following type system shorthand:
- *   enum Episode { NEWHOPE, EMPIRE, JEDI }
- */
-$episodeEnum = new EnumType([
-    'name' => 'Episode',
-    'description' => 'One of the films in the Star Wars Trilogy',
-    'values' => [
-        'NEWHOPE' => [
-            'value' => 4,
-            'description' => 'Released in 1977.'
-        ],
-        'EMPIRE' => [
-            'value' => 5,
-            'description' => 'Released in 1980.'
-        ],
-        'JEDI' => [
-            'value' => 6,
-            'description' => 'Released in 1983.'
-        ],
-    ]
-]);
-```
-
-#### Interfaces
-Next, let's define a `Character` interface, describing characters of original Star Wars trilogy:
-
-```php
-use GraphQL\Type\Definition\InterfaceType;
-use GraphQL\Type\Definition\Type;
-
-// Implementor types (will be defined in next examples):
-$humanType = null;
-$droidType = null;
-
-/**
- * Characters in the Star Wars trilogy are either humans or droids.
- *
- * This implements the following type system shorthand:
- *   interface Character {
- *     id: String!
- *     name: String
- *     friends: [Character]
- *     appearsIn: [Episode]
- *   }
- */
-$characterInterface = new InterfaceType([
-    'name' => 'Character',
-    'description' => 'A character in the Star Wars Trilogy',
-    'fields' => [
-        'id' => [
-            'type' => Type::nonNull(Type::string()),
-            'description' => 'The id of the character.',
-        ],
-        'name' => [
-            'type' => Type::string(),
-            'description' => 'The name of the character.'
-        ],
-        'friends' => [
-            'type' => function () use (&$characterInterface) {
-                return Type::listOf($characterInterface);
-            },
-            'description' => 'The friends of the character.',
-        ],
-        'appearsIn' => [
-            'type' => Type::listOf($episodeEnum),
-            'description' => 'Which movies they appear in.'
-        ]
-    ],
-    'resolveType' => function ($obj) use (&$humanType, &$droidType) {
-        $humans = StarWarsData::humans();
-        $droids = StarWarsData::droids();
-        if (isset($humans[$obj['id']])) {
-            return $humanType;
-        }
-        if (isset($droids[$obj['id']])) {
-            return $droidType;
-        }
-        return null;
-    },
-]);
-```
-
-As you can see `type` may be optionally defined as `callback` that returns actual type at runtime. (see [Fields](#fields) section for details)
-
-In this example field `friends` represents a list of `characterInterface`. Since at the moment of type definition `characterInterface` is still not defined, we pass in `closure` that will return this type at runtime.
-
-**Interface definition options:**
-
-Option | Type | Notes
------- | ---- | -----
-name | `string` | Required. Unique name of this interface type within Schema
-fields | `array` | Required. List of fields required to be defined by interface implementors. See [Fields](#fields) section for available options.
-description | `string` | Textual description of this interface for clients
-resolveType | `callback(value) => objectType` | Any `callable` that receives data from data layer of your application and returns concrete interface implementor for that data.
-
-
-**Notes**:
-
-1. If `resolveType` option is omitted, GraphQL PHP will loop through all interface implementors and use their `isTypeOf()` method to pick the first suitable one. This is obviously less efficient than single `resolveType` call. So it is recommended to define `resolveType` when possible.
-
-2. Interface types do not participate in data fetching. They just resolve actual `object` type which will be asked for data when GraphQL query is executed.
-
-
-#### Objects
-Now let's define `Human` type that implements `CharacterInterface` from example above:
-
-```php
-use GraphQL\Type\Definition\ObjectType;
-use GraphQL\Type\Definition\Type;
-
-/**
- * We define our human type, which implements the character interface.
- *
- * This implements the following type system shorthand:
- *   type Human : Character {
- *     id: String!
- *     name: String
- *     friends: [Character]
- *     appearsIn: [Episode]
- *   }
- */
-$humanType = new ObjectType([
-    'name' => 'Human',
-    'description' => 'A humanoid creature in the Star Wars universe.',
-    'fields' => [
-        'id' => [
-            'type' => Type::nonNull(Type::string()),
-            'description' => 'The id of the human.',
-        ],
-        'name' => [
-            'type' => Type::string(),
-            'description' => 'The name of the human.',
-        ],
-        'friends' => [
-            'type' => Type::listOf($characterInterface),
-            'description' => 'The friends of the human',
-            'resolve' => function ($human) {
-                return StarWarsData::getFriends($human);
-            },
-        ],
-        'appearsIn' => [
-            'type' => Type::listOf($episodeEnum),
-            'description' => 'Which movies they appear in.'
-        ],
-        'homePlanet' => [
-            'type' => Type::string(),
-            'description' => 'The home planet of the human, or null if unknown.'
-        ],
-    ],
-    'interfaces' => [$characterInterface]
-]);
-```
-
-**Object definition options**
-
-Option | Type | Notes
------- | ---- | -----
-name | `string` | Required. Unique name of this object type within Schema
-fields | `array` | Required. List of fields describing object properties. See [Fields](#Fields) section for available options.
-description | `string` | Textual description of this type for clients
-interfaces | `array` or `callback() => ObjectType[]` | List of interfaces implemented by this type (or callback returning list of interfaces)
-isTypeOf | `callback($value, GraphQL\Type\Definition\ResolveInfo $info)` | Callback that takes `$value` provided by your data layer and returns true if that `$value` qualifies for this type
-
-**Notes:**
-
-1. Both `object` types and `interface` types define set of fields which can have their own types. That's how type composition is implemented.
-
-2. Object types are responsible for data fetching. Each of their fields may have optional `resolve` callback option. This callback takes `$value` that corresponds to instance of this type and returns `data` accepted by type of given field.
-If `resolve` option is not set, GraphQL will try to get `data` from `$value[$fieldName]`.
-
-3. `resolve` callback is a place where you can use your existing data fetching logic.
-
-4. Other `ObjectType` mentioned in examples is `Droid`. Check out tests for this type: https://github.com/webonyx/graphql-php/blob/master/tests/StarWarsSchema.php
-
-
-#### Unions
-TODOC
-
-#### Fields
-
-Fields are parts of [Object](#objects) and [Interface](#interfaces) type definitions.
-
-Allowed Field definition options:
-
-Option | Type | Notes
------- | ---- | -----
-name | `string` | Required. Name of the field. If not set - GraphQL will look use `key` of fields array on type definition.
-type | `Type` or `callback() => Type` | Required. One of internal or custom types. Alternatively - callback that returns `type`.
-args | `array` | Array of possible type arguments. Each entry is expected to be an array with following keys: **name** (`string`), **type** (`Type` or `callback() => Type`), **defaultValue** (`any`)
-resolve | `callback($value, $args, ResolveInfo $info) => $fieldValue` | Function that receives `$value` of parent type and returns value for this field.
-description | `string` | Field description for clients
-deprecationReason | `string` | Text describing why this field is deprecated. When not empty - field will not be returned by introspection queries (unless forced)
-
-
-### Schema
-After all of your types are defined, you must define schema. Schema consists of two special root-level types: `Query` and `Mutation`
-
-`Query` type is a surface of your *read* API. `Mutation` type exposes *write* API by declaring all possible mutations in your app.
-
-Example schema:
-```php
-use GraphQL\Type\Definition\ObjectType;
-use GraphQL\Type\Definition\Type;
-use GraphQL\Schema;
-
-/**
- * This is the type that will be the root of our query, and the
- * entry point into our schema. It gives us the ability to fetch
- * objects by their IDs, as well as to fetch the undisputed hero
- * of the Star Wars trilogy, R2-D2, directly.
- *
- * This implements the following type system shorthand:
- *   type Query {
- *     hero(episode: Episode): Character
- *     human(id: String!): Human
- *     droid(id: String!): Droid
- *   }
- *
- */
-$queryType = new ObjectType([
-    'name' => 'Query',
-    'fields' => [
-        'hero' => [
-            'type' => $characterInterface,
-            'args' => [
-                'episode' => [
-                    'description' => 'If omitted, returns the hero of the whole saga. If provided, returns the hero of that particular episode.',
-                    'type' => $episodeEnum
-                ]
-            ],
-            'resolve' => function ($root, $args) {
-                return StarWarsData::getHero(isset($args['episode']) ? $args['episode'] : null);
-            },
-        ],
-        'human' => [
-            'type' => $humanType,
-            'args' => [
-                'id' => [
-                    'name' => 'id',
-                    'description' => 'id of the human',
-                    'type' => Type::nonNull(Type::string())
-                ]
-            ],
-            'resolve' => function ($root, $args) {
-                $humans = StarWarsData::humans();
-                return isset($humans[$args['id']]) ? $humans[$args['id']] : null;
-            }
-        ],
-        'droid' => [
-            'type' => $droidType,
-            'args' => [
-                'id' => [
-                    'name' => 'id',
-                    'description' => 'id of the droid',
-                    'type' => Type::nonNull(Type::string())
-                ]
-            ],
-            'resolve' => function ($root, $args) {
-                $droids = StarWarsData::droids();
-                return isset($droids[$args['id']]) ? $droids[$args['id']] : null;
-            }
-        ]
-    ]
-]);
-
-// TODOC
-$mutationType = null;
-
-$schema = new Schema($queryType, $mutationType);
-```
-
-**Notes:**
-
-1. `Query` is a regular `object` type.
-
-2. Fields of this type represent all possible root-level queries to your API.
-
-3. Fields can have `args`, so that your queries could be dynamic (see [Fields](#fields) section).
-
-
-### Query Resolution
-Resolution is a cascading process that starts from root `Query` type.
-
-In our example `Query` type exposes field `human` that expects `id` argument. Say we receive following GraphQL query that requests data for Luke Skywalker:
-```
-query FetchLukeQuery {
-  human(id: "1000") {
-    name
-    friends {
-      name
-    }
-  }
-}
-```
-
-And that's how our data for Luke looks like (in some internal storage):
-```
-$lukeData = [
-    'id' => '1000',
-    'name' => 'Luke Skywalker',
-    'friends' => ['1002', '1003', '2000', '2001'],
-    'appearsIn' => [4, 5, 6],
-    'homePlanet' => 'Tatooine',
-]
-```
-
-What happens:
-
-1. GraphQL query is parsed and validated against schema (it happens in `GraphQL\GraphQL::execute()` method)
-2. GraphQL executor detects that field `human` of `Human` type is requested at root `Query` level
-3. It calls `resolve(null, ['id' => 1000])` on this field (note first argument is null at the root level)
-4. `resolve` callback of `human` field fetches our data by id and returns it
-5. Since field `human` is expected to return type `Human` GraphQL traverses all requested fields of type `Human` and matches them against `$lukeData`
-6. Requested field `name` on `Human` type does not provide any `resolve` callback, so GraphQL simply resolves it as `$lukeData['name']`
-7. Requested field `friend` has `resolve` callback, so it is called: `resolve($lukeData, /*args*/ [], ResolveInfo $info)`
-8. Callback fetches data for all `$lukeData['friends']` and returns `[$friend1002, $friend1003, ...]` where each entry contains array with same structure as `$lukeData`
-9. GraphQL executor repeats these steps until all requested leaf fields are reached
-10. Final result is composed and returned:
-```
-[
-    'human' => [
-        'name' => 'Luke Skywalker',
-        'friends' => [
-            ['name' => 'Han Solo'],
-            ['name' => 'Leia Organa'],
-            ['name' => 'C-3PO'],
-            ['name' => 'R2-D2'],
-        ]
-    ]
-]
-```
-
-### HTTP endpoint
-Specification for GraphQL HTTP endpoint is still under development.
-But you can use following naive example to build your own custom HTTP endpoint that is ready to accept GraphQL queries:
-
-```php
-use GraphQL\GraphQL;
-use \Exception;
-
-if (isset($_SERVER['CONTENT_TYPE']) && $_SERVER['CONTENT_TYPE'] === 'application/json') {
-    $rawBody = file_get_contents('php://input');
-    $data = json_decode($rawBody ?: '', true);
-} else {
-    $data = $_POST;
-}
-
-$requestString = isset($data['query']) ? $data['query'] : null;
-$operationName = isset($data['operation']) ? $data['operation'] : null;
-$variableValues = isset($data['variables']) ? $data['variables'] : null;
-
-try {
-    // Define your schema:
-    $schema = MyApp\Schema::build();
-    $result = GraphQL::execute(
-        $schema,
-        $requestString,
-        /* $rootValue */ null,
-        $variableValues,
-        $operationName
-    );
-} catch (Exception $exception) {
-    $result = [
-        'errors' => [
-            ['message' => $exception->getMessage()]
-        ]
-    ];
-}
-
-header('Content-Type: application/json');
-echo json_encode($result);
-```
-
-### Security
-
-#### Query Complexity Analysis
-
-This is a PHP port of [Query Complexity Analysis](http://sangria-graphql.org/learn/#query-complexity-analysis) in Sangria implementation.
-Introspection query with description max complexity is **109**.
-
-This document validator rule is disabled by default. Here an example to enabled it:
-
-```php
-use GraphQL\GraphQL;
-
-/** @var \GraphQL\Validator\Rules\QueryComplexity $queryComplexity */
-$queryComplexity = DocumentValidator::getRule('QueryComplexity');
-$queryComplexity->setMaxQueryComplexity($maxQueryComplexity = 110);
-
-GraphQL::execute(/*...*/);
-```
-
-#### Limiting Query Depth
-
-This is a PHP port of [Limiting Query Depth](http://sangria-graphql.org/learn/#limiting-query-depth) in Sangria implementation.
-Introspection query with description max depth is **7**.
-
-This document validator rule is disabled by default. Here an example to enabled it:
-
-```php
-use GraphQL\GraphQL;
-
-/** @var \GraphQL\Validator\Rules\QueryDepth $queryDepth */
-$queryDepth = DocumentValidator::getRule('QueryDepth');
-$queryDepth->setMaxQueryDepth($maxQueryDepth = 10);
-
-GraphQL::execute(/*...*/);
-```
-
-### More Examples
-Make sure to check [tests](https://github.com/webonyx/graphql-php/tree/master/tests) for more usage examples.
-
-### Complementary Tools
-- [Integration with Relay](https://github.com/ivome/graphql-relay-php)
-- [Use GraphQL with Laravel 5](https://github.com/Folkloreatelier/laravel-graphql)
-- [Relay helpers for laravel-graphql](https://github.com/nuwave/laravel-graphql-relay)
-- [GraphQL and Relay with Symfony2](https://github.com/overblog/GraphQLBundle)
-
-Also check [Awesome GraphQL](https://github.com/chentsulin/awesome-graphql) for full picture of GraphQL ecosystem.
+See [LICENSE](LICENSE).

UPGRADE.md

@@ -0,0 +1,532 @@
+## Master
+
+### Breaking (major): dropped deprecations
+ - dropped deprecated `GraphQL\Schema`. Use `GraphQL\Type\Schema`.
+
+## Upgrade v0.12.x > v0.13.x
+
+### Breaking (major): minimum supported version of PHP
+New minimum required version of PHP is **7.1+**
+
+### Breaking (major): default errors formatting changed according to spec 
+**Category** and extensions assigned to errors are shown under `extensions` key
+```php
+$e = new Error(
+    'msg',
+    null,
+    null,
+    null,
+    null,
+    null,
+    ['foo' => 'bar']
+);
+```
+Formatting before the change:
+```
+'errors' => [
+    [
+        'message' => 'msg',
+        'category' => 'graphql',
+        'foo' => 'bar'
+    ]
+]
+```
+After the change:
+```
+'errors' => [
+    [
+        'message' => 'msg',
+        'extensions' => [
+            'category' => 'graphql',
+            'foo' => 'bar',
+        ],
+    ]
+]
+```
+
+Note: if error extensions contain `category` key - it has a priority over default category.
+
+You can always switch to [custom error formatting](https://webonyx.github.io/graphql-php/error-handling/#custom-error-handling-and-formatting) to revert to the old format.
+
+### Try it: Experimental Executor with improved performance
+It is disabled by default. To enable it, do the following
+```php
+<?php
+use GraphQL\Executor\Executor;
+use GraphQL\Experimental\Executor\CoroutineExecutor;
+
+Executor::setImplementationFactory([CoroutineExecutor::class, 'create']);
+```
+
+**Please post your feedback about new executor at https://github.com/webonyx/graphql-php/issues/397
+Especially if you had issues (because it may become the default in one of the next releases)**
+
+### Breaking: multiple interfaces separated with & in SDL
+Before the change:
+```graphql
+type Foo implements Bar, Baz { field: Type }
+```
+
+After the change:
+```graphql
+type Foo implements Bar & Baz { field: Type }
+```
+
+To allow for an adaptive migration, use `allowLegacySDLImplementsInterfaces` option of parser:
+```php
+Parser::parse($source, [ 'allowLegacySDLImplementsInterfaces' => true])
+```
+
+### Breaking: several classes renamed
+
+- `AbstractValidationRule` renamed to `ValidationRule` (NS `GraphQL\Validator\Rules`)
+- `AbstractQuerySecurity` renamed to `QuerySecurityRule` (NS `GraphQL\Validator\Rules`)
+- `FindBreakingChanges` renamed to `BreakingChangesFinder` (NS `GraphQL\Utils`)
+
+### Breaking: new constructors
+
+`GraphQL\Type\Definition\ResolveInfo` now takes 10 arguments instead of one array.
+
+## Upgrade v0.11.x > v0.12.x
+
+### Breaking: Minimum supported version is PHP5.6
+Dropped support for PHP 5.5. This release still supports PHP 5.6 and PHP 7.0
+**But the next major release will require PHP7.1+**
+
+### Breaking: Custom scalar types need to throw on invalid value
+As null might be a valid value custom types need to throw an
+Exception inside `parseLiteral()`, `parseValue()` and `serialize()`. 
+
+Returning null from any of these methods will now be treated as valid result.
+
+### Breaking: Custom scalar types parseLiteral() declaration changed
+A new parameter was added to `parseLiteral()`, which also needs to be added to any custom scalar type extending from `ScalarType`
+
+Before:
+```php
+class MyType extends ScalarType {
+
+    ...
+
+    public function parseLiteral($valueNode) {
+        //custom implementation
+    }
+}
+```
+
+After:
+```php
+class MyType extends ScalarType {
+
+    ...
+
+    public function parseLiteral($valueNode, array $variables = null) {
+        //custom implementation
+    }
+}
+```
+
+### Breaking: Descriptions in comments are not used as descriptions by default anymore
+Descriptions now need to be inside Strings or BlockStrings in order to be picked up as
+description. If you want to keep the old behaviour you can supply the option `commentDescriptions`
+to BuildSchema::buildAST(), BuildSchema::build() or Printer::doPrint().
+
+Here is the official way now to define descriptions in the graphQL language:
+
+Old:
+
+```graphql
+# Description
+type Dog {
+  ...
+}
+```
+
+New:
+
+```graphql
+"Description"
+type Dog {
+  ...
+}
+
+"""
+Long Description
+"""
+type Dog {
+  ...
+}
+```
+
+### Breaking: Cached AST of version 0.11.x is not compatible with 0.12.x.
+That's because description in AST is now a separate node, not just a string. 
+Make sure to renew caches.
+
+### Breaking: Most of previously deprecated classes and methods were removed
+See deprecation notices for previous versions in details.
+
+### Breaking: Standard server expects `operationName` vs `operation` for multi-op queries
+Before the change:
+```json
+{
+  "queryId": "persisted-query-id",
+  "operation": "QueryFromPersistedDocument",
+  "variables": {}
+}
+```
+After the change:
+```json
+{
+  "queryId": "persisted-query-id",
+  "operationName": "QueryFromPersistedDocument",
+  "variables": {}
+}
+```
+This naming is aligned with graphql-express version.
+
+### Possibly Breaking: AST to array serialization excludes nulls
+Most users won't be affected. It *may* affect you only if you do your own manipulations 
+with exported AST. 
+
+Example of json-serialized AST before the change:
+```json
+{
+    "kind": "Field",
+    "loc": null,
+    "name": {
+        "kind": "Name",
+        "loc": null,
+        "value": "id"
+    },
+    "alias": null,
+    "arguments": [],
+    "directives": [],
+    "selectionSet": null
+}
+```
+After the change:
+```json
+{
+    "kind": "Field",
+    "name": {
+        "kind": "Name",
+        "value": "id"
+    },
+    "arguments": [],
+    "directives": []
+}
+```
+
+## Upgrade v0.8.x, v0.9.x > v0.10.x
+
+### Breaking: changed minimum PHP version from 5.4 to 5.5
+It allows us to leverage `::class` constant, `generators` and other features of newer PHP versions.
+
+### Breaking: default error formatting
+By default exceptions thrown in resolvers will be reported with generic message `"Internal server error"`.
+Only exceptions implementing interface `GraphQL\Error\ClientAware` and claiming themselves as `safe` will 
+be reported with full error message.
+
+This breaking change is done to avoid information leak in production when unhandled 
+exceptions were reported to clients (e.g. database connection errors, file access errors, etc).
+
+Also every error reported to client now has new `category` key which is either `graphql` or `internal`.
+Exceptions implementing `ClientAware` interface may define their own custom categories.
+
+During development or debugging use `$executionResult->toArray(true)`. It will add `debugMessage` key to 
+each error entry in result. If you also want to add `trace` for each error - pass flags instead:
+
+```
+use GraphQL\Error\FormattedError;
+$debug = FormattedError::INCLUDE_DEBUG_MESSAGE | FormattedError::INCLUDE_TRACE;
+$result = GraphQL::executeAndReturnResult(/*args*/)->toArray($debug);
+```
+
+To change default `"Internal server error"` message to something else, use: 
+```
+GraphQL\Error\FormattedError::setInternalErrorMessage("Unexpected error");
+```
+
+**This change only affects default error reporting mechanism. If you set your own error formatter using 
+`$executionResult->setErrorFormatter($myFormatter)` you won't be affected by this change.**
+
+If you need to revert to old behavior temporary, use:
+
+```php
+GraphQL::executeAndReturnResult(/**/)
+    ->setErrorFormatter('\GraphQL\Error\Error::formatError')
+    ->toArray();
+```
+But note that this is deprecated format and will be removed in future versions. 
+
+In general, if new default formatting doesn't work for you - just set [your own error
+formatter](http://webonyx.github.io/graphql-php/error-handling/#custom-error-handling-and-formatting).
+
+### Breaking: Validation rules now have abstract base class
+Previously any callable was accepted by DocumentValidator as validation rule. Now only instances of 
+`GraphQL\Validator\Rules\AbstractValidationRule` are allowed.
+
+If you were using custom validation rules, just wrap them with 
+`GraphQL\Validator\Rules\CustomValidationRule` (created for backwards compatibility).
+
+Before:
+```php
+use GraphQL\Validator\DocumentValidator;
+
+$myRule = function(ValidationContext $context) {};
+DocumentValidator::validate($schema, $ast, [$myRule]);
+```
+
+After:
+```php
+use GraphQL\Validator\Rules\CustomValidationRule;
+use GraphQL\Validator\DocumentValidator;
+
+$myRule = new CustomValidationRule('MyRule', function(ValidationContext $context) {});
+DocumentValidator::validate($schema, $ast, [$myRule]);
+```
+
+Also `DocumentValidator::addRule()` signature changed. 
+
+Before the change:
+```php
+use GraphQL\Validator\DocumentValidator;
+
+$myRule = function(ValidationContext $context) {};
+DocumentValidator::addRule('MyRuleName', $myRule);
+```
+
+After the change:
+```php
+use GraphQL\Validator\DocumentValidator;
+
+$myRule = new CustomValidationRulefunction('MyRule', ValidationContext $context) {});
+DocumentValidator::addRule($myRule);
+```
+
+
+### Breaking: AST now uses `NodeList` vs array for lists of nodes
+It helps us unserialize AST from array lazily. This change affects you only if you use `array_`
+functions with AST or mutate AST directly.
+
+Before the change:
+```php
+new GraphQL\Language\AST\DocumentNode([
+    'definitions' => array(/*...*/)
+]);
+```
+After the change:
+```
+new GraphQL\Language\AST\DocumentNode([
+    'definitions' => new NodeList([/*...*/])
+]);
+```
+
+
+### Breaking: scalar types now throw different exceptions when parsing and serializing
+On invalid client input (`parseValue` and `parseLiteral`) they throw standard `GraphQL\Error\Error` 
+but when they encounter invalid output (in `serialize`) they throw `GraphQL\Error\InvariantViolation`.
+
+Previously they were throwing `GraphQL\Error\UserError`. This exception is no longer used so make sure 
+to adjust if you were checking for this error in your custom error formatters.
+
+### Breaking: removed previously deprecated ability to define type as callable
+See https://github.com/webonyx/graphql-php/issues/35
+
+### Deprecated: `GraphQL\GraphQL::executeAndReturnResult` 
+Method is renamed to `GraphQL\GraphQL::executeQuery`. Old method name is still available, 
+but will trigger deprecation warning in the next version.
+
+### Deprecated: `GraphQL\GraphQL::execute`
+Use `GraphQL\GraphQL::executeQuery()->toArray()` instead.
+Old method still exists, but will trigger deprecation warning in next version.
+
+### Deprecated: `GraphQL\Schema` moved to `GraphQL\Type\Schema`
+Old class still exists, but will trigger deprecation warning in next version.
+
+### Deprecated: `GraphQL\Utils` moved to `GraphQL\Utils\Utils`
+Old class still exists, but triggers deprecation warning when referenced.
+
+### Deprecated: `GraphQL\Type\Definition\Config`
+If you were using config validation in previous versions, replace:
+```php
+GraphQL\Type\Definition\Config::enableValidation();
+```
+with: 
+```php
+$schema->assertValid();
+``` 
+See https://github.com/webonyx/graphql-php/issues/148
+
+### Deprecated: experimental `GraphQL\Server`
+Use [new PSR-7 compliant implementation](docs/executing-queries.md#using-server) instead.
+
+### Deprecated: experimental `GraphQL\Type\Resolution` interface and implementations
+Use schema [**typeLoader** option](docs/type-system/schema.md#lazy-loading-of-types) instead.
+
+### Non-breaking: usage on async platforms
+When using the library on async platforms use separate method `GraphQL::promiseToExecute()`. 
+It requires promise adapter in it's first argument and always returns a `Promise`.
+
+Old methods `GraphQL::execute` and `GraphQL::executeAndReturnResult` still work in backwards-compatible manner, 
+but they are deprecated and will be removed eventually.
+
+Same applies to Executor: use `Executor::promiseToExecute()` vs `Executor::execute()`.
+
+## Upgrade v0.7.x > v0.8.x
+All of those changes apply to those who extends various parts of this library.
+If you only use the library and don't try to extend it - everything should work without breaks.
+
+
+### Breaking: Custom directives handling
+When passing custom directives to schema, default directives (like `@skip` and `@include`) 
+are not added to schema automatically anymore. If you need them - add them explicitly with 
+your other directives.
+
+Before the change:
+```php
+$schema = new Schema([
+   // ...
+   'directives' => [$myDirective]
+]);
+```
+
+After the change:
+```php
+$schema = new Schema([
+    // ...
+    'directives' => array_merge(GraphQL::getInternalDirectives(), [$myDirective])
+]);
+```
+
+### Breaking: Schema protected property and methods visibility 
+Most of the `protected` properties and methods of `GraphQL\Schema` were changed to `private`.
+Please use public interface instead.
+
+### Breaking: Node kind constants
+Node kind constants were extracted from `GraphQL\Language\AST\Node` to 
+separate class `GraphQL\Language\AST\NodeKind`
+
+### Non-breaking: AST node classes renamed
+AST node classes were renamed to disambiguate with types. e.g.:
+
+```
+GraphQL\Language\AST\Field -> GraphQL\Language\AST\FieldNode
+GraphQL\Language\AST\OjbectValue -> GraphQL\Language\AST\OjbectValueNode
+```
+etc. 
+
+Old names are still available via `class_alias` defined in `src/deprecated.php`. 
+This file is included automatically when using composer autoloading.
+
+### Deprecations
+There are several deprecations which still work, but trigger `E_USER_DEPRECATED` when used.
+
+For example `GraphQL\Executor\Executor::setDefaultResolveFn()` is renamed to `setDefaultResolver()`
+but still works with old name.
+
+## 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 as 3rd argument. 
+This can for example be used to pass the current user etc.
+
+Make sure to update all calls to `GraphQL::execute`, `GraphQL::executeAndReturnResult`, `Executor::execute` and all 
+`'resolve'` callbacks in your app.
+ 
+Before v0.7.0 `GraphQL::execute` signature looked this way:
+ ```php
+ GraphQL::execute(
+     $schema,
+     $query,
+     $rootValue,
+     $variables,
+     $operationName
+ );
+ ```
+
+Starting from v0.7.0 the signature looks this way (note the new `$context` argument):
+```php
+GraphQL::execute(
+    $schema,
+    $query,
+    $rootValue,
+    $context,
+    $variables,
+    $operationName
+);
+```
+
+Before v.0.7.0 resolve callbacks had following signature:
+```php
+/**
+ * @param mixed $object The parent resolved object
+ * @param array $args Input arguments
+ * @param ResolveInfo $info ResolveInfo object
+ * @return mixed
+ */
+function resolveMyField($object, array $args, ResolveInfo $info) {
+    //...
+}
+```
+
+Starting from v0.7.0 the signature has changed to (note the new `$context` argument): 
+```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:
+ 
+Before v0.7.0:
+```php
+$schema = new Schema($queryType, $mutationType);
+```
+
+Starting from v0.7.0:
+```php
+$schema = new Schema([
+    'query' => $queryType,
+    'mutation' => $mutationType,
+    'types' => $arrayOfTypesWithInterfaces // See 3.
+]);
+```
+
+### 3. Types can be directly passed to schema
+
+There are edge cases when GraphQL cannot infer some types from your schema. 
+One example is when you define a field of interface type and object types implementing 
+this interface are not referenced anywhere else.
+
+In such case object 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 that GraphQL knows of their existence during query validation.
+
+For example:
+```php
+$schema = new Schema([
+    'query' => $queryType,
+    'mutation' => $mutationType,
+    'types' => $arrayOfTypesWithInterfaces
+]);
+```
+
+Note that you don't need to pass all types here - only those types that GraphQL "doesn't see" 
+automatically. Before v7.0.0 the workaround for this was to create a dumb (non-used) field per 
+each "invisible" object type.
+
+Also see [webonyx/graphql-php#38](https://github.com/webonyx/graphql-php/issues/38)

benchmarks/HugeSchemaBench.php

@@ -0,0 +1,75 @@
+<?php
+namespace GraphQL\Benchmarks;
+
+use GraphQL\Benchmarks\Utils\QueryGenerator;
+use GraphQL\Benchmarks\Utils\SchemaGenerator;
+use GraphQL\GraphQL;
+use GraphQL\Type\Schema;
+use GraphQL\Type\SchemaConfig;
+
+/**
+ * @BeforeMethods({"setUp"})
+ * @OutputTimeUnit("milliseconds", precision=3)
+ * @Warmup(1)
+ * @Revs(5)
+ * @Iterations(1)
+ */
+class HugeSchemaBench
+{
+    /** @var SchemaGenerator */
+    private $schemaBuilder;
+
+    private $schema;
+
+    /** @var string */
+    private $smallQuery;
+
+    public function setUp()
+    {
+        $this->schemaBuilder = new SchemaGenerator([
+            'totalTypes' => 600,
+            'fieldsPerType' => 8,
+            'listFieldsPerType' => 2,
+            'nestingLevel' => 10,
+        ]);
+
+        $this->schema = $this->schemaBuilder->buildSchema();
+
+        $queryBuilder     = new QueryGenerator($this->schema, 0.05);
+        $this->smallQuery = $queryBuilder->buildQuery();
+    }
+
+    public function benchSchema()
+    {
+        $this->schemaBuilder
+            ->buildSchema()
+            ->getTypeMap();
+    }
+
+    public function benchSchemaLazy()
+    {
+        $this->createLazySchema();
+    }
+
+    public function benchSmallQuery()
+    {
+        $result = GraphQL::executeQuery($this->schema, $this->smallQuery);
+    }
+
+    public function benchSmallQueryLazy()
+    {
+        $schema = $this->createLazySchema();
+        $result = GraphQL::executeQuery($schema, $this->smallQuery);
+    }
+
+    private function createLazySchema()
+    {
+        return new Schema(
+            SchemaConfig::create()
+                ->setQuery($this->schemaBuilder->buildQueryType())
+                ->setTypeLoader(function ($name) {
+                    return $this->schemaBuilder->loadType($name);
+                })
+        );
+    }
+}

benchmarks/LexerBench.php

@@ -0,0 +1,35 @@
+<?php
+namespace GraphQL\Benchmarks;
+
+use GraphQL\Language\Lexer;
+use GraphQL\Language\Source;
+use GraphQL\Language\Token;
+use GraphQL\Type\Introspection;
+
+/**
+ * @BeforeMethods({"setUp"})
+ * @OutputTimeUnit("milliseconds", precision=3)
+ */
+class LexerBench
+{
+    private $introQuery;
+
+    public function setUp()
+    {
+        $this->introQuery = new Source(Introspection::getIntrospectionQuery());
+    }
+
+    /**
+     * @Warmup(2)
+     * @Revs(100)
+     * @Iterations(5)
+     */
+    public function benchIntrospectionQuery()
+    {
+        $lexer = new Lexer($this->introQuery);
+
+        do {
+            $token = $lexer->advance();
+        } while ($token->kind !== Token::EOF);
+    }
+}

benchmarks/StarWarsBench.php

@@ -0,0 +1,98 @@
+<?php
+namespace GraphQL\Benchmarks;
+
+use GraphQL\GraphQL;
+use GraphQL\Tests\StarWarsSchema;
+use GraphQL\Type\Introspection;
+
+/**
+ * @BeforeMethods({"setIntroQuery"})
+ * @OutputTimeUnit("milliseconds", precision=3)
+ * @Warmup(2)
+ * @Revs(10)
+ * @Iterations(2)
+ */
+class StarWarsBench
+{
+    private $introQuery;
+
+    public function setIntroQuery()
+    {
+        $this->introQuery = Introspection::getIntrospectionQuery();
+    }
+
+    public function benchSchema()
+    {
+        StarWarsSchema::build();
+    }
+
+    public function benchHeroQuery()
+    {
+        $q = '
+        query HeroNameQuery {
+          hero {
+            name
+          }
+        }
+        ';
+
+        GraphQL::executeQuery(
+            StarWarsSchema::build(),
+            $q
+        );
+    }
+
+    public function benchNestedQuery()
+    {
+        $q = '
+        query NestedQuery {
+          hero {
+            name
+            friends {
+              name
+              appearsIn
+              friends {
+                name
+              }
+            }
+          }
+        }
+        ';
+        GraphQL::executeQuery(
+            StarWarsSchema::build(),
+            $q
+        );
+    }
+
+    public function benchQueryWithFragment()
+    {
+        $q = '
+        query UseFragment {
+          luke: human(id: "1000") {
+            ...HumanFragment
+          }
+          leia: human(id: "1003") {
+            ...HumanFragment
+          }
+        }
+
+        fragment HumanFragment on Human {
+          name
+          homePlanet
+        }
+        ';
+
+        GraphQL::executeQuery(
+            StarWarsSchema::build(),
+            $q
+        );
+    }
+
+    public function benchStarWarsIntrospectionQuery()
+    {
+        GraphQL::executeQuery(
+            StarWarsSchema::build(),
+            $this->introQuery
+        );
+    }
+}

benchmarks/Utils/QueryGenerator.php

@@ -0,0 +1,105 @@
+<?php
+namespace GraphQL\Benchmarks\Utils;
+
+use GraphQL\Language\AST\DocumentNode;
+use GraphQL\Language\AST\FieldNode;
+use GraphQL\Language\AST\NameNode;
+use GraphQL\Language\AST\OperationDefinitionNode;
+use GraphQL\Language\AST\SelectionSetNode;
+use GraphQL\Language\Printer;
+use GraphQL\Type\Definition\FieldDefinition;
+use GraphQL\Type\Definition\InterfaceType;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\WrappingType;
+use GraphQL\Type\Schema;
+use GraphQL\Utils\Utils;
+use function count;
+use function max;
+use function round;
+
+class QueryGenerator
+{
+    private $schema;
+
+    private $maxLeafFields;
+
+    private $currentLeafFields;
+
+    public function __construct(Schema $schema, $percentOfLeafFields)
+    {
+        $this->schema = $schema;
+
+        Utils::invariant(0 < $percentOfLeafFields && $percentOfLeafFields <= 1);
+
+        $totalFields = 0;
+        foreach ($schema->getTypeMap() as $type) {
+            if (! ($type instanceof ObjectType)) {
+                continue;
+            }
+
+            $totalFields += count($type->getFields());
+        }
+
+        $this->maxLeafFields     = max(1, round($totalFields * $percentOfLeafFields));
+        $this->currentLeafFields = 0;
+    }
+
+    public function buildQuery()
+    {
+        $qtype = $this->schema->getQueryType();
+
+        $ast = new DocumentNode([
+            'definitions' => [new OperationDefinitionNode([
+                'name' => new NameNode(['value' => 'TestQuery']),
+                'operation' => 'query',
+                'selectionSet' => $this->buildSelectionSet($qtype->getFields()),
+            ]),
+            ],
+        ]);
+
+        return Printer::doPrint($ast);
+    }
+
+    /**
+     * @param FieldDefinition[] $fields
+     *
+     * @return SelectionSetNode
+     */
+    public function buildSelectionSet($fields)
+    {
+        $selections[] = new FieldNode([
+            'name' => new NameNode(['value' => '__typename']),
+        ]);
+        $this->currentLeafFields++;
+
+        foreach ($fields as $field) {
+            if ($this->currentLeafFields >= $this->maxLeafFields) {
+                break;
+            }
+
+            $type = $field->getType();
+
+            if ($type instanceof WrappingType) {
+                $type = $type->getWrappedType(true);
+            }
+
+            if ($type instanceof ObjectType || $type instanceof InterfaceType) {
+                $selectionSet = $this->buildSelectionSet($type->getFields());
+            } else {
+                $selectionSet = null;
+                $this->currentLeafFields++;
+            }
+
+            $selections[] = new FieldNode([
+                'name' => new NameNode(['value' => $field->name]),
+                'selectionSet' => $selectionSet,
+            ]);
+        }
+
+        $selectionSet = new SelectionSetNode([
+            'selections' => $selections,
+        ]);
+
+        return $selectionSet;
+    }
+}

benchmarks/Utils/SchemaGenerator.php

@@ -0,0 +1,159 @@
+<?php
+namespace GraphQL\Benchmarks\Utils;
+
+use GraphQL\Type\Definition\EnumType;
+use GraphQL\Type\Definition\InputObjectType;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Schema;
+
+class SchemaGenerator
+{
+    private $config = [
+        'totalTypes' => 100,
+        'nestingLevel' => 10,
+        'fieldsPerType' => 10,
+        'listFieldsPerType' => 2
+    ];
+
+    private $typeIndex = 0;
+
+    private $objectTypes = [];
+
+    /**
+     * BenchmarkSchemaBuilder constructor.
+     * @param array $config
+     */
+    public function __construct(array $config)
+    {
+        $this->config = array_merge($this->config, $config);
+    }
+
+    public function buildSchema()
+    {
+        return new Schema([
+            'query' => $this->buildQueryType()
+        ]);
+    }
+
+    public function buildQueryType()
+    {
+        $this->typeIndex = 0;
+        $this->objectTypes = [];
+
+        return $this->createType(0);
+    }
+
+    public function loadType($name)
+    {
+        $tokens = explode('_', $name);
+        $nestingLevel = (int) $tokens[1];
+
+        return $this->createType($nestingLevel, $name);
+    }
+
+    protected function createType($nestingLevel, $typeName = null)
+    {
+        if ($this->typeIndex > $this->config['totalTypes']) {
+            throw new \Exception(
+                "Cannot create new type: there are already {$this->typeIndex} ".
+                "which exceeds allowed number of {$this->config['totalTypes']} types total"
+            );
+        }
+
+        $this->typeIndex++;
+        if (!$typeName) {
+            $typeName = 'Level_' . $nestingLevel . '_Type' . $this->typeIndex;
+        }
+
+        $type = new ObjectType([
+            'name' => $typeName,
+            'fields' => function() use ($typeName, $nestingLevel) {
+                return $this->createTypeFields($typeName, $nestingLevel + 1);
+            }
+        ]);
+
+        $this->objectTypes[$typeName] = $type;
+        return $type;
+    }
+
+    protected function getFieldTypeAndName($nestingLevel, $fieldIndex)
+    {
+        if ($nestingLevel >= $this->config['nestingLevel']) {
+            $fieldType = Type::string();
+            $fieldName = 'leafField' . $fieldIndex;
+        } else if ($this->typeIndex >= $this->config['totalTypes']) {
+            $fieldType = $this->objectTypes[array_rand($this->objectTypes)];
+            $fieldName = 'randomTypeField' . $fieldIndex;
+        } else {
+            $fieldType = $this->createType($nestingLevel);
+            $fieldName = 'field' . $fieldIndex;
+        }
+
+        return [$fieldType, $fieldName];
+    }
+
+    protected function createTypeFields($typeName, $nestingLevel)
+    {
+        $fields = [];
+        for ($index = 0; $index < $this->config['fieldsPerType']; $index++) {
+            list($type, $name) = $this->getFieldTypeAndName($nestingLevel, $index);
+            $fields[] = [
+                'name' => $name,
+                'type' => $type,
+                'resolve' => [$this, 'resolveField']
+            ];
+        }
+        for ($index = 0; $index < $this->config['listFieldsPerType']; $index++) {
+            list($type, $name) = $this->getFieldTypeAndName($nestingLevel, $index);
+            $name = 'listOf' . ucfirst($name);
+
+            $fields[] = [
+                'name' => $name,
+                'type' => Type::listOf($type),
+                'args' => $this->createFieldArgs($name, $typeName),
+                'resolve' => function() {
+                    return [
+                        'string1',
+                        'string2',
+                        'string3',
+                        'string4',
+                        'string5',
+                    ];
+                }
+            ];
+        }
+        return $fields;
+    }
+
+    protected function createFieldArgs($fieldName, $typeName)
+    {
+        return [
+            'argString' => [
+                'type' => Type::string()
+            ],
+            'argEnum' => [
+                'type' => new EnumType([
+                    'name' => $typeName . $fieldName . 'Enum',
+                    'values' => [
+                        "ONE", "TWO", "THREE"
+                    ]
+                ])
+            ],
+            'argInputObject' => [
+                'type' => new InputObjectType([
+                    'name' => $typeName . $fieldName . 'Input',
+                    'fields' => [
+                        'field1' => Type::string(),
+                        'field2' => Type::int()
+                    ]
+                ])
+            ]
+        ];
+    }
+
+    public function resolveField($objectValue, $args, $context, $resolveInfo)
+    {
+        return $resolveInfo->fieldName . '-value';
+    }
+}

composer.json

@@ -2,20 +2,31 @@
   "name":              "webonyx/graphql-php",
   "description":       "A PHP port of GraphQL reference implementation",
   "type":              "library",
-  "license":           "BSD",
+  "license":           "MIT",
   "homepage":          "https://github.com/webonyx/graphql-php",
   "keywords":          [
     "graphql",
     "API"
   ],
   "require": {
-    "php": ">=5.4,<8.0-DEV"
+    "php": "^7.1||^8.0",
+    "ext-json": "*",
+    "ext-mbstring": "*"
   },
   "require-dev": {
-    "phpunit/phpunit": "^4.8"
+    "doctrine/coding-standard": "^6.0",
+    "phpbench/phpbench": "^0.14.0",
+    "phpstan/phpstan": "^0.11.12",
+    "phpstan/phpstan-phpunit": "^0.11.2",
+    "phpstan/phpstan-strict-rules": "^0.11.1",
+    "phpunit/phpcov": "^5.0",
+    "phpunit/phpunit": "^7.2",
+    "psr/http-message": "^1.0",
+    "react/promise": "2.*"
   },
   "config": {
-    "bin-dir": "bin"
+    "preferred-install": "dist",
+    "sort-packages": true
   },
   "autoload": {
     "psr-4": {
@@ -24,7 +35,22 @@
   },
   "autoload-dev": {
     "psr-4": {
-      "GraphQL\\Tests\\": "tests/"
+      "GraphQL\\Tests\\": "tests/",
+      "GraphQL\\Benchmarks\\": "benchmarks/",
+      "GraphQL\\Examples\\Blog\\": "examples/01-blog/Blog/"
     }
+  },
+  "suggest": {
+    "react/promise": "To leverage async resolving on React PHP platform",
+    "psr/http-message": "To use standard GraphQL server"
+  },
+  "scripts": {
+    "api-docs": "php tools/gendocs.php",
+    "bench": "phpbench run .",
+    "test": "phpunit",
+    "lint" : "phpcs",
+    "fix-style" : "phpcbf",
+    "static-analysis": "phpstan analyse --ansi --memory-limit 256M",
+    "check-all": "composer lint && composer static-analysis && composer test"
   }
 }

docs/best-practices.md

@@ -0,0 +1,19 @@
+# Config Validation
+Defining types using arrays may be error-prone, but **graphql-php** provides config validation
+tool to report when config has unexpected structure. 
+
+This validation tool is **disabled by default** because it is time-consuming operation which only 
+makes sense during development.
+
+To enable validation - call: `GraphQL\Type\Definition\Config::enableValidation();` in your bootstrap
+but make sure to restrict it to debug/development mode only.
+
+# Type Registry
+**graphql-php** expects that each type in Schema is presented by single instance. Therefore
+if you define your types as separate PHP classes you need to ensure that each type is referenced only once.
+ 
+Technically you can create several instances of your type (for example for tests), but `GraphQL\Type\Schema` 
+will throw on attempt to add different instances with the same name.
+
+There are several ways to achieve this depending on your preferences. We provide reference 
+implementation below that introduces TypeRegistry class:

docs/complementary-tools.md

@@ -0,0 +1,26 @@
+# Integrations
+
+* [Standard Server](executing-queries.md/#using-server) – Out of the box integration with any PSR-7 compatible framework (like [Slim](http://slimframework.com) or [Zend Expressive](http://zendframework.github.io/zend-expressive/)).
+* [Relay Library for graphql-php](https://github.com/ivome/graphql-relay-php) – Helps construct Relay related schema definitions.
+* [Lighthouse](https://github.com/nuwave/lighthouse) – Laravel based, uses Schema Definition Language
+* [Laravel GraphQL](https://github.com/rebing/graphql-laravel) - Laravel wrapper for Facebook's GraphQL
+* [OverblogGraphQLBundle](https://github.com/overblog/GraphQLBundle) – Bundle for Symfony
+* [WP-GraphQL](https://github.com/wp-graphql/wp-graphql) - GraphQL API for WordPress
+
+# GraphQL PHP Tools
+
+* [GraphQLite](https://graphqlite.thecodingmachine.io) – Define your complete schema with annotations
+* [GraphQL Doctrine](https://github.com/Ecodev/graphql-doctrine) – Define types with Doctrine ORM annotations
+* [DataLoaderPHP](https://github.com/overblog/dataloader-php) – as a ready implementation for [deferred resolvers](data-fetching.md#solving-n1-problem)
+* [GraphQL Uploads](https://github.com/Ecodev/graphql-upload) – A PSR-15 middleware to support file uploads in GraphQL.
+* [GraphQL Batch Processor](https://github.com/vasily-kartashov/graphql-batch-processing) – Provides a builder interface for defining collection, querying, filtering, and post-processing logic of batched data fetches. 
+* [GraphQL Utils](https://github.com/simPod/GraphQL-Utils) – Objective schema definition builders (no need for arrays anymore) and `DateTime` scalar
+* [PSR 15 compliant middleware](https://github.com/phps-cans/psr7-middleware-graphql) for the Standard Server _(experimental)_
+
+# General GraphQL Tools
+
+* [GraphQL Playground](https://github.com/prismagraphql/graphql-playground) – GraphQL IDE for better development workflows (GraphQL Subscriptions, interactive docs & collaboration).
+* [GraphiQL](https://github.com/graphql/graphiql) – An in-browser IDE for exploring GraphQL
+* [ChromeiQL](https://chrome.google.com/webstore/detail/chromeiql/fkkiamalmpiidkljmicmjfbieiclmeij)
+  or [GraphiQL Feen](https://chrome.google.com/webstore/detail/graphiql-feen/mcbfdonlkfpbfdpimkjilhdneikhfklp) –
+  GraphiQL as Google Chrome extension

docs/concepts.md

@@ -0,0 +1,139 @@
+# Overview
+GraphQL is data-centric. On the very top level it is built around three major concepts: 
+**Schema**, **Query** and **Mutation**.
+ 
+You are expected to express your application as **Schema** (aka Type System) and expose it
+with single HTTP endpoint (e.g. using our [standard server](executing-queries.md#using-server)). 
+Application clients (e.g. web or mobile clients) send **Queries** 
+to this endpoint to request structured data and **Mutations** to perform changes (usually with HTTP POST method).
+ 
+## Queries
+Queries are expressed in simple language that resembles JSON:
+ 
+```graphql
+{
+  hero {
+    name
+    friends {
+      name
+    }
+  }
+}
+```
+ 
+It was designed to mirror the structure of expected response:
+```json
+{
+  "hero": {
+    "name": "R2-D2",
+    "friends": [
+      {"name": "Luke Skywalker"},
+      {"name": "Han Solo"},
+      {"name": "Leia Organa"}
+    ]
+  }
+}
+```
+**graphql-php** runtime parses Queries, makes sure that they are valid for given Type System 
+and executes using [data fetching tools](data-fetching.md) provided by you 
+as a part of integration. Queries are supposed to be idempotent.
+
+## Mutations
+Mutations use advanced features of the very same query language (like arguments and variables)  
+and have only semantic difference from Queries:
+
+```graphql
+mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
+  createReview(episode: $ep, review: $review) {
+    stars
+    commentary
+  }
+}
+```
+Variables `$ep` and `$review` are sent alongside with mutation. Full HTTP request might look like this:
+```json
+// POST /graphql-endpoint
+// Content-Type: application/javascript
+// 
+{
+  "query": "mutation CreateReviewForEpisode...",
+  "variables": {
+    "ep": "JEDI",
+    "review": {
+      "stars": 5,
+      "commentary": "This is a great movie!"
+    }
+  }
+}
+```
+As you see variables may include complex objects and they will be correctly validated by 
+**graphql-php** runtime.
+
+Another nice feature of GraphQL mutations is that they also hold the query for data to be 
+returned after mutation. In our example mutation will return:
+```
+{
+  "createReview": {
+    "stars": 5,
+    "commentary": "This is a great movie!"
+  }
+}
+```
+
+# Type System
+Conceptually GraphQL type is a collection of fields. Each field in turn
+has it's own type which allows to build complex hierarchies.
+
+Quick example on pseudo-language:
+```
+type BlogPost {
+    title: String!
+    author: User
+    body: String
+}
+
+type User {
+    id: Id!
+    firstName: String
+    lastName: String
+}
+```
+
+Type system is a heart of GraphQL integration. That's where **graphql-php** comes into play.
+ 
+It provides following tools and primitives to describe your App as hierarchy of types:
+
+ * Primitives for defining **objects** and **interfaces**
+ * Primitives for defining **enumerations** and **unions**
+ * Primitives for defining custom **scalar types**
+ * Built-in scalar types: `ID`, `String`, `Int`, `Float`, `Boolean`
+ * Built-in type modifiers: `ListOf` and `NonNull`
+
+Same example expressed in **graphql-php**:
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$userType = new ObjectType([
+    'name' => 'User',
+    'fields' => [
+        'id' => Type::nonNull(Type::id()),
+        'firstName' => Type::string(),
+        'lastName' => Type::string()
+    ]
+]);
+
+$blogPostType = new ObjectType([
+    'name' => 'BlogPost',
+    'fields' => [
+        'title' => Type::nonNull(Type::string()),
+        'author' => $userType
+    ]
+]);
+```
+
+# Further Reading
+To get deeper understanding of GraphQL concepts - [read the docs on official GraphQL website](http://graphql.org/learn/)
+
+To get started with **graphql-php** - continue to next section ["Getting Started"](getting-started.md)

docs/data-fetching.md

@@ -0,0 +1,274 @@
+# Overview
+GraphQL is data-storage agnostic. You can use any underlying data storage engine, including SQL or NoSQL database, 
+plain files or in-memory data structures.
+
+In order to convert the GraphQL query to PHP array, **graphql-php** traverses query fields (using depth-first algorithm) and 
+runs special **resolve** function on each field. This **resolve** function is provided by you as a part of 
+[field definition](type-system/object-types.md#field-configuration-options) or [query execution call](executing-queries.md#overview).
+
+Result returned by **resolve** function is directly included in the response (for scalars and enums)
+or passed down to nested fields (for objects).
+
+Let's walk through an example. Consider following GraphQL query:
+
+```graphql
+{
+  lastStory {
+    title
+    author {
+      name
+    }
+  }
+}
+```
+
+We need a Schema that can fulfill it. On the very top level the Schema contains Query type:
+
+```php
+<?php
+use GraphQL\Type\Definition\ObjectType;
+
+$queryType = new ObjectType([
+  'name' => 'Query',
+  'fields' => [
+  
+    'lastStory' => [
+      'type' => $blogStoryType,
+      'resolve' => function() {
+        return [
+          'id' => 1,
+          'title' => 'Example blog post',
+          'authorId' => 1
+        ];
+      }
+    ]
+    
+  ]
+]);
+```
+
+As we see field **lastStory** has **resolve** function that is responsible for fetching data.
+
+In our example, we simply return array value, but in the real-world application you would query
+your database/cache/search index and return the result.
+
+Since **lastStory** is of composite type **BlogStory** this result is passed down to fields of this type:
+
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$blogStoryType = new ObjectType([
+  'name' => 'BlogStory',
+  'fields' => [
+
+    'author' => [
+      'type' => $userType,
+      'resolve' => function($blogStory) {
+        $users = [
+          1 => [
+            'id' => 1,
+            'name' => 'Smith'
+          ],
+          2 => [
+            'id' => 2,
+            'name' => 'Anderson'
+          ]
+        ];
+        return $users[$blogStory['authorId']];
+      }
+    ],
+    
+    'title' => [
+      'type' => Type::string()
+    ]
+
+  ]
+]);
+```
+
+Here **$blogStory** is the array returned by **lastStory** field above. 
+
+Again: in the real-world applications you would fetch user data from data store by **authorId** and return it.
+Also, note that you don't have to return arrays. You can return any value, **graphql-php** will pass it untouched
+to nested resolvers.
+
+But then the question appears - field **title** has no **resolve** option. How is it resolved?
+
+There is a default resolver for all fields. When you define your own **resolve** function
+for a field you simply override this default resolver.
+
+# Default Field Resolver
+**graphql-php** provides following default field resolver:
+```php
+<?php
+function defaultFieldResolver($objectValue, $args, $context, \GraphQL\Type\Definition\ResolveInfo $info)
+    {
+        $fieldName = $info->fieldName;
+        $property  = null;
+
+        if (is_array($objectValue) || $objectValue instanceof \ArrayAccess) {
+            if (isset($objectValue[$fieldName])) {
+                $property = $objectValue[$fieldName];
+            }
+        } elseif (is_object($objectValue)) {
+            if (isset($objectValue->{$fieldName})) {
+                $property = $objectValue->{$fieldName};
+            }
+        }
+
+        return $property instanceof Closure
+            ? $property($objectValue, $args, $context, $info)
+            : $property;
+    }
+```
+
+As you see it returns value by key (for arrays) or property (for objects). 
+If the value is not set - it returns **null**.
+
+To override the default resolver, pass it as an argument of [executeQuery](executing-queries.md) call.
+
+# Default Field Resolver per Type
+Sometimes it might be convenient to set default field resolver per type. You can do so by providing
+[resolveField option in type config](type-system/object-types.md#configuration-options). For example:
+
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\ResolveInfo;
+
+$userType = new ObjectType([
+  'name' => 'User',
+  'fields' => [
+
+    'name' => Type::string(),
+    'email' => Type::string()
+
+  ],
+  'resolveField' => function(User $user, $args, $context, ResolveInfo $info) {
+    switch ($info->fieldName) {
+        case 'name':
+          return $user->getName();
+        case 'email':
+          return $user->getEmail();
+        default:
+          return null;
+    }
+  }
+]);
+```
+
+Keep in mind that **field resolver** has precedence over **default field resolver per type** which in turn
+ has precedence over **default field resolver**.
+
+# Solving N+1 Problem
+Since: 0.9.0
+
+One of the most annoying problems with data fetching is a so-called 
+[N+1 problem](https://secure.phabricator.com/book/phabcontrib/article/n_plus_one/). <br>
+Consider following GraphQL query:
+```
+{
+  topStories(limit: 10) {
+    title
+    author {
+      name
+      email
+    }
+  }
+}
+```
+
+Naive field resolution process would require up to 10 calls to the underlying data store to fetch authors for all 10 stories.
+
+**graphql-php** provides tools to mitigate this problem: it allows you to defer actual field resolution to a later stage 
+when one batched query could be executed instead of 10 distinct queries.
+
+Here is an example of **BlogStory** resolver for field **author** that uses deferring:
+```php
+<?php
+'resolve' => function($blogStory) {
+    MyUserBuffer::add($blogStory['authorId']);
+
+    return new GraphQL\Deferred(function () use ($blogStory) {
+        MyUserBuffer::loadBuffered();
+        return MyUserBuffer::get($blogStory['authorId']);
+    });
+}
+```
+
+In this example, we fill up the buffer with 10 author ids first. Then **graphql-php** continues 
+resolving other non-deferred fields until there are none of them left.
+
+After that, it calls closures wrapped by `GraphQL\Deferred` which in turn load all buffered 
+ids once (using SQL IN(?), Redis MGET or other similar tools) and returns final field value.
+
+Originally this approach was advocated by Facebook in their [Dataloader](https://github.com/facebook/dataloader)
+project. This solution enables very interesting optimizations at no cost. Consider the following query:
+
+```graphql
+{
+  topStories(limit: 10) {
+    author {
+      email
+    }
+  }
+  category {
+    stories(limit: 10) {
+      author {
+        email
+      }
+    }
+  }
+}
+```
+
+Even though **author** field is located on different levels of the query - it can be buffered in the same buffer.
+In this example, only one query will be executed for all story authors comparing to 20 queries
+in a naive implementation.
+
+# Async PHP
+Since: 0.10.0 (version 0.9.0 had slightly different API which still works, but is deprecated)
+
+If your project runs in an environment that supports async operations 
+(like HHVM, ReactPHP, Icicle.io, appserver.io, PHP threads, etc) 
+you can leverage the power of your platform to resolve some fields asynchronously.
+
+The only requirement: your platform must support the concept of Promises compatible with
+[Promises A+](https://promisesaplus.com/) specification.
+
+To start using this feature, switch facade method for query execution from 
+**executeQuery** to **promiseToExecute**:
+
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Executor\ExecutionResult;
+
+$promise = GraphQL::promiseToExecute(
+    $promiseAdapter,
+    $schema, 
+    $queryString, 
+    $rootValue = null, 
+    $contextValue = null, 
+    $variableValues = null, 
+    $operationName = null,
+    $fieldResolver = null,
+    $validationRules = null
+);
+$promise->then(function(ExecutionResult $result) {
+    return $result->toArray();
+});
+```
+
+Where **$promiseAdapter** is an instance of:
+
+* For [ReactPHP](https://github.com/reactphp/react) (requires **react/promise** as composer dependency): <br> 
+  `GraphQL\Executor\Promise\Adapter\ReactPromiseAdapter`
+
+* Other platforms: write your own class implementing interface: <br> 
+  [`GraphQL\Executor\Promise\PromiseAdapter`](reference.md#graphqlexecutorpromisepromiseadapter). 
+
+Then your **resolve** functions should return promises of your platform instead of `GraphQL\Deferred`s.

docs/error-handling.md

@@ -0,0 +1,193 @@
+# Errors in GraphQL
+
+Query execution process never throws exceptions. Instead, all errors are caught and collected. 
+After execution, they are available in **$errors** prop of 
+[`GraphQL\Executor\ExecutionResult`](reference.md#graphqlexecutorexecutionresult).
+
+When the result is converted to a serializable array using its **toArray()** method, all errors are 
+converted to arrays as well using default error formatting (see below). 
+
+Alternatively, you can apply [custom error filtering and formatting](#custom-error-handling-and-formatting)
+for your specific requirements.
+
+# Default Error formatting
+By default, each error entry is converted to an associative array with following structure:
+
+```php
+<?php
+[
+    'message' => 'Error message',
+    'category' => 'graphql',
+    'locations' => [
+        ['line' => 1, 'column' => 2]
+    ],
+    'path' => [
+        'listField',
+        0,
+        'fieldWithException'
+    ]
+];
+```
+Entry at key **locations** points to a character in query string which caused the error.
+In some cases (like deep fragment fields) locations will include several entries to track down 
+the path to field with the error in query.
+
+Entry at key **path** exists only for errors caused by exceptions thrown in resolvers. 
+It contains a path from the very root field to actual field value producing an error 
+(including indexes for list types and field names for composite types). 
+
+**Internal errors**
+
+As of version **0.10.0**, all exceptions thrown in resolvers are reported with generic message **"Internal server error"**.
+This is done to avoid information leak in production environments (e.g. database connection errors, file access errors, etc).
+
+Only exceptions implementing interface [`GraphQL\Error\ClientAware`](reference.md#graphqlerrorclientaware) and claiming themselves as **safe** will 
+be reported with a full error message.
+
+For example:
+```php
+<?php
+use GraphQL\Error\ClientAware;
+
+class MySafeException extends \Exception implements ClientAware
+{
+    public function isClientSafe()
+    {
+        return true;
+    }
+    
+    public function getCategory()
+    {
+        return 'businessLogic';
+    }
+}
+```
+When such exception is thrown it will be reported with a full error message:
+```php
+<?php
+[
+    'message' => 'My reported error',
+    'category' => 'businessLogic',
+    'locations' => [
+        ['line' => 10, 'column' => 2]
+    ],
+    'path' => [
+        'path',
+        'to',
+        'fieldWithException'
+    ]
+];
+```
+
+To change default **"Internal server error"** message to something else, use: 
+```
+GraphQL\Error\FormattedError::setInternalErrorMessage("Unexpected error");
+```
+
+# Debugging tools
+
+During development or debugging use `$result->toArray(true)` to add **debugMessage** key to 
+each formatted error entry. If you also want to add exception trace - pass flags instead:
+
+```
+use GraphQL\Error\Debug;
+$debug = Debug::INCLUDE_DEBUG_MESSAGE | Debug::INCLUDE_TRACE;
+$result = GraphQL::executeQuery(/*args*/)->toArray($debug);
+```
+
+This will make each error entry to look like this:
+```php
+<?php
+[
+    'debugMessage' => 'Actual exception message',
+    'message' => 'Internal server error',
+    'category' => 'internal',
+    'locations' => [
+        ['line' => 10, 'column' => 2]
+    ],
+    'path' => [
+        'listField',
+        0,
+        'fieldWithException'
+    ],
+    'trace' => [
+        /* Formatted original exception trace */
+    ]
+];
+```
+
+If you prefer the first resolver exception to be re-thrown, use following flags:
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Error\Debug;
+$debug = Debug::INCLUDE_DEBUG_MESSAGE | Debug::RETHROW_INTERNAL_EXCEPTIONS;
+
+// Following will throw if there was an exception in resolver during execution:
+$result = GraphQL::executeQuery(/*args*/)->toArray($debug); 
+```
+
+If you only want to re-throw Exceptions that are not marked as safe through the `ClientAware` interface, use
+the flag `Debug::RETHROW_UNSAFE_EXCEPTIONS`.
+
+# Custom Error Handling and Formatting
+It is possible to define custom **formatter** and **handler** for result errors.
+
+**Formatter** is responsible for converting instances of [`GraphQL\Error\Error`](reference.md#graphqlerrorerror) 
+to an array. **Handler** is useful for error filtering and logging. 
+
+For example, these are default formatter and handler:
+
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Error\Error;
+use GraphQL\Error\FormattedError;
+
+$myErrorFormatter = function(Error $error) {
+    return FormattedError::createFromException($error);
+};
+
+$myErrorHandler = function(array $errors, callable $formatter) {
+    return array_map($formatter, $errors);
+};
+
+$result = GraphQL::executeQuery(/* $args */)
+    ->setErrorFormatter($myErrorFormatter)
+    ->setErrorsHandler($myErrorHandler)
+    ->toArray(); 
+```
+
+Note that when you pass [debug flags](#debugging-tools) to **toArray()** your custom formatter will still be 
+decorated with same debugging information mentioned above.
+
+# Schema Errors
+So far we only covered errors which occur during query execution process. But schema definition can 
+also throw `GraphQL\Error\InvariantViolation` if there is an error in one of type definitions.
+
+Usually such errors mean that there is some logical error in your schema and it is the only case 
+when it makes sense to return `500` error code for GraphQL endpoint:
+
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Type\Schema;
+use GraphQL\Error\FormattedError;
+
+try {
+    $schema = new Schema([
+        // ...
+    ]);
+    
+    $body = GraphQL::executeQuery($schema, $query);
+    $status = 200;
+} catch(\Exception $e) {
+    $body = [
+        'errors' => [FormattedError::createFromException($e)]
+    ];
+    $status = 500;
+}
+
+header('Content-Type: application/json', true, $status);
+echo json_encode($body);
+```

docs/executing-queries.md

@@ -0,0 +1,208 @@
+# Using Facade Method
+Query execution is a complex process involving multiple steps, including query **parsing**, 
+**validating** and finally **executing** against your [schema](type-system/schema.md).
+
+**graphql-php** provides a convenient facade for this process in class 
+[`GraphQL\GraphQL`](reference.md#graphqlgraphql):
+
+```php
+<?php
+use GraphQL\GraphQL;
+
+$result = GraphQL::executeQuery(
+    $schema, 
+    $queryString, 
+    $rootValue = null, 
+    $context = null, 
+    $variableValues = null, 
+    $operationName = null,
+    $fieldResolver = null,
+    $validationRules = null
+);
+```
+
+It returns an instance of [`GraphQL\Executor\ExecutionResult`](reference.md#graphqlexecutorexecutionresult) 
+which can be easily converted to array:
+
+```php
+$serializableResult = $result->toArray();
+```
+
+Returned array contains **data** and **errors** keys, as described by the 
+[GraphQL spec](http://facebook.github.io/graphql/#sec-Response-Format). 
+This array is suitable for further serialization (e.g. using **json_encode**).
+See also the section on [error handling and formatting](error-handling.md).
+
+Description of **executeQuery** method arguments:
+
+Argument     | Type     | Notes
+------------ | -------- | -----
+schema       | [`GraphQL\Type\Schema`](#) | **Required.** Instance of your application [Schema](type-system/schema.md)
+queryString  | `string` or `GraphQL\Language\AST\DocumentNode` | **Required.** Actual GraphQL query string to be parsed, validated and executed. If you parse query elsewhere before executing - pass corresponding AST document here to avoid new parsing.
+rootValue  | `mixed` | Any value that represents a root of your data graph. It is passed as the 1st argument to field resolvers of [Query type](type-system/schema.md#query-and-mutation-types). Can be omitted or set to null if actual root values are fetched by Query type itself.
+context  | `mixed` | Any value that holds information shared between all field resolvers. Most often they use it to pass currently logged in user, locale details, etc.<br><br>It will be available as the 3rd argument in all field resolvers. (see section on [Field Definitions](type-system/object-types.md#field-configuration-options) for reference) **graphql-php** never modifies this value and passes it *as is* to all underlying resolvers.
+variableValues | `array` | Map of variable values passed along with query string. See section on [query variables on official GraphQL website](http://graphql.org/learn/queries/#variables)
+operationName | `string` | Allows the caller to specify which operation in queryString will be run, in cases where queryString contains multiple top-level operations.
+fieldResolver | `callable` | A resolver function to use when one is not provided by the schema. If not provided, the [default field resolver is used](data-fetching.md#default-field-resolver).
+validationRules | `array` | A set of rules for query validation step. The default value is all available rules. Empty array would allow skipping query validation (may be convenient for persisted queries which are validated before persisting and assumed valid during execution)
+
+# Using Server
+If you are building HTTP GraphQL API, you may prefer our Standard Server 
+(compatible with [express-graphql](https://github.com/graphql/express-graphql)). 
+It supports more features out of the box, including parsing HTTP requests, producing a spec-compliant response; [batched queries](#query-batching); persisted queries.
+
+Usage example (with plain PHP):
+
+```php
+<?php
+use GraphQL\Server\StandardServer;
+
+$server = new StandardServer([/* server options, see below */]);
+$server->handleRequest(); // parses PHP globals and emits response
+```
+
+Server also supports [PSR-7 request/response interfaces](http://www.php-fig.org/psr/psr-7/):
+```php
+<?php
+use GraphQL\Server\StandardServer;
+use GraphQL\Executor\ExecutionResult;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\StreamInterface;
+
+/** @var ServerRequestInterface $psrRequest */
+/** @var ResponseInterface $psrResponse */
+/** @var StreamInterface $psrBodyStream */
+$server = new StandardServer([/* server options, see below */]);
+$psrResponse = $server->processPsrRequest($psrRequest, $psrResponse, $psrBodyStream);
+
+
+// Alternatively create PSR-7 response yourself:
+
+/** @var ExecutionResult|ExecutionResult[] $result */
+$result = $server->executePsrRequest($psrRequest);
+$psrResponse = new SomePsr7ResponseImplementation(json_encode($result));
+```
+
+PSR-7 is useful when you want to integrate the server into existing framework:
+
+- [PSR-7 for Laravel](https://laravel.com/docs/5.1/requests#psr7-requests)
+- [Symfony PSR-7 Bridge](https://symfony.com/doc/current/components/psr7.html)
+- [Slim](https://www.slimframework.com/docs/concepts/value-objects.html)
+- [Zend Expressive](http://zendframework.github.io/zend-expressive/)
+
+## Server configuration options
+
+Argument     | Type     | Notes
+------------ | -------- | -----
+schema       | [`Schema`](reference.md#graphqltypeschema) | **Required.** Instance of your application [Schema](type-system/schema/)
+rootValue  | `mixed` | Any value that represents a root of your data graph. It is passed as the 1st argument to field resolvers of [Query type](type-system/schema.md#query-and-mutation-types). Can be omitted or set to null if actual root values are fetched by Query type itself.
+context  | `mixed` | Any value that holds information shared between all field resolvers. Most often they use it to pass currently logged in user, locale details, etc.<br><br>It will be available as the 3rd argument in all field resolvers. (see section on [Field Definitions](type-system/object-types.md#field-configuration-options) for reference) **graphql-php** never modifies this value and passes it *as is* to all underlying resolvers.
+fieldResolver | `callable` | A resolver function to use when one is not provided by the schema. If not provided, the [default field resolver is used](data-fetching.md#default-field-resolver).
+validationRules | `array` or `callable` | A set of rules for query validation step. The default value is all available rules. The empty array would allow skipping query validation (may be convenient for persisted queries which are validated before persisting and assumed valid during execution).<br><br>Pass `callable` to return different validation rules for different queries (e.g. empty array for persisted query and a full list of rules for regular queries). When passed, it is expected to have the following signature: <br><br> **function ([OperationParams](reference.md#graphqlserveroperationparams) $params, DocumentNode $node, $operationType): array**
+queryBatching | `bool` | Flag indicating whether this server supports query batching ([apollo-style](https://dev-blog.apollodata.com/query-batching-in-apollo-63acfd859862)).<br><br> Defaults to **false**
+debug | `int` | Debug flags. See [docs on error debugging](error-handling.md#debugging-tools) (flag values are the same).
+persistentQueryLoader | `callable` | A function which is called to fetch actual query when server encounters **queryId** in request vs **query**.<br><br> The server does not implement persistence part (which you will have to build on your own), but it allows you to execute queries which were persisted previously.<br><br> Expected function signature:<br> **function ($queryId, [OperationParams](reference.md#graphqlserveroperationparams) $params)** <br><br>Function is expected to return query **string** or parsed **DocumentNode** <br><br> [Read more about persisted queries](https://dev-blog.apollodata.com/persisted-graphql-queries-with-apollo-client-119fd7e6bba5).
+errorFormatter | `callable` | Custom error formatter. See [error handling docs](error-handling.md#custom-error-handling-and-formatting).
+errorsHandler | `callable` | Custom errors handler. See [error handling docs](error-handling.md#custom-error-handling-and-formatting).
+promiseAdapter | [`PromiseAdapter`](reference.md#graphqlexecutorpromisepromiseadapter) | Required for [Async PHP](data-fetching/#async-php) only. 
+
+**Server config instance**
+
+If you prefer fluid interface for config with autocomplete in IDE and static time validation, 
+use [`GraphQL\Server\ServerConfig`](reference.md#graphqlserverserverconfig) instead of an array:
+
+```php
+<?php
+use GraphQL\Server\ServerConfig;
+use GraphQL\Server\StandardServer;
+
+$config = ServerConfig::create()
+    ->setSchema($schema)
+    ->setErrorFormatter($myFormatter)
+    ->setDebug($debug)
+;
+
+$server = new StandardServer($config);
+```
+
+## Query batching
+Standard Server supports query batching ([apollo-style](https://dev-blog.apollodata.com/query-batching-in-apollo-63acfd859862)).
+
+One of the major benefits of Server over a sequence of **executeQuery()** calls is that 
+[Deferred resolvers](data-fetching.md#solving-n1-problem) won't be isolated in queries.
+So for example following batch will require single DB request (if user field is deferred):
+
+```json
+[
+  {
+    "query": "{user(id: 1) { id }}"
+  },
+  {
+    "query": "{user(id: 2) { id }}"
+  },
+  {
+    "query": "{user(id: 3) { id }}"
+  }
+]
+```
+
+To enable query batching, pass **queryBatching** option in server config:
+```php
+<?php
+use GraphQL\Server\StandardServer;
+
+$server = new StandardServer([
+    'queryBatching' => true
+]);
+```
+
+# Custom Validation Rules
+Before execution, a query is validated using a set of standard rules defined by the GraphQL spec.
+It is possible to override standard set of rules globally or per execution.
+
+Add rules globally:
+```php
+<?php
+use GraphQL\Validator\Rules;
+use GraphQL\Validator\DocumentValidator;
+
+// Add to standard set of rules globally:
+DocumentValidator::addRule(new Rules\DisableIntrospection());
+```
+
+Custom rules per execution:
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Validator\Rules;
+
+$myValiationRules = array_merge(
+    GraphQL::getStandardValidationRules(),
+    [
+        new Rules\QueryComplexity(100),
+        new Rules\DisableIntrospection()
+    ]
+);
+
+$result = GraphQL::executeQuery(
+    $schema, 
+    $queryString, 
+    $rootValue = null, 
+    $context = null, 
+    $variableValues = null, 
+    $operationName = null,
+    $fieldResolver = null,
+    $myValiationRules // <-- this will override global validation rules for this request
+);
+```
+
+Or with a standard server:
+```php
+<?php 
+use GraphQL\Server\StandardServer;
+
+$server = new StandardServer([
+    'validationRules' => $myValiationRules
+]);
+```

docs/getting-started.md

@@ -0,0 +1,125 @@
+# Prerequisites
+This documentation assumes your familiarity with GraphQL concepts. If it is not the case - 
+first learn about GraphQL on [the official website](http://graphql.org/learn/).
+
+# Installation
+
+Using [composer](https://getcomposer.org/doc/00-intro.md), run:
+
+```sh
+composer require webonyx/graphql-php
+```
+
+# Upgrading
+We try to keep library releases backwards compatible. But when breaking changes are inevitable 
+they are explained in [upgrade instructions](https://github.com/webonyx/graphql-php/blob/master/UPGRADE.md).
+
+# Install Tools (optional)
+While it is possible to communicate with GraphQL API using regular HTTP tools it is way 
+more convenient for humans to use [GraphiQL](https://github.com/graphql/graphiql) - an in-browser 
+IDE for exploring GraphQL APIs.
+
+It provides syntax-highlighting, auto-completion and auto-generated documentation for 
+GraphQL API.
+
+The easiest way to use it is to install one of the existing Google Chrome extensions:
+
+ - [ChromeiQL](https://chrome.google.com/webstore/detail/chromeiql/fkkiamalmpiidkljmicmjfbieiclmeij)
+ - [GraphiQL Feen](https://chrome.google.com/webstore/detail/graphiql-feen/mcbfdonlkfpbfdpimkjilhdneikhfklp)
+
+Alternatively, you can follow instructions on [the GraphiQL](https://github.com/graphql/graphiql)
+page and install it locally.
+
+
+# Hello World
+Let's create a type system that will be capable to process following simple query:
+```
+query {
+  echo(message: "Hello World")
+}
+```
+
+To do so we need an object type with field `echo`:
+
+```php
+<?php
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+
+$queryType = new ObjectType([
+    'name' => 'Query',
+    'fields' => [
+        'echo' => [
+            'type' => Type::string(),
+            'args' => [
+                'message' => Type::nonNull(Type::string()),
+            ],
+            'resolve' => function ($rootValue, $args) {
+                return $rootValue['prefix'] . $args['message'];
+            }
+        ],
+    ],
+]);
+
+```
+
+(Note: type definition can be expressed in [different styles](type-system/index.md#type-definition-styles), 
+but this example uses **inline** style for simplicity)
+
+The interesting piece here is **resolve** option of field definition. It is responsible for returning 
+a value of our field. Values of **scalar** fields will be directly included in response while values of 
+**composite** fields (objects, interfaces, unions) will be passed down to nested field resolvers 
+(not in this example though).
+
+Now when our type is ready, let's create GraphQL endpoint file for it **graphql.php**:
+
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Type\Schema;
+
+$schema = new Schema([
+    'query' => $queryType
+]);
+
+$rawInput = file_get_contents('php://input');
+$input = json_decode($rawInput, true);
+$query = $input['query'];
+$variableValues = isset($input['variables']) ? $input['variables'] : null;
+
+try {
+    $rootValue = ['prefix' => 'You said: '];
+    $result = GraphQL::executeQuery($schema, $query, $rootValue, null, $variableValues);
+    $output = $result->toArray();
+} catch (\Exception $e) {
+    $output = [
+        'errors' => [
+            [
+                'message' => $e->getMessage()
+            ]
+        ]
+    ];
+}
+header('Content-Type: application/json');
+echo json_encode($output);
+```
+
+Our example is finished. Try it by running:
+```sh
+php -S localhost:8080 graphql.php
+curl http://localhost:8080 -d '{"query": "query { echo(message: \"Hello World\") }" }'
+```
+
+Check out the full [source code](https://github.com/webonyx/graphql-php/blob/master/examples/00-hello-world) of this example
+which also includes simple mutation.
+
+Obviously hello world only scratches the surface of what is possible. 
+So check out next example, which is closer to real-world apps.
+Or keep reading about [schema definition](type-system/index.md).
+
+# Blog example
+It is often easier to start with a full-featured example and then get back to documentation
+for your own work. 
+
+Check out [Blog example of GraphQL API](https://github.com/webonyx/graphql-php/tree/master/examples/01-blog).
+It is quite close to real-world GraphQL hierarchies. Follow instructions and try it yourself in ~10 minutes.

docs/how-it-works.md

@@ -0,0 +1,35 @@
+# Overview
+Following reading describes implementation details of query execution process. It may clarify some 
+internals of GraphQL runtime but is not required to use it.
+
+# Parsing
+
+TODOC
+
+# Validating
+TODOC
+
+# Executing
+TODOC
+
+# Errors explained
+There are 3 types of errors in GraphQL:
+
+- **Syntax**: query has invalid syntax and could not be parsed;
+- **Validation**: query is incompatible with type system (e.g. unknown field is requested);
+- **Execution**: occurs when some field resolver throws (or returns unexpected value).
+
+Obviously, when **Syntax** or **Validation** error is detected - the process is interrupted and 
+the query is not executed.
+
+Execution process never throws exceptions. Instead, all errors are caught and collected in 
+execution result.
+
+GraphQL is forgiving to **Execution** errors which occur in resolvers of nullable fields. 
+If such field throws or returns unexpected value the value of the field in response will be simply 
+replaced with **null** and error entry will be registered.
+
+If an exception is thrown in the non-null field - error bubbles up to the first nullable field. 
+This nullable field is replaced with **null** and error entry is added to the result. 
+If all fields up to the root are non-null - **data** entry will be removed from the result  
+and only **errors** key will be presented.

docs/index.md

@@ -0,0 +1,55 @@
+[![GitHub stars](https://img.shields.io/github/stars/webonyx/graphql-php.svg?style=social&label=Star)](https://github.com/webonyx/graphql-php)
+[![Build Status](https://travis-ci.org/webonyx/graphql-php.svg?branch=master)](https://travis-ci.org/webonyx/graphql-php)
+[![Coverage Status](https://coveralls.io/repos/github/webonyx/graphql-php/badge.svg)](https://coveralls.io/github/webonyx/graphql-php)
+[![Latest Stable Version](https://poser.pugx.org/webonyx/graphql-php/version)](https://packagist.org/packages/webonyx/graphql-php)
+[![License](https://poser.pugx.org/webonyx/graphql-php/license)](https://packagist.org/packages/webonyx/graphql-php)
+
+# About GraphQL
+
+GraphQL is a modern way to build HTTP APIs consumed by the web and mobile clients.
+It is intended to be an alternative to REST and SOAP APIs (even for **existing applications**).
+
+GraphQL itself is a [specification](https://github.com/facebook/graphql) designed by Facebook
+engineers. Various implementations of this specification were written 
+[in different languages and environments](http://graphql.org/code/).
+
+Great overview of GraphQL features and benefits is presented on [the official website](http://graphql.org/). 
+All of them equally apply to this PHP implementation. 
+
+
+# About graphql-php
+
+**graphql-php** is a feature-complete implementation of GraphQL specification in PHP (5.5+, 7.0+). 
+It was originally inspired by [reference JavaScript implementation](https://github.com/graphql/graphql-js) 
+published by Facebook.
+
+This library is a thin wrapper around your existing data layer and business logic. 
+It doesn't dictate how these layers are implemented or which storage engines 
+are used. Instead, it provides tools for creating rich API for your existing app.
+ 
+Library features include:
+
+ - Primitives to express your app as a [Type System](type-system/index.md)
+ - Validation and introspection of this Type System (for compatibility with tools like [GraphiQL](complementary-tools.md#tools))
+ - Parsing, validating and [executing GraphQL queries](executing-queries.md) against this Type System
+ - Rich [error reporting](error-handling.md), including query validation and execution errors
+ - Optional tools for [parsing GraphQL Type language](type-system/type-language.md)
+ - Tools for [batching requests](data-fetching.md#solving-n1-problem) to backend storage
+ - [Async PHP platforms support](data-fetching.md#async-php) via promises
+ - [Standard HTTP server](executing-queries.md#using-server)
+
+Also, several [complementary tools](complementary-tools.md) are available which provide integrations with 
+existing PHP frameworks, add support for Relay, etc.
+
+## Current Status
+The first version of this library (v0.1) was released on August 10th 2015.
+
+The current version supports all features described by GraphQL specification 
+as well as some experimental features like 
+[Schema Language parser](type-system/type-language.md) and 
+[Schema printer](reference.md#graphqlutilsschemaprinter).
+
+Ready for real-world usage. 
+
+## GitHub
+Project source code is [hosted on GitHub](https://github.com/webonyx/graphql-php).

docs/security.md

@@ -0,0 +1,94 @@
+# Query Complexity Analysis
+
+This is a PHP port of [Query Complexity Analysis](http://sangria-graphql.org/learn/#query-complexity-analysis) in Sangria implementation.
+
+Complexity analysis is a separate validation rule which calculates query complexity score before execution.
+Every field in the query gets a default score 1 (including ObjectType nodes). Total complexity of the 
+query is the sum of all field scores. For example, the complexity of introspection query is **109**.
+
+If this score exceeds a threshold, a query is not executed and an error is returned instead.
+
+Complexity analysis is disabled by default. To enabled it, add validation rule:
+
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Validator\Rules\QueryComplexity;
+use GraphQL\Validator\DocumentValidator;
+
+$rule = new QueryComplexity($maxQueryComplexity = 100);
+DocumentValidator::addRule($rule);
+
+GraphQL::executeQuery(/*...*/);
+```
+This will set the rule globally. Alternatively, you can provide validation rules [per execution](executing-queries.md#custom-validation-rules).
+
+To customize field score add **complexity** function to field definition:
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$type = new ObjectType([
+    'name' => 'MyType',
+    'fields' => [
+        'someList' => [
+            'type' => Type::listOf(Type::string()),
+            'args' => [
+                'limit' => [
+                    'type' => Type::int(),
+                    'defaultValue' => 10
+                ]
+            ],
+            'complexity' => function($childrenComplexity, $args) {
+                return $childrenComplexity * $args['limit'];
+            }
+        ]
+    ]
+]);
+```
+
+# Limiting Query Depth
+
+This is a PHP port of [Limiting Query Depth](http://sangria-graphql.org/learn/#limiting-query-depth) in Sangria implementation.
+For example, max depth of the introspection query is **7**.
+
+It is disabled by default. To enable it, add following validation rule:
+
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Validator\Rules\QueryDepth;
+use GraphQL\Validator\DocumentValidator;
+
+$rule = new QueryDepth($maxDepth = 10);
+DocumentValidator::addRule($rule);
+
+GraphQL::executeQuery(/*...*/);
+```
+
+This will set the rule globally. Alternatively, you can provide validation rules [per execution](executing-queries.md#custom-validation-rules).
+
+# Disabling Introspection
+[Introspection](http://graphql.org/learn/introspection/) is a mechanism for fetching schema structure.
+It is used by tools like GraphiQL for auto-completion, query validation, etc.
+
+Introspection is enabled by default. It means that anybody can get a full description of your schema by 
+sending a special query containing meta fields **__type** and **__schema** .
+
+If you are not planning to expose your API to the general public, it makes sense to disable this feature.
+
+GraphQL PHP provides you separate validation rule which prohibits queries that contain 
+**__type** or **__schema** fields. To disable introspection, add following rule:
+
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Validator\Rules\DisableIntrospection;
+use GraphQL\Validator\DocumentValidator;
+
+DocumentValidator::addRule(new DisableIntrospection());
+
+GraphQL::executeQuery(/*...*/);
+```
+This will set the rule globally. Alternatively, you can provide validation rules [per execution](executing-queries.md#custom-validation-rules).

docs/type-system/directives.md

@@ -0,0 +1,61 @@
+# Built-in directives
+The directive is a way for a client to give GraphQL server additional context and hints on how to execute
+the query. The directive can be attached to a field or fragment and can affect the execution of the 
+query in any way the server desires.
+
+GraphQL specification includes two built-in directives:
+ 
+* **@include(if: Boolean)** Only include this field or fragment in the result if the argument is **true** 
+* **@skip(if: Boolean)** Skip this field or fragment if the argument is **true**
+
+For example:
+```graphql
+query Hero($episode: Episode, $withFriends: Boolean!) {
+  hero(episode: $episode) {
+    name
+    friends @include(if: $withFriends) {
+      name
+    }
+  }
+}
+```
+Here if **$withFriends** variable is set to **false** - friends section will be ignored and excluded 
+from the response. Important implementation detail: those fields will never be executed 
+(not just removed from response after execution).
+
+# Custom directives
+**graphql-php** supports custom directives even though their presence does not affect the execution of fields.
+But you can use [`GraphQL\Type\Definition\ResolveInfo`](../reference.md#graphqltypedefinitionresolveinfo) 
+in field resolvers to modify the output depending on those directives or perform statistics collection.
+ 
+Other use case is your own query validation rules relying on custom directives.
+
+In **graphql-php** custom directive is an instance of `GraphQL\Type\Definition\Directive`
+(or one of its subclasses) which accepts an array of following options:
+
+```php
+<?php
+use GraphQL\Language\DirectiveLocation;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\Directive;
+use GraphQL\Type\Definition\FieldArgument;
+
+$trackDirective = new Directive([
+    'name' => 'track',
+    'description' => 'Instruction to record usage of the field by client',
+    'locations' => [
+        DirectiveLocation::FIELD,
+    ],
+    'args' => [
+        new FieldArgument([
+            'name' => 'details',
+            'type' => Type::string(),
+            'description' => 'String with additional details of field usage scenario',
+            'defaultValue' => ''
+        ])
+    ]
+]);
+```
+
+See possible directive locations in 
+[`GraphQL\Language\DirectiveLocation`](../reference.md#graphqllanguagedirectivelocation).

docs/type-system/enum-types.md

@@ -0,0 +1,182 @@
+# Enum Type Definition
+Enumeration types are a special kind of scalar that is restricted to a particular set 
+of allowed values. 
+
+In **graphql-php** enum type is an instance of `GraphQL\Type\Definition\EnumType` 
+which accepts configuration array in constructor:
+
+```php
+<?php
+use GraphQL\Type\Definition\EnumType;
+
+$episodeEnum = new EnumType([
+    'name' => 'Episode',
+    'description' => 'One of the films in the Star Wars Trilogy',
+    'values' => [
+        'NEWHOPE' => [
+            'value' => 4,
+            'description' => 'Released in 1977.'
+        ],
+        'EMPIRE' => [
+            'value' => 5,
+            'description' => 'Released in 1980.'
+        ],
+        'JEDI' => [
+            'value' => 6,
+            'description' => 'Released in 1983.'
+        ],
+    ]
+]);
+```
+
+This example uses an **inline** style for Enum Type definition, but you can also use
+[inheritance or type language](index.md#type-definition-styles).
+
+# Configuration options
+Enum Type constructor accepts an array with following options:
+
+Option | Type | Notes
+------ | ---- | -----
+name | `string` | **Required.** Name of the type. When not set - inferred from array key (read about [shorthand field definition](#shorthand-definitions) below)
+description | `string` | Plain-text description of the type for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+values | `array` | List of enumerated items, see below for expected structure of each entry
+
+Each entry of **values** array in turn accepts following options:
+
+Option | Type | Notes
+------ | ---- | -----
+name | `string` | **Required.** Name of the item. When not set - inferred from array key (read about [shorthand field definition](#shorthand-definitions) below)
+value | `mixed` | Internal representation of enum item in your application (could be any value, including complex objects or callbacks)
+description | `string` | Plain-text description of enum value for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+deprecationReason | `string` | Text describing why this enum value is deprecated. When not empty - item will not be returned by introspection queries (unless forced)
+
+
+# Shorthand definitions
+If internal representation of enumerated item is the same as item name, then you can use
+following shorthand for definition:
+
+```php
+<?php
+use GraphQL\Type\Definition\EnumType;
+
+$episodeEnum = new EnumType([
+    'name' => 'Episode',
+    'description' => 'One of the films in the Star Wars Trilogy',
+    'values' => ['NEWHOPE', 'EMPIRE', 'JEDI']
+]);
+```
+
+which is equivalent of:
+```php
+<?php
+use GraphQL\Type\Definition\EnumType;
+
+$episodeEnum = new EnumType([
+    'name' => 'Episode',
+    'description' => 'One of the films in the Star Wars Trilogy',
+    'values' => [
+        'NEWHOPE' => ['value' => 'NEWHOPE'], 
+        'EMPIRE' => ['value' => 'EMPIRE'], 
+        'JEDI' => ['value' => 'JEDI']
+    ]
+]);
+```
+
+which is in turn equivalent of the full form:
+
+```php
+<?php
+use GraphQL\Type\Definition\EnumType;
+
+$episodeEnum = new EnumType([
+    'name' => 'Episode',
+    'description' => 'One of the films in the Star Wars Trilogy',
+    'values' => [
+        ['name' => 'NEWHOPE', 'value' => 'NEWHOPE'], 
+        ['name' => 'EMPIRE', 'value' => 'EMPIRE'], 
+        ['name' => 'JEDI', 'value' => 'JEDI']
+    ]
+]);
+```
+
+# Field Resolution
+When object field is of Enum Type, field resolver is expected to return an internal 
+representation of corresponding Enum item (**value** in config). **graphql-php** will 
+then serialize this **value** to **name** to include in response:
+
+```php
+<?php
+use GraphQL\Type\Definition\EnumType;
+use GraphQL\Type\Definition\ObjectType;
+
+$episodeEnum = new EnumType([
+    'name' => 'Episode',
+    'description' => 'One of the films in the Star Wars Trilogy',
+    'values' => [
+        'NEWHOPE' => [
+            'value' => 4,
+            'description' => 'Released in 1977.'
+        ],
+        'EMPIRE' => [
+            'value' => 5,
+            'description' => 'Released in 1980.'
+        ],
+        'JEDI' => [
+            'value' => 6,
+            'description' => 'Released in 1983.'
+        ],
+    ]
+]);
+
+$heroType = new ObjectType([
+    'name' => 'Hero',
+    'fields' => [
+        'appearsIn' => [
+            'type' => $episodeEnum,
+            'resolve' => function() {
+                return 5; // Actual entry in response will be 'appearsIn' => 'EMPIRE'
+            }
+        ]
+    ]
+]);
+```
+
+The Reverse is true when the enum is used as input type (e.g. as field argument). 
+GraphQL will treat enum input as **name** and convert it into **value** before passing to your app.
+
+For example, given object type definition:
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$heroType = new ObjectType([
+    'name' => 'Hero',
+    'fields' => [
+        'appearsIn' => [
+            'type' => Type::boolean(),
+            'args' => [
+                'episode' => Type::nonNull($enumType)
+            ],
+            'resolve' => function($hero, $args) {
+                return $args['episode'] === 5 ? true : false; 
+            }
+        ]
+    ]
+]);
+```
+
+Then following query:
+```graphql
+fragment on Hero {
+    appearsInNewHope: appearsIn(NEWHOPE)
+    appearsInEmpire: appearsIn(EMPIRE)
+}
+```
+will return:
+```php
+[
+    'appearsInNewHope' => false,
+    'appearsInEmpire' => true
+]
+```

docs/type-system/index.md

@@ -0,0 +1,127 @@
+# Type System
+To start using GraphQL you are expected to implement a type hierarchy and expose it as [Schema](schema.md). 
+
+In graphql-php **type** is an instance of internal class from 
+`GraphQL\Type\Definition` namespace: [`ObjectType`](object-types.md), 
+[`InterfaceType`](interfaces.md), [`UnionType`](unions.md), [`InputObjectType`](input-types.md), 
+[`ScalarType`](scalar-types.md), [`EnumType`](enum-types.md) (or one of subclasses).
+
+But most of the types in your schema will be [object types](object-types.md).
+
+# Type Definition Styles
+Several styles of type definitions are supported depending on your preferences.
+
+Inline definitions:
+```php
+<?php
+namespace MyApp;
+
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+
+$myType = new ObjectType([
+    'name' => 'MyType',
+    'fields' => [
+        'id' => Type::id()
+    ]
+]);
+```
+
+Class per type:
+```php
+<?php
+namespace MyApp;
+
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+
+class MyType extends ObjectType
+{
+    public function __construct()
+    {
+        $config = [
+            // Note: 'name' is not needed in this form:
+            // it will be inferred from class name by omitting namespace and dropping "Type" suffix
+            'fields' => [
+                'id' => Type::id()
+            ]
+        ];
+        parent::__construct($config);
+    }
+}
+```
+
+Using [GraphQL Type language](http://graphql.org/learn/schema/#type-language):
+
+```graphql
+schema {
+    query: Query
+    mutation: Mutation
+}
+
+type Query {
+    greetings(input: HelloInput!): String!
+}
+
+input HelloInput {
+    firstName: String!
+    lastName: String
+}
+```
+
+Read more about type language definitions in a [dedicated docs section](type-language.md).
+
+# Type Registry
+Every type must be presented in Schema by a single instance (**graphql-php** 
+throws when it discovers several instances with the same **name** in the schema).
+
+Therefore if you define your type as separate PHP class you must ensure that only one 
+instance of that class is added to the schema.
+
+The typical way to do this is to create a registry of your types:
+
+```php
+<?php
+namespace MyApp;
+
+class TypeRegistry
+{
+    private $myAType;
+    private $myBType;
+    
+    public function myAType()
+    {
+        return $this->myAType ?: ($this->myAType = new MyAType($this));
+    }
+    
+    public function myBType()
+    {
+        return $this->myBType ?: ($this->myBType = new MyBType($this));
+    }
+}
+```
+And use this registry in type definition:
+
+```php
+<?php
+namespace MyApp;
+use GraphQL\Type\Definition\ObjectType;
+
+class MyAType extends ObjectType
+{
+    public function __construct(TypeRegistry $types) 
+    {
+        parent::__construct([
+            'fields' => [
+                'b' => $types->myBType()                
+            ]
+        ]);
+    }
+}
+```
+Obviously, you can automate this registry as you wish to reduce boilerplate or even 
+introduce Dependency Injection Container if your types have other dependencies.
+
+Alternatively, all methods of the registry could be static - then there is no need
+to pass it in constructor - instead just use use **TypeRegistry::myAType()** in your 
+type definitions.

docs/type-system/input-types.md

@@ -0,0 +1,172 @@
+# Mutations
+Mutation is just a field of a regular [Object Type](object-types.md) with arguments.
+For GraphQL PHP runtime there is no difference between query fields with arguments and mutations.
+They are executed [almost](http://facebook.github.io/graphql/#sec-Mutation) identically. 
+To some extent, Mutation is just a convention described in the GraphQL spec.
+
+Here is an example of a mutation operation:
+```graphql
+mutation CreateReviewForEpisode($ep: EpisodeInput!, $review: ReviewInput!) {
+  createReview(episode: $ep, review: $review) {
+    stars
+    commentary
+  }
+}
+```
+
+To execute such a mutation, you need **Mutation** type [at the root of your schema](schema.md):
+
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$myMutationType = new ObjectType([
+    'name' => 'Mutation',
+    'fields' => [
+        // List of mutations:
+        'createReview' => [
+            'args' => [
+                'episode' => Type::nonNull($episodeInputType),
+                'review' => Type::nonNull($reviewInputType)
+            ],
+            'type' => new ObjectType([
+                'name' => 'CreateReviewOutput',
+                'fields' => [
+                    'stars' => ['type' => Type::int()],
+                    'commentary' => ['type' => Type::string()]
+                ]
+            ]),
+        ],
+        // ... other mutations
+    ]
+]);
+```
+As you can see, the only difference from regular object type is the semantics of field names
+(verbs vs nouns).
+
+Also as we see arguments can be of complex types. To leverage the full power of mutations 
+(and field arguments in general) you must learn how to create complex input types.
+
+
+# About Input and Output Types
+All types in GraphQL are of two categories: **input** and **output**.
+
+* **Output** types (or field types) are: [Scalar](scalar-types.md), [Enum](enum-types.md), [Object](object-types.md), 
+[Interface](interfaces.md), [Union](unions.md)
+
+* **Input** types (or argument types) are: [Scalar](scalar-types.md), [Enum](enum-types.md), InputObject
+
+Obviously, [NonNull and List](lists-and-nonnulls.md) types belong to both categories depending on their 
+inner type.
+
+Until now all examples of field **arguments** in this documentation were of [Scalar](scalar-types.md) or 
+[Enum](enum-types.md) types. But you can also pass complex objects. 
+
+This is particularly valuable in case of mutations, where input data might be rather complex.
+
+# Input Object Type
+GraphQL specification defines Input Object Type for complex inputs. It is similar to ObjectType
+except that it's fields have no **args** or **resolve** options and their **type** must be input type.
+
+In graphql-php **Input Object Type** is an instance of `GraphQL\Type\Definition\InputObjectType` 
+(or one of it subclasses) which accepts configuration array in constructor:
+
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\InputObjectType;
+
+$filters = new InputObjectType([
+    'name' => 'StoryFiltersInput',
+    'fields' => [
+        'author' => [
+            'type' => Type::id(),
+            'description' => 'Only show stories with this author id'
+        ],
+        'popular' => [
+            'type' => Type::boolean(),
+            'description' => 'Only show popular stories (liked by several people)'
+        ],
+        'tags' => [
+            'type' => Type::listOf(Type::string()),
+            'description' => 'Only show stories which contain all of those tags'
+        ]
+    ]
+]);
+```
+
+Every field may be of other InputObjectType (thus complex hierarchies of inputs are possible)
+
+# Configuration options
+The constructor of InputObjectType accepts array with only 3 options:
+ 
+Option       | Type     | Notes
+------------ | -------- | -----
+name         | `string` | **Required.** Unique name of this object type within Schema
+fields       | `array` or `callable` | **Required**. An array describing object fields or callable returning such an array (see below).
+description  | `string` | Plain-text description of this type for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+
+Every field is an array with following entries:
+
+Option | Type | Notes
+------ | ---- | -----
+name | `string` | **Required.** Name of the input field. When not set - inferred from **fields** array key
+type | `Type` | **Required.** Instance of one of [Input Types](input-types.md) (**Scalar**, **Enum**, **InputObjectType** + any combination of those with **nonNull** and **listOf** modifiers)
+description | `string` | Plain-text description of this input field for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+defaultValue | `scalar` | Default value of this input field. Use the internal value if specifying a default for an **enum** type
+
+# Using Input Object Type
+In the example above we defined our InputObjectType. Now let's use it in one of field arguments:
+
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$queryType = new ObjectType([
+    'name' => 'Query',
+    'fields' => [
+        'stories' => [
+            'type' => Type::listOf($storyType),
+            'args' => [
+                'filters' => [
+                    'type' => $filters,
+                    'defaultValue' => [
+                        'popular' => true
+                    ]
+                ]
+            ],
+            'resolve' => function($rootValue, $args) {
+                return DataSource::filterStories($args['filters']);
+            }
+        ]
+    ]
+]);
+```
+(note that you can define **defaultValue** for fields with complex inputs as associative array).
+
+Then GraphQL query could include filters as literal value:
+```graphql
+{
+    stories(filters: {author: "1", popular: false})
+}
+```
+
+Or as query variable:
+```graphql
+query($filters: StoryFiltersInput!) {
+    stories(filters: $filters)
+}
+```
+```php
+$variables = [
+    'filters' => [
+        "author" => "1",
+        "popular" => false
+    ]
+];
+```
+
+**graphql-php** will validate the input against your InputObjectType definition and pass it to your 
+resolver as `$args['filters']`

docs/type-system/interfaces.md

@@ -0,0 +1,136 @@
+# Interface Type Definition
+An Interface is an abstract type that includes a certain set of fields that a 
+type must include to implement the interface.
+
+In **graphql-php** interface type is an instance of `GraphQL\Type\Definition\InterfaceType` 
+(or one of its subclasses) which accepts configuration array in a constructor:
+
+```php
+<?php
+use GraphQL\Type\Definition\InterfaceType;
+use GraphQL\Type\Definition\Type;
+
+$character = new InterfaceType([
+    'name' => 'Character',
+    'description' => 'A character in the Star Wars Trilogy',
+    'fields' => [
+        'id' => [
+            'type' => Type::nonNull(Type::string()),
+            'description' => 'The id of the character.',
+        ],
+        'name' => [
+            'type' => Type::string(),
+            'description' => 'The name of the character.'
+        ]
+    ],
+    'resolveType' => function ($value) {
+        if ($value->type === 'human') {
+            return MyTypes::human();            
+        } else {
+            return MyTypes::droid();
+        }
+    }
+]);
+```
+This example uses **inline** style for Interface definition, but you can also use  
+[inheritance or type language](index.md#type-definition-styles).
+
+# Configuration options
+The constructor of InterfaceType accepts an array. Below is a full list of allowed options:
+
+Option | Type | Notes
+------ | ---- | -----
+name | `string` | **Required.** Unique name of this interface type within Schema
+fields | `array` | **Required.** List of fields required to be defined by interface implementors. Same as [Fields for Object Type](object-types.md#field-configuration-options)
+description | `string` | Plain-text description of this type for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+resolveType | `callback` | **function($value, $context, [ResolveInfo](../reference.md#graphqltypedefinitionresolveinfo) $info)**<br> Receives **$value** from resolver of the parent field and returns concrete interface implementor for this **$value**.
+
+# Implementing interface
+To implement the Interface simply add it to **interfaces** array of Object Type definition:
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$humanType = new ObjectType([
+    'name' => 'Human',
+    'fields' => [
+        'id' => [
+            'type' => Type::nonNull(Type::string()),
+            'description' => 'The id of the character.',
+        ],
+        'name' => [
+            'type' => Type::string(),
+            'description' => 'The name of the character.'
+        ]
+    ],
+    'interfaces' => [
+        $character
+    ]
+]);
+```
+Note that Object Type must include all fields of interface with exact same types 
+(including **nonNull** specification) and arguments.
+
+The only exception is when object's field type is more specific than the type of this field defined in interface 
+(see [Covariant return types for interface fields](#covariant-return-types-for-interface-fields) below)
+
+# Covariant return types for interface fields
+Object types implementing interface may change the field type to more specific.
+Example:
+
+```
+interface A {
+  field1: A
+}
+
+type B implements A {
+  field1: B
+}
+```
+
+# Sharing Interface fields
+Since every Object Type implementing an Interface must have the same set of fields - it often makes 
+sense to reuse field definitions of Interface in Object Types:
+
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$humanType = new ObjectType([
+    'name' => 'Human',
+    'interfaces' => [
+        $character
+    ],
+    'fields' => [
+        'height' => Type::float(),
+        $character->getField('id'),
+        $character->getField('name')
+    ] 
+]);
+```
+
+In this case, field definitions are created only once (as a part of Interface Type) and then 
+reused by all interface implementors. It can save several microseconds and kilobytes + ensures that 
+field definitions of Interface and implementors are always in sync.
+
+Yet it creates a problem with the resolution of such fields. There are two ways how shared fields could 
+be resolved:
+
+1. If field resolution algorithm is the same for all Interface implementors - you can simply add 
+**resolve** option to field definition in Interface itself.
+
+2. If field resolution varies for different implementations - you can specify **resolveField** 
+option in [Object Type config](object-types.md#configuration-options) and handle field 
+resolutions there 
+(Note: **resolve** option in field definition has precedence over **resolveField** option in object type definition)
+
+# Interface role in data fetching
+The only responsibility of interface in Data Fetching process is to return concrete Object Type 
+for given **$value** in **resolveType**. Then resolution of fields is delegated to resolvers of this 
+concrete Object Type.
+
+If a **resolveType** option is omitted, graphql-php will loop through all interface implementors and 
+use their **isTypeOf** callback to pick the first suitable one. This is obviously less efficient 
+than single **resolveType** call. So it is recommended to define **resolveType** whenever possible.

docs/type-system/lists-and-nonnulls.md

@@ -0,0 +1,62 @@
+# Lists
+**graphql-php** provides built-in support for lists. In order to create list type - wrap 
+existing type with `GraphQL\Type\Definition\Type::listOf()` modifier:
+```php
+<?php
+namespace MyApp;
+
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$userType = new ObjectType([
+    'name' => 'User',
+    'fields' => [
+        'emails' => [
+            'type' => Type::listOf(Type::string()),
+            'resolve' => function() {
+                return ['jon@example.com', 'jonny@example.com'];
+            }
+        ]
+    ]
+]);
+```
+
+Resolvers for such fields are expected to return **array** or instance of PHP's built-in **Traversable** 
+interface (**null** is allowed by default too). 
+
+If returned value is not of one of these types - **graphql-php** will add an error to result 
+and set the field value to **null** (only if the field is nullable, see below for non-null fields).
+
+# Non-Null fields
+By default in GraphQL, every field can have a **null** value. To indicate that some field always 
+returns **non-null** value - use `GraphQL\Type\Definition\Type::nonNull()` modifier:
+
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$humanType = new ObjectType([
+    'name' => 'User',
+    'fields' => [
+        'id' => [
+            'type' => Type::nonNull(Type::id()),
+            'resolve' => function() {
+                return uniqid();
+            }
+        ],
+        'emails' => [
+            'type' => Type::nonNull(Type::listOf(Type::string())),
+            'resolve' => function() {
+                return ['jon@example.com', 'jonny@example.com'];
+            }
+        ]
+    ]
+]);
+```
+
+If resolver of non-null field returns **null**, graphql-php will add an error to 
+result and exclude the whole object from the output (an error will bubble to first 
+nullable parent field which will be set to **null**).
+
+Read the section on [Data Fetching](../data-fetching.md) for details.

docs/type-system/object-types.md

@@ -0,0 +1,210 @@
+# Object Type Definition
+Object Type is the most frequently used primitive in a typical GraphQL application.
+
+Conceptually Object Type is a collection of Fields. Each field, in turn,
+has its own type which allows building complex hierarchies.
+
+In **graphql-php** object type is an instance of `GraphQL\Type\Definition\ObjectType` 
+(or one of it subclasses) which accepts configuration array in constructor:
+
+```php
+<?php
+namespace MyApp;
+
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Examples\Blog\Data\DataSource;
+use GraphQL\Examples\Blog\Data\Story;
+
+$userType = new ObjectType([
+    'name' => 'User',
+    'description' => 'Our blog visitor',
+    'fields' => [
+        'firstName' => [
+            'type' => Type::string(),
+            'description' => 'User first name'
+        ],
+        'email' => Type::string()
+    ]
+]);
+
+$blogStory = new ObjectType([
+    'name' => 'Story',
+    'fields' => [
+        'body' => Type::string(),
+        'author' => [
+            'type' => $userType,
+            'description' => 'Story author',
+            'resolve' => function(Story $blogStory) {
+                return DataSource::findUser($blogStory->authorId);
+            }
+        ],
+        'likes' => [
+            'type' => Type::listOf($userType),
+            'description' => 'List of users who liked the story',
+            'args' => [
+                'limit' => [
+                    'type' => Type::int(),
+                    'description' => 'Limit the number of recent likes returned',
+                    'defaultValue' => 10
+                ]
+            ],
+            'resolve' => function(Story $blogStory, $args) {
+                return DataSource::findLikes($blogStory->id, $args['limit']);
+            }
+        ]
+    ]
+]);
+```
+This example uses **inline** style for Object Type definitions, but you can also use  
+[inheritance or type language](index.md#type-definition-styles).
+
+
+# Configuration options
+Object type constructor expects configuration array. Below is a full list of available options:
+
+Option       | Type     | Notes
+------------ | -------- | -----
+name         | `string` | **Required.** Unique name of this object type within Schema
+fields       | `array` or `callable` | **Required**. An array describing object fields or callable returning such an array. See [Fields](#field-definitions) section below for expected structure of each array entry. See also the section on [Circular types](#recurring-and-circular-types) for an explanation of when to use callable for this option.
+description  | `string` | Plain-text description of this type for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+interfaces   | `array` or `callable` | List of interfaces implemented by this type or callable returning such a list. See [Interface Types](interfaces.md) for details. See also the section on [Circular types](#recurring-and-circular-types) for an explanation of when to use callable for this option.
+isTypeOf     | `callable` | **function($value, $context, [ResolveInfo](../reference.md#graphqltypedefinitionresolveinfo) $info)**<br> Expected to return **true** if **$value** qualifies for this type (see section about [Abstract Type Resolution](interfaces.md#interface-role-in-data-fetching) for explanation).
+resolveField | `callable` | **function($value, $args, $context, [ResolveInfo](../reference.md#graphqltypedefinitionresolveinfo) $info)**<br> Given the **$value** of this type, it is expected to return value for a field defined in **$info->fieldName**. A good place to define a type-specific strategy for field resolution. See section on [Data Fetching](../data-fetching.md) for details.
+
+# Field configuration options
+Below is a full list of available field configuration options:
+
+Option | Type | Notes
+------ | ---- | -----
+name | `string` | **Required.** Name of the field. When not set - inferred from **fields** array key (read about [shorthand field definition](#shorthand-field-definitions) below)
+type | `Type` | **Required.** An instance of internal or custom type. Note: type must be represented by a single instance within one schema (see also [Type Registry](index.md#type-registry))
+args | `array` | An array of possible type arguments. Each entry is expected to be an array with keys: **name**, **type**, **description**, **defaultValue**. See [Field Arguments](#field-arguments) section below.
+resolve | `callable` | **function($objectValue, $args, $context, [ResolveInfo](../reference.md#graphqltypedefinitionresolveinfo) $info)**<br> Given the **$objectValue** of this type, it is expected to return actual value of the current field. See section on [Data Fetching](../data-fetching.md) for details
+complexity | `callable` | **function($childrenComplexity, $args)**<br> Used to restrict query complexity. The feature is disabled by default, read about [Security](../security.md#query-complexity-analysis) to use it.
+description | `string` | Plain-text description of this field for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+deprecationReason | `string` | Text describing why this field is deprecated. When not empty - field will not be returned by introspection queries (unless forced)
+
+# Field arguments
+Every field on a GraphQL object type can have zero or more arguments, defined in **args** option of field definition.
+Each argument is an array with following options:
+
+Option | Type | Notes
+------ | ---- | -----
+name | `string` | **Required.** Name of the argument. When not set - inferred from **args** array key
+type | `Type` | **Required.** Instance of one of [Input Types](input-types.md) (**scalar**, **enum**, **InputObjectType** + any combination of those with **nonNull** and **listOf** modifiers)
+description | `string` | Plain-text description of this argument for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+defaultValue | `scalar` | Default value for this argument. Use the internal value if specifying a default for an **enum** type
+
+# Shorthand field definitions
+Fields can be also defined in **shorthand** notation (with only **name** and **type** options):
+```php
+'fields' => [
+    'id' => Type::id(),
+    'fieldName' => $fieldType
+]
+```
+which is equivalent of:
+```php
+'fields' => [
+    'id' => ['type' => Type::id()],
+    'fieldName' => ['type' => $fieldName]
+]
+```
+which is in turn equivalent of the full form:
+```php
+'fields' => [
+    ['name' => 'id', 'type' => Type::id()],
+    ['name' => 'fieldName', 'type' => $fieldName]
+]
+```
+Same shorthand notation applies to field arguments as well.
+
+# Recurring and circular types
+Almost all real-world applications contain recurring or circular types. 
+Think user friends or nested comments for example. 
+
+**graphql-php** allows such types, but you have to use `callable` in 
+option **fields** (and/or **interfaces**).
+ 
+For example:
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$userType = null;
+
+$userType = new ObjectType([
+    'name' => 'User',
+    'fields' => function() use (&$userType) {
+        return [
+            'email' => [
+                'type' => Type::string()
+            ],
+            'friends' => [
+                'type' => Type::listOf($userType)
+            ]
+        ];
+    }
+]);
+```
+
+Same example for [inheritance style of type definitions](index.md#type-definition-styles) using [TypeRegistry](index.md#type-registry):
+```php
+<?php
+namespace MyApp;
+
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+class UserType extends ObjectType
+{
+    public function __construct()
+    {
+        $config = [
+            'fields' => function() {
+                return [
+                    'email' => MyTypes::string(),
+                    'friends' => MyTypes::listOf(MyTypes::user())
+                ];
+            }
+        ];
+        parent::__construct($config);
+    }
+}
+
+class MyTypes 
+{
+    private static $user;
+    
+    public static function user()
+    {
+        return self::$user ?: (self::$user = new UserType());
+    }
+    
+    public static function string()
+    {
+        return Type::string();
+    }
+    
+    public static function listOf($type)
+    {
+        return Type::listOf($type);
+    }
+}
+```
+
+# Field Resolution
+Field resolution is the primary mechanism in **graphql-php** for returning actual data for your fields.
+It is implemented using **resolveField** callable in type definition or **resolve**
+callable in field definition (which has precedence).
+
+Read the section on [Data Fetching](../data-fetching.md) for a complete description of this process.
+
+# Custom Metadata
+All types in **graphql-php** accept configuration array. In some cases, you may be interested in 
+passing your own metadata for type or field definition.
+
+**graphql-php** preserves original configuration array in every type or field instance in 
+public property **$config**. Use it to implement app-level mappings and definitions.

docs/type-system/scalar-types.md

@@ -0,0 +1,130 @@
+# Built-in Scalar Types
+GraphQL specification describes several built-in scalar types. In **graphql-php** they are 
+exposed as static methods of [`GraphQL\Type\Definition\Type`](../reference.md#graphqltypedefinitiontype) class:
+
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+
+// Built-in Scalar types:
+Type::string();  // String type
+Type::int();     // Int type
+Type::float();   // Float type
+Type::boolean(); // Boolean type
+Type::id();      // ID type
+```
+Those methods return instances of `GraphQL\Type\Definition\ScalarType` (actually one of subclasses).
+Use them directly in type definitions, or wrap in your [TypeRegistry](index.md#type-registry) 
+(if you use one).
+
+# Writing Custom Scalar Types
+In addition to built-in scalars, you can define your own scalar types with additional validation. 
+Typical examples of such types are **Email**, **Date**, **Url**, etc.
+
+In order to implement your own type, you must understand how scalars are presented in GraphQL.
+GraphQL deals with scalars in following cases:
+
+1. When converting **internal representation** of value returned by your app (e.g. stored in a database 
+or hardcoded in the source code) to **serialized** representation included in the response.
+ 
+2. When converting **input value** passed by a client in variables along with GraphQL query to 
+**internal representation** of your app.
+
+3. When converting **input literal value** hardcoded in GraphQL query (e.g. field argument value) to 
+the **internal representation** of your app.
+
+Those cases are covered by methods `serialize`, `parseValue` and `parseLiteral` of abstract `ScalarType` 
+class respectively.
+
+Here is an example of a simple **Email** type:
+
+```php
+<?php
+namespace MyApp;
+
+use GraphQL\Error\Error;
+use GraphQL\Error\InvariantViolation;
+use GraphQL\Language\AST\StringValueNode;
+use GraphQL\Type\Definition\ScalarType;
+use GraphQL\Utils\Utils;
+
+class EmailType extends ScalarType
+{
+    // Note: name can be omitted. In this case it will be inferred from class name 
+    // (suffix "Type" will be dropped)
+    public $name = 'Email';
+
+    /**
+     * Serializes an internal value to include in a response.
+     *
+     * @param string $value
+     * @return string
+     */
+    public function serialize($value)
+    {
+        // Assuming internal representation of email is always correct:
+        return $value;
+        
+        // If it might be incorrect and you want to make sure that only correct values are included
+        // in response - use following line instead:
+        // if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
+        //     throw new InvariantViolation("Could not serialize following value as email: " . Utils::printSafe($value));
+        // }
+        // return $this->parseValue($value);
+    }
+
+    /**
+     * Parses an externally provided value (query variable) to use as an input
+     *
+     * @param mixed $value
+     * @return mixed
+     */
+    public function parseValue($value)
+    {
+        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
+            throw new Error("Cannot represent following value as email: " . Utils::printSafeJson($value));
+        }
+        return $value;
+    }
+
+    /**
+     * Parses an externally provided literal value (hardcoded in GraphQL query) to use as an input.
+     * 
+     * E.g. 
+     * {
+     *   user(email: "user@example.com") 
+     * }
+     *
+     * @param \GraphQL\Language\AST\Node $valueNode
+     * @param array|null $variables
+     * @return string
+     * @throws Error
+     */
+    public function parseLiteral($valueNode, array $variables = null)
+    {
+        // Note: throwing GraphQL\Error\Error vs \UnexpectedValueException to benefit from GraphQL
+        // error location in query:
+        if (!$valueNode instanceof StringValueNode) {
+            throw new Error('Query error: Can only parse strings got: ' . $valueNode->kind, [$valueNode]);
+        }
+        if (!filter_var($valueNode->value, FILTER_VALIDATE_EMAIL)) {
+            throw new Error("Not a valid email", [$valueNode]);
+        }
+        return $valueNode->value;
+    }
+}
+```
+
+Or with inline style:
+
+```php
+<?php
+use GraphQL\Type\Definition\CustomScalarType;
+
+$emailType = new CustomScalarType([
+    'name' => 'Email',
+    'serialize' => function($value) {/* See function body above */},
+    'parseValue' => function($value) {/* See function body above */},
+    'parseLiteral' => function($valueNode, array $variables = null) {/* See function body above */},
+]);
+```

docs/type-system/schema.md

@@ -0,0 +1,194 @@
+# Schema Definition
+The schema is a container of your type hierarchy, which accepts root types in a constructor and provides
+methods for receiving information about your types to internal GrahpQL tools.
+
+In **graphql-php** schema is an instance of [`GraphQL\Type\Schema`](../reference.md#graphqltypeschema) 
+which accepts configuration array in a constructor:
+
+```php
+<?php
+use GraphQL\Type\Schema;
+
+$schema = new Schema([
+    'query' => $queryType, 
+    'mutation' => $mutationType,
+]);
+```
+See possible constructor options [below](#configuration-options).
+
+# Query and Mutation types
+The schema consists of two root types:
+ 
+* **Query** type is a surface of your read API
+* **Mutation** type (optional) exposes write API by declaring all possible mutations in your app. 
+
+Query and Mutation types are regular [object types](object-types.md) containing root-level fields 
+of your API:
+
+```php
+<?php
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+
+$queryType = new ObjectType([
+    'name' => 'Query',
+    'fields' => [
+        'hello' => [
+            'type' => Type::string(),
+            'resolve' => function() {
+                return 'Hello World!';
+            }
+        ],
+        'hero' => [
+            'type' => $characterInterface,
+            'args' => [
+                'episode' => [
+                    'type' => $episodeEnum
+                ]
+            ],
+            'resolve' => function ($rootValue, $args) {
+                return StarWarsData::getHero(isset($args['episode']) ? $args['episode'] : null);
+            },
+        ]
+    ]
+]);
+
+$mutationType = new ObjectType([
+    'name' => 'Mutation',
+    'fields' => [
+        'createReview' => [
+            'type' => $createReviewOutput,
+            'args' => [
+                'episode' => $episodeEnum,
+                'review' => $reviewInputObject
+            ],
+            'resolve' => function($rootValue, $args) {
+                // TODOC
+            }
+        ]
+    ]
+]);
+```
+
+Keep in mind that other than the special meaning of declaring a surface area of your API, 
+those types are the same as any other [object type](object-types.md), and their fields work 
+exactly the same way.
+
+**Mutation** type is also just a regular object type. The difference is in semantics. 
+Field names of Mutation type are usually verbs and they almost always have arguments - quite often 
+with complex input values (see [Mutations and Input Types](input-types.md) for details).
+
+# Configuration Options
+Schema constructor expects an instance of [`GraphQL\Type\SchemaConfig`](../reference.md#graphqltypeschemaconfig) 
+or an array with following options:
+
+Option       | Type     | Notes
+------------ | -------- | -----
+query        | `ObjectType` | **Required.** Object type (usually named "Query") containing root-level fields of your read API
+mutation     | `ObjectType` | Object type (usually named "Mutation") containing root-level fields of your write API
+subscription     | `ObjectType` | Reserved for future subscriptions implementation. Currently presented for compatibility with introspection query of **graphql-js**, used by various clients (like Relay or GraphiQL)
+directives  | `Directive[]` | A full list of [directives](directives.md) supported by your schema. By default, contains built-in **@skip** and **@include** directives.<br><br> If you pass your own directives and still want to use built-in directives - add them explicitly. For example:<br><br> *array_merge(GraphQL::getStandardDirectives(), [$myCustomDirective]);*
+types     | `ObjectType[]` | List of object types which cannot be detected by **graphql-php** during static schema analysis.<br><br>Most often it happens when the object type is never referenced in fields directly but is still a part of a schema because it implements an interface which resolves to this object type in its **resolveType** callable. <br><br> Note that you are not required to pass all of your types here - it is simply a workaround for concrete use-case.
+typeLoader     | `callable` | **function($name)** Expected to return type instance given the name. Must always return the same instance if called multiple times. See section below on lazy type loading.
+
+# Using config class
+If you prefer fluid interface for config with auto-completion in IDE and static time validation, 
+use [`GraphQL\Type\SchemaConfig`](../reference.md#graphqltypeschemaconfig) instead of an array:
+
+```php
+<?php
+use GraphQL\Type\SchemaConfig;
+use GraphQL\Type\Schema;
+
+$config = SchemaConfig::create()
+    ->setQuery($myQueryType)
+    ->setTypeLoader($myTypeLoader);
+
+$schema = new Schema($config);
+```
+
+
+# Lazy loading of types
+By default, the schema will scan all of your type, field and argument definitions to serve GraphQL queries. 
+It may cause performance overhead when there are many types in the schema. 
+
+In this case, it is recommended to pass **typeLoader** option to schema constructor and define all 
+of your object **fields** as callbacks.
+
+Type loading concept is very similar to PHP class loading, but keep in mind that **typeLoader** must
+always return the same instance of a type.
+
+Usage example:
+```php
+<?php
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Schema;
+
+class Types
+{
+    private $types = [];
+
+    public function get($name)
+    {
+        if (!isset($this->types[$name])) {
+            $this->types[$name] = $this->{$name}();
+        }
+        return $this->types[$name];
+    }
+
+    private function MyTypeA()
+    {
+        return new ObjectType([
+            'name' => 'MyTypeA',
+            'fields' => function() {
+                return [
+                    'b' => ['type' => $this->get('MyTypeB')]
+                ];
+            }
+        ]);
+    }
+    
+    private function MyTypeB()
+    {
+        // ...
+    }
+}
+
+$registry = new Types();
+
+$schema = new Schema([
+    'query' => $registry->get('Query'),
+    'typeLoader' => function($name) use ($registry) {
+        return $registry->get($name);
+    }
+]);
+```
+
+
+# Schema Validation
+By default, the schema is created with only shallow validation of type and field definitions  
+(because validation requires full schema scan and is very costly on bigger schemas).
+
+But there is a special method **assertValid()** on schema instance which throws 
+`GraphQL\Error\InvariantViolation` exception when it encounters any error, like:
+
+- Invalid types used for fields/arguments
+- Missing interface implementations
+- Invalid interface implementations
+- Other schema errors...
+
+Schema validation is supposed to be used in CLI commands or during build step of your app.
+Don't call it in web requests in production. 
+
+Usage example:
+```php
+<?php
+try {
+    $schema = new GraphQL\Type\Schema([
+        'query' => $myQueryType
+    ]);
+    $schema->assertValid();
+} catch (GraphQL\Error\InvariantViolation $e) {
+    echo $e->getMessage();
+}
+```

docs/type-system/type-language.md

@@ -0,0 +1,91 @@
+# Defining your schema
+Since 0.9.0
+
+[Type language](http://graphql.org/learn/schema/#type-language) is a convenient way to define your schema,
+especially with IDE autocompletion and syntax validation.
+
+Here is a simple schema defined in GraphQL type language (e.g. in a separate **schema.graphql** file):
+
+```graphql
+schema {
+    query: Query
+    mutation: Mutation
+}
+
+type Query {
+    greetings(input: HelloInput!): String!
+}
+
+input HelloInput {
+    firstName: String!
+    lastName: String
+}
+```
+
+In order to create schema instance out of this file, use 
+[`GraphQL\Utils\BuildSchema`](../reference.md#graphqlutilsbuildschema):
+
+```php
+<?php
+use GraphQL\Utils\BuildSchema;
+
+$contents = file_get_contents('schema.graphql');
+$schema = BuildSchema::build($contents);
+```
+
+By default, such schema is created without any resolvers.
+
+We have to rely on [default field resolver](../data-fetching.md#default-field-resolver) and **root value** in 
+order to execute a query against this schema.
+
+# Defining resolvers
+Since 0.10.0
+
+In order to enable **Interfaces**, **Unions** and custom field resolvers you can pass the second argument:
+**type config decorator** to schema builder.
+
+It accepts default type config produced by the builder and is expected to add missing options like
+[**resolveType**](interfaces.md#configuration-options) for interface types or
+[**resolveField**](object-types.md#configuration-options) for object types.
+
+```php
+<?php
+use GraphQL\Utils\BuildSchema;
+
+$typeConfigDecorator = function($typeConfig, $typeDefinitionNode) {
+    $name = $typeConfig['name'];
+    // ... add missing options to $typeConfig based on type $name
+    return $typeConfig;
+};
+
+$contents = file_get_contents('schema.graphql');
+$schema = BuildSchema::build($contents, $typeConfigDecorator);
+```
+
+# Performance considerations
+Since 0.10.0
+
+Method **build()** produces a [lazy schema](schema.md#lazy-loading-of-types)
+automatically, so it works efficiently even with very large schemas.
+
+But parsing type definition file on each request is suboptimal, so it is recommended to cache 
+intermediate parsed representation of the schema for the production environment:
+
+```php
+<?php
+use GraphQL\Language\Parser;
+use GraphQL\Utils\BuildSchema;
+use GraphQL\Utils\AST;
+
+$cacheFilename = 'cached_schema.php';
+
+if (!file_exists($cacheFilename)) {
+    $document = Parser::parse(file_get_contents('./schema.graphql'));
+    file_put_contents($cacheFilename, "<?php\nreturn " . var_export(AST::toArray($document), true) . ";\n");
+} else {
+    $document = AST::fromArray(require $cacheFilename); // fromArray() is a lazy operation as well
+}
+
+$typeConfigDecorator = function () {};
+$schema = BuildSchema::build($document, $typeConfigDecorator);
+```

docs/type-system/unions.md

@@ -0,0 +1,39 @@
+# Union Type Definition
+A Union is an abstract type that simply enumerates other Object Types. 
+The value of Union Type is actually a value of one of included Object Types.
+
+In **graphql-php** union type is an instance of `GraphQL\Type\Definition\UnionType` 
+(or one of its subclasses) which accepts configuration array in a constructor:
+
+```php
+<?php
+use GraphQL\Type\Definition\UnionType;
+
+$searchResultType = new UnionType([
+    'name' => 'SearchResult',
+    'types' => [
+        MyTypes::story(),
+        MyTypes::user()
+    ],
+    'resolveType' => function($value) {
+        if ($value->type === 'story') {
+            return MyTypes::story();            
+        } else {
+            return MyTypes::user();
+        }
+    }
+]);
+```
+
+This example uses **inline** style for Union definition, but you can also use  
+[inheritance or type language](index.md#type-definition-styles).
+
+# Configuration options
+The constructor of UnionType accepts an array. Below is a full list of allowed options:
+
+Option | Type | Notes
+------ | ---- | -----
+name | `string` | **Required.** Unique name of this interface type within Schema
+types | `array` | **Required.** List of Object Types included in this Union. Note that you can't create a Union type out of Interfaces or other Unions.
+description | `string` | Plain-text description of this type for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
+resolveType | `callback` | **function($value, $context, [ResolveInfo](../reference.md#graphqltypedefinitionresolveinfo) $info)**<br> Receives **$value** from resolver of the parent field and returns concrete Object Type for this **$value**.

examples/00-hello-world/README.md

@@ -0,0 +1,18 @@
+# Hello world
+Clean and simple single-file example of main GraphQL concepts originally proposed and 
+implemented by [Leo Cavalcante](https://github.com/leocavalcante)
+
+### Run locally
+```
+php -S localhost:8080 ./graphql.php
+```
+
+### Try query
+```
+curl http://localhost:8080 -d '{"query": "query { echo(message: \"Hello World\") }" }'
+```
+
+### Try mutation
+```
+curl http://localhost:8080 -d '{"query": "mutation { sum(x: 2, y: 2) }" }'
+```

examples/00-hello-world/graphql.php

@@ -0,0 +1,69 @@
+<?php
+// Test this using following command
+// php -S localhost:8080 ./graphql.php &
+// curl http://localhost:8080 -d '{"query": "query { echo(message: \"Hello World\") }" }'
+// curl http://localhost:8080 -d '{"query": "mutation { sum(x: 2, y: 2) }" }'
+require_once __DIR__ . '/../../vendor/autoload.php';
+
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Schema;
+use GraphQL\GraphQL;
+
+try {
+    $queryType = new ObjectType([
+        'name' => 'Query',
+        'fields' => [
+            'echo' => [
+                'type' => Type::string(),
+                'args' => [
+                    'message' => ['type' => Type::string()],
+                ],
+                'resolve' => function ($rootValue, $args) {
+                    return $rootValue['prefix'] . $args['message'];
+                }
+            ],
+        ],
+    ]);
+
+    $mutationType = new ObjectType([
+        'name' => 'Calc',
+        'fields' => [
+            'sum' => [
+                'type' => Type::int(),
+                'args' => [
+                    'x' => ['type' => Type::int()],
+                    'y' => ['type' => Type::int()],
+                ],
+                'resolve' => function ($calc, $args) {
+                    return $args['x'] + $args['y'];
+                },
+            ],
+        ],
+    ]);
+
+    // See docs on schema options:
+    // http://webonyx.github.io/graphql-php/type-system/schema/#configuration-options
+    $schema = new Schema([
+        'query' => $queryType,
+        'mutation' => $mutationType,
+    ]);
+
+    $rawInput = file_get_contents('php://input');
+    $input = json_decode($rawInput, true);
+    $query = $input['query'];
+    $variableValues = isset($input['variables']) ? $input['variables'] : null;
+
+    $rootValue = ['prefix' => 'You said: '];
+    $result = GraphQL::executeQuery($schema, $query, $rootValue, null, $variableValues);
+    $output = $result->toArray();
+} catch (\Exception $e) {
+    $output = [
+        'error' => [
+            'message' => $e->getMessage()
+        ]
+    ];
+}
+header('Content-Type: application/json; charset=UTF-8');
+echo json_encode($output);
+

examples/01-blog/Blog/AppContext.php

@@ -0,0 +1,28 @@
+<?php
+namespace GraphQL\Examples\Blog;
+
+use GraphQL\Examples\Blog\Data\User;
+
+/**
+ * Class AppContext
+ * Instance available in all GraphQL resolvers as 3rd argument
+ *
+ * @package GraphQL\Examples\Blog
+ */
+class AppContext
+{
+    /**
+     * @var string
+     */
+    public $rootUrl;
+
+    /**
+     * @var User
+     */
+    public $viewer;
+
+    /**
+     * @var \mixed
+     */
+    public $request;
+}

examples/01-blog/Blog/Data/Comment.php

@@ -0,0 +1,25 @@
+<?php
+namespace GraphQL\Examples\Blog\Data;
+
+
+use GraphQL\Utils\Utils;
+
+class Comment
+{
+    public $id;
+
+    public $authorId;
+
+    public $storyId;
+
+    public $parentId;
+
+    public $body;
+
+    public $isAnonymous;
+
+    public function __construct(array $data)
+    {
+        Utils::assign($this, $data);
+    }
+}

examples/01-blog/Blog/Data/DataSource.php

@@ -0,0 +1,206 @@
+<?php
+namespace GraphQL\Examples\Blog\Data;
+
+/**
+ * Class DataSource
+ *
+ * This is just a simple in-memory data holder for the sake of example.
+ * Data layer for real app may use Doctrine or query the database directly (e.g. in CQRS style)
+ *
+ * @package GraphQL\Examples\Blog
+ */
+class DataSource
+{
+    private static $users = [];
+    private static $stories = [];
+    private static $storyLikes = [];
+    private static $comments = [];
+    private static $storyComments = [];
+    private static $commentReplies = [];
+    private static $storyMentions = [];
+
+    public static function init()
+    {
+        self::$users = [
+            '1' => new User([
+                'id' => '1',
+                'email' => 'john@example.com',
+                'firstName' => 'John',
+                'lastName' => 'Doe'
+            ]),
+            '2' => new User([
+                'id' => '2',
+                'email' => 'jane@example.com',
+                'firstName' => 'Jane',
+                'lastName' => 'Doe'
+            ]),
+            '3' => new User([
+                'id' => '3',
+                'email' => 'john@example.com',
+                'firstName' => 'John',
+                'lastName' => 'Doe'
+            ]),
+        ];
+
+        self::$stories = [
+            '1' => new Story(['id' => '1', 'authorId' => '1', 'body' => '<h1>GraphQL is awesome!</h1>']),
+            '2' => new Story(['id' => '2', 'authorId' => '1', 'body' => '<a>Test this</a>']),
+            '3' => new Story(['id' => '3', 'authorId' => '3', 'body' => "This\n<br>story\n<br>spans\n<br>newlines"]),
+        ];
+
+        self::$storyLikes = [
+            '1' => ['1', '2', '3'],
+            '2' => [],
+            '3' => ['1']
+        ];
+
+        self::$comments = [
+            // thread #1:
+            '100' => new Comment(['id' => '100', 'authorId' => '3', 'storyId' => '1', 'body' => 'Likes']),
+                '110' => new Comment(['id' =>'110', 'authorId' =>'2', 'storyId' => '1', 'body' => 'Reply <b>#1</b>', 'parentId' => '100']),
+                    '111' => new Comment(['id' => '111', 'authorId' => '1', 'storyId' => '1', 'body' => 'Reply #1-1', 'parentId' => '110']),
+                    '112' => new Comment(['id' => '112', 'authorId' => '3', 'storyId' => '1', 'body' => 'Reply #1-2', 'parentId' => '110']),
+                    '113' => new Comment(['id' => '113', 'authorId' => '2', 'storyId' => '1', 'body' => 'Reply #1-3', 'parentId' => '110']),
+                    '114' => new Comment(['id' => '114', 'authorId' => '1', 'storyId' => '1', 'body' => 'Reply #1-4', 'parentId' => '110']),
+                    '115' => new Comment(['id' => '115', 'authorId' => '3', 'storyId' => '1', 'body' => 'Reply #1-5', 'parentId' => '110']),
+                    '116' => new Comment(['id' => '116', 'authorId' => '1', 'storyId' => '1', 'body' => 'Reply #1-6', 'parentId' => '110']),
+                    '117' => new Comment(['id' => '117', 'authorId' => '2', 'storyId' => '1', 'body' => 'Reply #1-7', 'parentId' => '110']),
+                '120' => new Comment(['id' => '120', 'authorId' => '3', 'storyId' => '1', 'body' => 'Reply #2', 'parentId' => '100']),
+                '130' => new Comment(['id' => '130', 'authorId' => '3', 'storyId' => '1', 'body' => 'Reply #3', 'parentId' => '100']),
+            '200' => new Comment(['id' => '200', 'authorId' => '2', 'storyId' => '1', 'body' => 'Me2']),
+            '300' => new Comment(['id' => '300', 'authorId' => '3', 'storyId' => '1', 'body' => 'U2']),
+
+            # thread #2:
+            '400' => new Comment(['id' => '400', 'authorId' => '2', 'storyId' => '2', 'body' => 'Me too']),
+            '500' => new Comment(['id' => '500', 'authorId' => '2', 'storyId' => '2', 'body' => 'Nice!']),
+        ];
+
+        self::$storyComments = [
+            '1' => ['100', '200', '300'],
+            '2' => ['400', '500']
+        ];
+
+        self::$commentReplies = [
+            '100' => ['110', '120', '130'],
+            '110' => ['111', '112', '113', '114', '115', '116', '117'],
+        ];
+
+        self::$storyMentions = [
+            '1' => [
+                self::$users['2']
+            ],
+            '2' => [
+                self::$stories['1'],
+                self::$users['3']
+            ]
+        ];
+    }
+
+    public static function findUser($id)
+    {
+        return isset(self::$users[$id]) ? self::$users[$id] : null;
+    }
+
+    public static function findStory($id)
+    {
+        return isset(self::$stories[$id]) ? self::$stories[$id] : null;
+    }
+
+    public static function findComment($id)
+    {
+        return isset(self::$comments[$id]) ? self::$comments[$id] : null;
+    }
+
+    public static function findLastStoryFor($authorId)
+    {
+        $storiesFound = array_filter(self::$stories, function(Story $story) use ($authorId) {
+            return $story->authorId == $authorId;
+        });
+        return !empty($storiesFound) ? $storiesFound[count($storiesFound) - 1] : null;
+    }
+
+    public static function findLikes($storyId, $limit)
+    {
+        $likes = isset(self::$storyLikes[$storyId]) ? self::$storyLikes[$storyId] : [];
+        $result = array_map(
+            function($userId) {
+                return self::$users[$userId];
+            },
+            $likes
+        );
+        return array_slice($result, 0, $limit);
+    }
+
+    public static function isLikedBy($storyId, $userId)
+    {
+        $subscribers = isset(self::$storyLikes[$storyId]) ? self::$storyLikes[$storyId] : [];
+        return in_array($userId, $subscribers);
+    }
+
+    public static function getUserPhoto($userId, $size)
+    {
+        return new Image([
+            'id' => $userId,
+            'type' => Image::TYPE_USERPIC,
+            'size' => $size,
+            'width' => rand(100, 200),
+            'height' => rand(100, 200)
+        ]);
+    }
+
+    public static function findLatestStory()
+    {
+        return array_pop(self::$stories);
+    }
+
+    public static function findStories($limit, $afterId = null)
+    {
+        $start = $afterId ? (int) array_search($afterId, array_keys(self::$stories)) + 1 : 0;
+        return array_slice(array_values(self::$stories), $start, $limit);
+    }
+
+    public static function findComments($storyId, $limit = 5, $afterId = null)
+    {
+        $storyComments = isset(self::$storyComments[$storyId]) ? self::$storyComments[$storyId] : [];
+
+        $start = isset($after) ? (int) array_search($afterId, $storyComments) + 1 : 0;
+        $storyComments = array_slice($storyComments, $start, $limit);
+
+        return array_map(
+            function($commentId) {
+                return self::$comments[$commentId];
+            },
+            $storyComments
+        );
+    }
+
+    public static function findReplies($commentId, $limit = 5, $afterId = null)
+    {
+        $commentReplies = isset(self::$commentReplies[$commentId]) ? self::$commentReplies[$commentId] : [];
+
+        $start = isset($after) ? (int) array_search($afterId, $commentReplies) + 1: 0;
+        $commentReplies = array_slice($commentReplies, $start, $limit);
+
+        return array_map(
+            function($replyId) {
+                return self::$comments[$replyId];
+            },
+            $commentReplies
+        );
+    }
+
+    public static function countComments($storyId)
+    {
+        return isset(self::$storyComments[$storyId]) ? count(self::$storyComments[$storyId]) : 0;
+    }
+
+    public static function countReplies($commentId)
+    {
+        return isset(self::$commentReplies[$commentId]) ? count(self::$commentReplies[$commentId]) : 0;
+    }
+
+    public static function findStoryMentions($storyId)
+    {
+        return isset(self::$storyMentions[$storyId]) ? self::$storyMentions[$storyId] :[];
+    }
+}

examples/01-blog/Blog/Data/Image.php

@@ -0,0 +1,29 @@
+<?php
+namespace GraphQL\Examples\Blog\Data;
+
+use GraphQL\Utils\Utils;
+
+class Image
+{
+    const TYPE_USERPIC = 'userpic';
+
+    const SIZE_ICON = 'icon';
+    const SIZE_SMALL = 'small';
+    const SIZE_MEDIUM = 'medium';
+    const SIZE_ORIGINAL = 'original';
+
+    public $id;
+
+    public $type;
+
+    public $size;
+
+    public $width;
+
+    public $height;
+
+    public function __construct(array $data)
+    {
+        Utils::assign($this, $data);
+    }
+}

examples/01-blog/Blog/Data/Story.php

@@ -0,0 +1,22 @@
+<?php
+namespace GraphQL\Examples\Blog\Data;
+
+use GraphQL\Utils\Utils;
+
+class Story
+{
+    public $id;
+
+    public $authorId;
+
+    public $title;
+
+    public $body;
+
+    public $isAnonymous = false;
+
+    public function __construct(array $data)
+    {
+        Utils::assign($this, $data);
+    }
+}

examples/01-blog/Blog/Data/User.php

@@ -0,0 +1,22 @@
+<?php
+namespace GraphQL\Examples\Blog\Data;
+
+use GraphQL\Utils\Utils;
+
+class User
+{
+    public $id;
+
+    public $email;
+
+    public $firstName;
+
+    public $lastName;
+
+    public $hasPhoto;
+
+    public function __construct(array $data)
+    {
+        Utils::assign($this, $data);
+    }
+}

examples/01-blog/Blog/Type/CommentType.php

@@ -0,0 +1,76 @@
+<?php
+namespace GraphQL\Examples\Blog\Type;
+
+use GraphQL\Examples\Blog\AppContext;
+use GraphQL\Examples\Blog\Data\Comment;
+use GraphQL\Examples\Blog\Data\DataSource;
+use GraphQL\Examples\Blog\Types;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\ResolveInfo;
+
+class CommentType extends ObjectType
+{
+    public function __construct()
+    {
+        $config = [
+            'name' => 'Comment',
+            'fields' => function() {
+                return [
+                    'id' => Types::id(),
+                    'author' => Types::user(),
+                    'parent' => Types::comment(),
+                    'isAnonymous' => Types::boolean(),
+                    'replies' => [
+                        'type' => Types::listOf(Types::comment()),
+                        'args' => [
+                            'after' => Types::int(),
+                            'limit' => [
+                                'type' => Types::int(),
+                                'defaultValue' => 5
+                            ]
+                        ]
+                    ],
+                    'totalReplyCount' => Types::int(),
+
+                    Types::htmlField('body')
+                ];
+            },
+            'resolveField' => function($comment, $args, $context, ResolveInfo $info) {
+                $method = 'resolve' . ucfirst($info->fieldName);
+                if (method_exists($this, $method)) {
+                    return $this->{$method}($comment, $args, $context, $info);
+                } else {
+                    return $comment->{$info->fieldName};
+                }
+            }
+        ];
+        parent::__construct($config);
+    }
+
+    public function resolveAuthor(Comment $comment)
+    {
+        if ($comment->isAnonymous) {
+            return null;
+        }
+        return DataSource::findUser($comment->authorId);
+    }
+
+    public function resolveParent(Comment $comment)
+    {
+        if ($comment->parentId) {
+            return DataSource::findComment($comment->parentId);
+        }
+        return null;
+    }
+
+    public function resolveReplies(Comment $comment, $args)
+    {
+        $args += ['after' => null];
+        return DataSource::findReplies($comment->id, $args['limit'], $args['after']);
+    }
+
+    public function resolveTotalReplyCount(Comment $comment)
+    {
+        return DataSource::countReplies($comment->id);
+    }
+}

examples/01-blog/Blog/Type/Enum/ContentFormatEnum.php

@@ -0,0 +1,19 @@
+<?php
+namespace GraphQL\Examples\Blog\Type\Enum;
+
+use GraphQL\Type\Definition\EnumType;
+
+class ContentFormatEnum extends EnumType
+{
+    const FORMAT_TEXT = 'TEXT';
+    const FORMAT_HTML = 'HTML';
+
+    public function __construct()
+    {
+        $config = [
+            'name' => 'ContentFormatEnum',
+            'values' => [self::FORMAT_TEXT, self::FORMAT_HTML]
+        ];
+        parent::__construct($config);
+    }
+}

examples/01-blog/Blog/Type/Enum/ImageSizeEnumType.php

@@ -0,0 +1,23 @@
+<?php
+namespace GraphQL\Examples\Blog\Type\Enum;
+
+use GraphQL\Examples\Blog\Data\Image;
+use GraphQL\Type\Definition\EnumType;
+
+class ImageSizeEnumType extends EnumType
+{
+    public function __construct()
+    {
+        $config = [
+            // Note: 'name' option is not needed in this form - it will be inferred from className
+            'values' => [
+                'ICON' => Image::SIZE_ICON,
+                'SMALL' => Image::SIZE_SMALL,
+                'MEDIUM' => Image::SIZE_MEDIUM,
+                'ORIGINAL' => Image::SIZE_ORIGINAL
+            ]
+        ];
+
+        parent::__construct($config);
+    }
+}

examples/01-blog/Blog/Type/Field/HtmlField.php

@@ -0,0 +1,52 @@
+<?php
+namespace GraphQL\Examples\Blog\Type\Field;
+
+use GraphQL\Examples\Blog\Type\Enum\ContentFormatEnum;
+use GraphQL\Examples\Blog\Types;
+
+class HtmlField
+{
+    public static function build($name, $objectKey = null)
+    {
+        $objectKey = $objectKey ?: $name;
+
+        // Demonstrates how to organize re-usable fields
+        // Usual example: when the same field with same args shows up in different types
+        // (for example when it is a part of some interface)
+        return [
+            'name' => $name,
+            'type' => Types::string(),
+            'args' => [
+                'format' => [
+                    'type' => Types::contentFormatEnum(),
+                    'defaultValue' => ContentFormatEnum::FORMAT_HTML
+                ],
+                'maxLength' => Types::int()
+            ],
+            'resolve' => function($object, $args) use ($objectKey) {
+                $html = $object->{$objectKey};
+                $text = strip_tags($html);
+
+                if (!empty($args['maxLength'])) {
+                    $safeText = mb_substr($text, 0, $args['maxLength']);
+                } else {
+                    $safeText = $text;
+                }
+
+                switch ($args['format']) {
+                    case ContentFormatEnum::FORMAT_HTML:
+                        if ($safeText !== $text) {
+                            // Text was truncated, so just show what's safe:
+                            return nl2br($safeText);
+                        } else {
+                            return $html;
+                        }
+
+                    case ContentFormatEnum::FORMAT_TEXT:
+                    default:
+                        return $safeText;
+                }
+            }
+        ];
+    }
+}

examples/01-blog/Blog/Type/ImageType.php

@@ -0,0 +1,62 @@
+<?php
+namespace GraphQL\Examples\Blog\Type;
+
+use GraphQL\Examples\Blog\AppContext;
+use GraphQL\Examples\Blog\Data\Image;
+use GraphQL\Examples\Blog\Types;
+use GraphQL\Type\Definition\EnumType;
+use GraphQL\Type\Definition\ObjectType;
+
+class ImageType extends ObjectType
+{
+    public function __construct()
+    {
+        $config = [
+            'name' => 'ImageType',
+            'fields' => [
+                'id' => Types::id(),
+                'type' => new EnumType([
+                    'name' => 'ImageTypeEnum',
+                    'values' => [
+                        'USERPIC' => Image::TYPE_USERPIC
+                    ]
+                ]),
+                'size' => Types::imageSizeEnum(),
+                'width' => Types::int(),
+                'height' => Types::int(),
+                'url' => [
+                    'type' => Types::url(),
+                    'resolve' => [$this, 'resolveUrl']
+                ],
+
+                // Just for the sake of example
+                'fieldWithError' => [
+                    'type' => Types::string(),
+                    'resolve' => function() {
+                        throw new \Exception("Field with exception");
+                    }
+                ],
+                'nonNullFieldWithError' => [
+                    'type' => Types::nonNull(Types::string()),
+                    'resolve' => function() {
+                        throw new \Exception("Non-null field with exception");
+                    }
+                ]
+            ]
+        ];
+
+        parent::__construct($config);
+    }
+
+    public function resolveUrl(Image $value, $args, AppContext $context)
+    {
+        switch ($value->type) {
+            case Image::TYPE_USERPIC:
+                $path = "/images/user/{$value->id}-{$value->size}.jpg";
+                break;
+            default:
+                throw new \UnexpectedValueException("Unexpected image type: " . $value->type);
+        }
+        return $context->rootUrl . $path;
+    }
+}

examples/01-blog/Blog/Type/NodeType.php

@@ -0,0 +1,34 @@
+<?php
+namespace GraphQL\Examples\Blog\Type;
+
+use GraphQL\Examples\Blog\Data\Story;
+use GraphQL\Examples\Blog\Data\User;
+use GraphQL\Examples\Blog\Data\Image;
+use GraphQL\Examples\Blog\Types;
+use GraphQL\Type\Definition\InterfaceType;
+
+class NodeType extends InterfaceType
+{
+    public function __construct()
+    {
+        $config = [
+            'name' => 'Node',
+            'fields' => [
+                'id' => Types::id()
+            ],
+            'resolveType' => [$this, 'resolveNodeType']
+        ];
+        parent::__construct($config);
+    }
+
+    public function resolveNodeType($object)
+    {
+        if ($object instanceof User) {
+            return Types::user();
+        } else if ($object instanceof Image) {
+            return Types::image();
+        } else if ($object instanceof Story) {
+            return Types::story();
+        }
+    }
+}

examples/01-blog/Blog/Type/QueryType.php

@@ -0,0 +1,97 @@
+<?php
+namespace GraphQL\Examples\Blog\Type;
+
+use GraphQL\Examples\Blog\AppContext;
+use GraphQL\Examples\Blog\Data\DataSource;
+use GraphQL\Examples\Blog\Types;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\ResolveInfo;
+use GraphQL\Type\Definition\Type;
+
+class QueryType extends ObjectType
+{
+    public function __construct()
+    {
+        $config = [
+            'name' => 'Query',
+            'fields' => [
+                'user' => [
+                    'type' => Types::user(),
+                    'description' => 'Returns user by id (in range of 1-5)',
+                    'args' => [
+                        'id' => Types::nonNull(Types::id())
+                    ]
+                ],
+                'viewer' => [
+                    'type' => Types::user(),
+                    'description' => 'Represents currently logged-in user (for the sake of example - simply returns user with id == 1)'
+                ],
+                'stories' => [
+                    'type' => Types::listOf(Types::story()),
+                    'description' => 'Returns subset of stories posted for this blog',
+                    'args' => [
+                        'after' => [
+                            'type' => Types::id(),
+                            'description' => 'Fetch stories listed after the story with this ID'
+                        ],
+                        'limit' => [
+                            'type' => Types::int(),
+                            'description' => 'Number of stories to be returned',
+                            'defaultValue' => 10
+                        ]
+                    ]
+                ],
+                'lastStoryPosted' => [
+                    'type' => Types::story(),
+                    'description' => 'Returns last story posted for this blog'
+                ],
+                'deprecatedField' => [
+                    'type' => Types::string(),
+                    'deprecationReason' => 'This field is deprecated!'
+                ],
+                'fieldWithException' => [
+                    'type' => Types::string(),
+                    'resolve' => function() {
+                        throw new \Exception("Exception message thrown in field resolver");
+                    }
+                ],
+                'hello' => Type::string()
+            ],
+            'resolveField' => function($rootValue, $args, $context, ResolveInfo $info) {
+                return $this->{$info->fieldName}($rootValue, $args, $context, $info);
+            }
+        ];
+        parent::__construct($config);
+    }
+
+    public function user($rootValue, $args)
+    {
+        return DataSource::findUser($args['id']);
+    }
+
+    public function viewer($rootValue, $args, AppContext $context)
+    {
+        return $context->viewer;
+    }
+
+    public function stories($rootValue, $args)
+    {
+        $args += ['after' => null];
+        return DataSource::findStories($args['limit'], $args['after']);
+    }
+
+    public function lastStoryPosted()
+    {
+        return DataSource::findLatestStory();
+    }
+
+    public function hello()
+    {
+        return 'Your graphql-php endpoint is ready! Use GraphiQL to browse API';
+    }
+
+    public function deprecatedField()
+    {
+        return 'You can request deprecated field, but it is not displayed in auto-generated documentation by default.';
+    }
+}

examples/01-blog/Blog/Type/Scalar/EmailType.php

@@ -0,0 +1,70 @@
+<?php
+namespace GraphQL\Examples\Blog\Type\Scalar;
+
+use GraphQL\Error\Error;
+use GraphQL\Language\AST\StringValueNode;
+use GraphQL\Type\Definition\CustomScalarType;
+use GraphQL\Utils\Utils;
+
+class EmailType
+{
+    public static function create()
+    {
+        return new CustomScalarType([
+            'name' => 'Email',
+            'serialize' => [__CLASS__, 'serialize'],
+            'parseValue' => [__CLASS__, 'parseValue'],
+            'parseLiteral' => [__CLASS__, 'parseLiteral'],
+        ]);
+    }
+
+    /**
+     * Serializes an internal value to include in a response.
+     *
+     * @param string $value
+     * @return string
+     */
+    public static function serialize($value)
+    {
+        // Assuming internal representation of email is always correct:
+        return $value;
+
+        // If it might be incorrect and you want to make sure that only correct values are included in response -
+        // use following line instead:
+        // return $this->parseValue($value);
+    }
+
+    /**
+     * Parses an externally provided value (query variable) to use as an input
+     *
+     * @param mixed $value
+     * @return mixed
+     */
+    public static function parseValue($value)
+    {
+        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
+            throw new \UnexpectedValueException("Cannot represent value as email: " . Utils::printSafe($value));
+        }
+        return $value;
+    }
+
+    /**
+     * Parses an externally provided literal value (hardcoded in GraphQL query) to use as an input
+     *
+     * @param \GraphQL\Language\AST\Node $valueNode
+     * @return string
+     * @throws Error
+     */
+    public static function parseLiteral($valueNode)
+    {
+        // Note: throwing GraphQL\Error\Error vs \UnexpectedValueException to benefit from GraphQL
+        // error location in query:
+        if (!$valueNode instanceof StringValueNode) {
+            throw new Error('Query error: Can only parse strings got: ' . $valueNode->kind, [$valueNode]);
+        }
+        if (!filter_var($valueNode->value, FILTER_VALIDATE_EMAIL)) {
+            throw new Error("Not a valid email", [$valueNode]);
+        }
+        return $valueNode->value;
+    }
+}

examples/01-blog/Blog/Type/Scalar/UrlType.php

@@ -0,0 +1,63 @@
+<?php
+namespace GraphQL\Examples\Blog\Type\Scalar;
+
+use GraphQL\Error\Error;
+use GraphQL\Language\AST\Node;
+use GraphQL\Language\AST\StringValueNode;
+use GraphQL\Type\Definition\ScalarType;
+use GraphQL\Utils\Utils;
+
+class UrlType extends ScalarType
+{
+    /**
+     * Serializes an internal value to include in a response.
+     *
+     * @param mixed $value
+     * @return mixed
+     */
+    public function serialize($value)
+    {
+        // Assuming internal representation of url is always correct:
+        return $value;
+
+        // If it might be incorrect and you want to make sure that only correct values are included in response -
+        // use following line instead:
+        // return $this->parseValue($value);
+    }
+
+    /**
+     * Parses an externally provided value (query variable) to use as an input
+     *
+     * @param mixed $value
+     * @return mixed
+     * @throws Error
+     */
+    public function parseValue($value)
+    {
+        if (!is_string($value) || !filter_var($value, FILTER_VALIDATE_URL)) { // quite naive, but after all this is example
+            throw new Error("Cannot represent value as URL: " . Utils::printSafe($value));
+        }
+        return $value;
+    }
+
+    /**
+     * Parses an externally provided literal value to use as an input (e.g. in Query AST)
+     *
+     * @param Node $valueNode
+     * @param array|null $variables
+     * @return null|string
+     * @throws Error
+     */
+    public function parseLiteral($valueNode, array $variables = null)
+    {
+        // Note: throwing GraphQL\Error\Error vs \UnexpectedValueException to benefit from GraphQL
+        // error location in query:
+        if (!($valueNode instanceof StringValueNode)) {
+            throw new Error('Query error: Can only parse strings got: ' . $valueNode->kind, [$valueNode]);
+        }
+        if (!is_string($valueNode->value) || !filter_var($valueNode->value, FILTER_VALIDATE_URL)) {
+            throw new Error('Query error: Not a valid URL', [$valueNode]);
+        }
+        return $valueNode->value;
+    }
+}

examples/01-blog/Blog/Type/SearchResultType.php

@@ -0,0 +1,31 @@
+<?php
+namespace GraphQL\Examples\Blog\Type;
+
+use GraphQL\Examples\Blog\Data\Story;
+use GraphQL\Examples\Blog\Data\User;
+use GraphQL\Examples\Blog\Types;
+use GraphQL\Type\Definition\UnionType;
+
+class SearchResultType extends UnionType
+{
+    public function __construct()
+    {
+        $config = [
+            'name' => 'SearchResultType',
+            'types' => function() {
+                return [
+                    Types::story(),
+                    Types::user()
+                ];
+            },
+            'resolveType' => function($value) {
+                if ($value instanceof Story) {
+                    return Types::story();
+                } else if ($value instanceof User) {
+                    return Types::user();
+                }
+            }
+        ];
+        parent::__construct($config);
+    }
+}

examples/01-blog/Blog/Type/StoryType.php

@@ -0,0 +1,127 @@
+<?php
+namespace GraphQL\Examples\Blog\Type;
+
+use GraphQL\Examples\Blog\AppContext;
+use GraphQL\Examples\Blog\Data\DataSource;
+use GraphQL\Examples\Blog\Data\Story;
+use GraphQL\Examples\Blog\Types;
+use GraphQL\Type\Definition\EnumType;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\ResolveInfo;
+
+/**
+ * Class StoryType
+ * @package GraphQL\Examples\Social\Type
+ */
+class StoryType extends ObjectType
+{
+    const EDIT = 'EDIT';
+    const DELETE = 'DELETE';
+    const LIKE = 'LIKE';
+    const UNLIKE = 'UNLIKE';
+    const REPLY = 'REPLY';
+
+    public function __construct()
+    {
+        $config = [
+            'name' => 'Story',
+            'fields' => function() {
+                return [
+                    'id' => Types::id(),
+                    'author' => Types::user(),
+                    'mentions' => Types::listOf(Types::mention()),
+                    'totalCommentCount' => Types::int(),
+                    'comments' => [
+                        'type' => Types::listOf(Types::comment()),
+                        'args' => [
+                            'after' => [
+                                'type' => Types::id(),
+                                'description' => 'Load all comments listed after given comment ID'
+                            ],
+                            'limit' => [
+                                'type' => Types::int(),
+                                'defaultValue' => 5
+                            ]
+                        ]
+                    ],
+                    'likes' => [
+                        'type' => Types::listOf(Types::user()),
+                        'args' => [
+                            'limit' => [
+                                'type' => Types::int(),
+                                'description' => 'Limit the number of recent likes returned',
+                                'defaultValue' => 5
+                            ]
+                        ]
+                    ],
+                    'likedBy' => [
+                        'type' => Types::listOf(Types::user()),
+                    ],
+                    'affordances' => Types::listOf(new EnumType([
+                        'name' => 'StoryAffordancesEnum',
+                        'values' => [
+                            self::EDIT,
+                            self::DELETE,
+                            self::LIKE,
+                            self::UNLIKE,
+                            self::REPLY
+                        ]
+                    ])),
+                    'hasViewerLiked' => Types::boolean(),
+
+                    Types::htmlField('body'),
+                ];
+            },
+            'interfaces' => [
+                Types::node()
+            ],
+            'resolveField' => function($story, $args, $context, ResolveInfo $info) {
+                $method = 'resolve' . ucfirst($info->fieldName);
+                if (method_exists($this, $method)) {
+                    return $this->{$method}($story, $args, $context, $info);
+                } else {
+                    return $story->{$info->fieldName};
+                }
+            }
+        ];
+        parent::__construct($config);
+    }
+
+    public function resolveAuthor(Story $story)
+    {
+        return DataSource::findUser($story->authorId);
+    }
+
+    public function resolveAffordances(Story $story, $args, AppContext $context)
+    {
+        $isViewer = $context->viewer === DataSource::findUser($story->authorId);
+        $isLiked = DataSource::isLikedBy($story->id, $context->viewer->id);
+
+        if ($isViewer) {
+            $affordances[] = self::EDIT;
+            $affordances[] = self::DELETE;
+        }
+        if ($isLiked) {
+            $affordances[] = self::UNLIKE;
+        } else {
+            $affordances[] = self::LIKE;
+        }
+        return $affordances;
+    }
+
+    public function resolveHasViewerLiked(Story $story, $args, AppContext $context)
+    {
+        return DataSource::isLikedBy($story->id, $context->viewer->id);
+    }
+
+    public function resolveTotalCommentCount(Story $story)
+    {
+        return DataSource::countComments($story->id);
+    }
+
+    public function resolveComments(Story $story, $args)
+    {
+        $args += ['after' => null];
+        return DataSource::findComments($story->id, $args['limit'], $args['after']);
+    }
+}

examples/01-blog/Blog/Type/UserType.php

@@ -0,0 +1,68 @@
+<?php
+namespace GraphQL\Examples\Blog\Type;
+
+use GraphQL\Examples\Blog\AppContext;
+use GraphQL\Examples\Blog\Data\DataSource;
+use GraphQL\Examples\Blog\Data\User;
+use GraphQL\Examples\Blog\Types;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\ResolveInfo;
+
+class UserType extends ObjectType
+{
+    public function __construct()
+    {
+        $config = [
+            'name' => 'User',
+            'description' => 'Our blog authors',
+            'fields' => function() {
+                return [
+                    'id' => Types::id(),
+                    'email' => Types::email(),
+                    'photo' => [
+                        'type' => Types::image(),
+                        'description' => 'User photo URL',
+                        'args' => [
+                            'size' => Types::nonNull(Types::imageSizeEnum()),
+                        ]
+                    ],
+                    'firstName' => [
+                        'type' => Types::string(),
+                    ],
+                    'lastName' => [
+                        'type' => Types::string(),
+                    ],
+                    'lastStoryPosted' => Types::story(),
+                    'fieldWithError' => [
+                        'type' => Types::string(),
+                        'resolve' => function() {
+                            throw new \Exception("This is error field");
+                        }
+                    ]
+                ];
+            },
+            'interfaces' => [
+                Types::node()
+            ],
+            'resolveField' => function($user, $args, $context, ResolveInfo $info) {
+                $method = 'resolve' . ucfirst($info->fieldName);
+                if (method_exists($this, $method)) {
+                    return $this->{$method}($user, $args, $context, $info);
+                } else {
+                    return $user->{$info->fieldName};
+                }
+            }
+        ];
+        parent::__construct($config);
+    }
+
+    public function resolvePhoto(User $user, $args)
+    {
+        return DataSource::getUserPhoto($user->id, $args['size']);
+    }
+
+    public function resolveLastStoryPosted(User $user)
+    {
+        return DataSource::findLastStoryFor($user->id);
+    }
+}

examples/01-blog/Blog/Types.php

@@ -0,0 +1,209 @@
+<?php
+namespace GraphQL\Examples\Blog;
+
+use GraphQL\Examples\Blog\Type\CommentType;
+use GraphQL\Examples\Blog\Type\Enum\ContentFormatEnum;
+use GraphQL\Examples\Blog\Type\Enum\ImageSizeEnumType;
+use GraphQL\Examples\Blog\Type\Field\HtmlField;
+use GraphQL\Examples\Blog\Type\SearchResultType;
+use GraphQL\Examples\Blog\Type\NodeType;
+use GraphQL\Examples\Blog\Type\QueryType;
+use GraphQL\Examples\Blog\Type\Scalar\EmailType;
+use GraphQL\Examples\Blog\Type\StoryType;
+use GraphQL\Examples\Blog\Type\Scalar\UrlType;
+use GraphQL\Examples\Blog\Type\UserType;
+use GraphQL\Examples\Blog\Type\ImageType;
+use GraphQL\Type\Definition\ListOfType;
+use GraphQL\Type\Definition\NonNull;
+use GraphQL\Type\Definition\Type;
+
+/**
+ * Class Types
+ *
+ * Acts as a registry and factory for your types.
+ *
+ * As simplistic as possible for the sake of clarity of this example.
+ * Your own may be more dynamic (or even code-generated).
+ *
+ * @package GraphQL\Examples\Blog
+ */
+class Types
+{
+    // Object types:
+    private static $user;
+    private static $story;
+    private static $comment;
+    private static $image;
+    private static $query;
+
+    /**
+     * @return UserType
+     */
+    public static function user()
+    {
+        return self::$user ?: (self::$user = new UserType());
+    }
+
+    /**
+     * @return StoryType
+     */
+    public static function story()
+    {
+        return self::$story ?: (self::$story = new StoryType());
+    }
+
+    /**
+     * @return CommentType
+     */
+    public static function comment()
+    {
+        return self::$comment ?: (self::$comment = new CommentType());
+    }
+
+    /**
+     * @return ImageType
+     */
+    public static function image()
+    {
+        return self::$image ?: (self::$image = new ImageType());
+    }
+
+    /**
+     * @return QueryType
+     */
+    public static function query()
+    {
+        return self::$query ?: (self::$query = new QueryType());
+    }
+
+
+    // Interface types
+    private static $node;
+
+    /**
+     * @return NodeType
+     */
+    public static function node()
+    {
+        return self::$node ?: (self::$node = new NodeType());
+    }
+
+
+    // Unions types:
+    private static $mention;
+
+    /**
+     * @return SearchResultType
+     */
+    public static function mention()
+    {
+        return self::$mention ?: (self::$mention = new SearchResultType());
+    }
+
+
+    // Enum types
+    private static $imageSizeEnum;
+    private static $contentFormatEnum;
+
+    /**
+     * @return ImageSizeEnumType
+     */
+    public static function imageSizeEnum()
+    {
+        return self::$imageSizeEnum ?: (self::$imageSizeEnum = new ImageSizeEnumType());
+    }
+
+    /**
+     * @return ContentFormatEnum
+     */
+    public static function contentFormatEnum()
+    {
+        return self::$contentFormatEnum ?: (self::$contentFormatEnum = new ContentFormatEnum());
+    }
+
+    // Custom Scalar types:
+    private static $urlType;
+    private static $emailType;
+
+    public static function email()
+    {
+        return self::$emailType ?: (self::$emailType = EmailType::create());
+    }
+
+    /**
+     * @return UrlType
+     */
+    public static function url()
+    {
+        return self::$urlType ?: (self::$urlType = new UrlType());
+    }
+
+    /**
+     * @param $name
+     * @param null $objectKey
+     * @return array
+     */
+    public static function htmlField($name, $objectKey = null)
+    {
+        return HtmlField::build($name, $objectKey);
+    }
+
+
+
+    // Let's add internal types as well for consistent experience
+
+    public static function boolean()
+    {
+        return Type::boolean();
+    }
+
+    /**
+     * @return \GraphQL\Type\Definition\FloatType
+     */
+    public static function float()
+    {
+        return Type::float();
+    }
+
+    /**
+     * @return \GraphQL\Type\Definition\IDType
+     */
+    public static function id()
+    {
+        return Type::id();
+    }
+
+    /**
+     * @return \GraphQL\Type\Definition\IntType
+     */
+    public static function int()
+    {
+        return Type::int();
+    }
+
+    /**
+     * @return \GraphQL\Type\Definition\StringType
+     */
+    public static function string()
+    {
+        return Type::string();
+    }
+
+    /**
+     * @param Type $type
+     * @return ListOfType
+     */
+    public static function listOf($type)
+    {
+        return new ListOfType($type);
+    }
+
+    /**
+     * @param Type $type
+     * @return NonNull
+     */
+    public static function nonNull($type)
+    {
+        return new NonNull($type);
+    }
+}

examples/01-blog/README.md

@@ -0,0 +1,120 @@
+## Blog Example
+Simple yet full-featured example of GraphQL API. Models blogging platform with Stories, Users
+and hierarchical comments. 
+
+### Run locally
+```
+php -S localhost:8080 ./graphql.php
+```
+
+### Test if GraphQL is running
+If you open `http://localhost:8080` in browser you should see `json` response with 
+following message:
+```
+{
+  data: {
+    hello: "Your GraphQL endpoint is ready! Install GraphiQL to browse API"
+  }
+}
+```
+
+Note that some browsers may try to download JSON file instead of showing you the response.
+In this case try to install browser plugin that adds JSON support (like JSONView or similar)
+
+### Debugging Mode
+By default GraphQL endpoint exposed at `http://localhost:8080` runs in production mode without 
+additional debugging tools enabled.
+
+In order to enable debugging mode with additional validation, error handling and reporting - 
+use `http://localhost:8080?debug=1` as endpoint
+
+### Browsing API
+The most convenient way to browse GraphQL API is by using [GraphiQL](https://github.com/graphql/graphiql)
+But setting it up from scratch may be inconvenient. An easy alternative is to use one of 
+the existing Google Chrome extensions:
+- [ChromeiQL](https://chrome.google.com/webstore/detail/chromeiql/fkkiamalmpiidkljmicmjfbieiclmeij)
+- [GraphiQL Feen](https://chrome.google.com/webstore/detail/graphiql-feen/mcbfdonlkfpbfdpimkjilhdneikhfklp)
+
+Set `http://localhost:8080?debug=1` as your GraphQL endpoint/server in one of these extensions 
+and try clicking "Docs" button (usually in the top-right corner) to browse auto-generated 
+documentation.
+
+### Running GraphQL queries
+Copy following query to GraphiQL and execute (by clicking play button on top bar)
+
+```
+{
+  viewer {
+    id
+    email
+  }
+  user(id: "2") {
+    id
+    email
+  }
+  stories(after: "1") {
+    id
+    body
+    comments {
+      ...CommentView
+    }
+  }
+  lastStoryPosted {
+    id
+    hasViewerLiked
+   
+    author {
+      id
+      photo(size: ICON) {
+        id
+        url
+        type
+        size
+        width
+        height
+        # Uncomment following line to see validation error:
+        # nonExistingField
+        
+        # Uncomment to see error reporting for fields with exceptions thrown in resolvers
+        # fieldWithError
+        # nonNullFieldWithError
+      }
+      lastStoryPosted {
+        id
+      }
+    }
+    body(format: HTML, maxLength: 10)
+  }
+}
+
+fragment CommentView on Comment {
+  id
+  body
+  totalReplyCount
+  replies {
+    id
+    body
+  }
+}
+```
+
+### Run your own query
+Use GraphiQL autocomplete (via CTRL+space) to easily create your own query.
+
+Note: GraphQL query requires at least one field per object type (to prevent accidental overfetching).
+For example following query is invalid in GraphQL:
+
+```
+{
+    viewer
+}
+```
+
+Try copying this query and see what happens
+
+### Run mutation query
+TODOC
+
+### Dig into source code
+Now when you tried GraphQL API as a consumer, see how it is implemented by browsing
+source code.

examples/01-blog/graphql.php

@@ -0,0 +1,71 @@
+<?php
+// Test this using following command
+// php -S localhost:8080 ./graphql.php
+require_once __DIR__ . '/../../vendor/autoload.php';
+
+use \GraphQL\Examples\Blog\Types;
+use \GraphQL\Examples\Blog\AppContext;
+use \GraphQL\Examples\Blog\Data\DataSource;
+use \GraphQL\Type\Schema;
+use \GraphQL\GraphQL;
+use \GraphQL\Error\FormattedError;
+use \GraphQL\Error\Debug;
+
+// Disable default PHP error reporting - we have better one for debug mode (see bellow)
+ini_set('display_errors', 0);
+
+$debug = false;
+if (!empty($_GET['debug'])) {
+    set_error_handler(function($severity, $message, $file, $line) use (&$phpErrors) {
+        throw new ErrorException($message, 0, $severity, $file, $line);
+    });
+    $debug = Debug::INCLUDE_DEBUG_MESSAGE | Debug::INCLUDE_TRACE;
+}
+
+try {
+    // Initialize our fake data source
+    DataSource::init();
+
+    // Prepare context that will be available in all field resolvers (as 3rd argument):
+    $appContext = new AppContext();
+    $appContext->viewer = DataSource::findUser('1'); // simulated "currently logged-in user"
+    $appContext->rootUrl = 'http://localhost:8080';
+    $appContext->request = $_REQUEST;
+
+    // Parse incoming query and variables
+    if (isset($_SERVER['CONTENT_TYPE']) && strpos($_SERVER['CONTENT_TYPE'], 'application/json') !== false) {
+        $raw = file_get_contents('php://input') ?: '';
+        $data = json_decode($raw, true) ?: [];
+    } else {
+        $data = $_REQUEST;
+    }
+    
+    $data += ['query' => null, 'variables' => null];
+
+    if (null === $data['query']) {
+        $data['query'] = '{hello}';
+    }
+
+    // GraphQL schema to be passed to query executor:
+    $schema = new Schema([
+        'query' => Types::query()
+    ]);
+
+    $result = GraphQL::executeQuery(
+        $schema,
+        $data['query'],
+        null,
+        $appContext,
+        (array) $data['variables']
+    );
+    $output = $result->toArray($debug);
+    $httpStatus = 200;
+} catch (\Exception $error) {
+    $httpStatus = 500;
+    $output['errors'] = [
+        FormattedError::createFromException($error, $debug)
+    ];
+}
+
+header('Content-Type: application/json', true, $httpStatus);
+echo json_encode($output);

examples/02-shorthand/README.md

@@ -0,0 +1,19 @@
+# Parsing GraphQL IDL shorthand
+
+Same as the Hello world example but shows how to build GraphQL schema from shorthand 
+and wire up some resolvers
+
+### Run locally
+```
+php -S localhost:8080 ./graphql.php
+```
+
+### Try query
+```
+curl http://localhost:8080 -d '{"query": "query { echo(message: \"Hello World\") }" }'
+```
+
+### Try mutation
+```
+curl http://localhost:8080 -d '{"query": "mutation { sum(x: 2, y: 2) }" }'
+```

examples/02-shorthand/graphql.php

@@ -0,0 +1,31 @@
+<?php
+// Test this using following command
+// php -S localhost:8080 ./graphql.php &
+// curl http://localhost:8080 -d '{"query": "query { echo(message: \"Hello World\") }" }'
+// curl http://localhost:8080 -d '{"query": "mutation { sum(x: 2, y: 2) }" }'
+require_once __DIR__ . '/../../vendor/autoload.php';
+
+use GraphQL\GraphQL;
+use GraphQL\Utils\BuildSchema;
+
+try {
+
+    $schema = BuildSchema::build(file_get_contents(__DIR__ . '/schema.graphqls'));
+    $rootValue = include __DIR__ . '/rootvalue.php';
+
+    $rawInput = file_get_contents('php://input');
+    $input = json_decode($rawInput, true);
+    $query = $input['query'];
+    $variableValues = isset($input['variables']) ? $input['variables'] : null;
+
+    $result = GraphQL::executeQuery($schema, $query, $rootValue, null, $variableValues);
+} catch (\Exception $e) {
+    $result = [
+        'error' => [
+            'message' => $e->getMessage()
+        ]
+    ];
+}
+header('Content-Type: application/json; charset=UTF-8');
+echo json_encode($result);
+

examples/02-shorthand/rootvalue.php

@@ -0,0 +1,35 @@
+<?php
+
+interface Resolver {
+    public function resolve($rootValue, $args, $context);
+}
+
+class Addition implements Resolver
+{
+    public function resolve($rootValue, $args, $context)
+    {
+        return $args['x'] + $args['y'];
+    }
+}
+
+class Echoer implements Resolver
+{
+    public function resolve($rootValue, $args, $context)
+    {
+        return $rootValue['prefix'].$args['message'];
+    }
+}
+
+return [
+    'sum' => function($rootValue, $args, $context) {
+        $sum = new Addition();
+
+        return $sum->resolve($rootValue, $args, $context);
+    },
+    'echo' => function($rootValue, $args, $context) {
+        $echo = new Echoer();
+
+        return $echo->resolve($rootValue, $args, $context);
+    },
+    'prefix' => 'You said: ',
+];

examples/02-shorthand/schema.graphqls

@@ -0,0 +1,13 @@
+schema {
+  query: Query
+  mutation: Calc
+}
+
+type Calc {
+  sum(x: Int, y: Int): Int
+}
+
+type Query {
+  echo(message: String): String
+}
+

examples/03-server/README.md

@@ -0,0 +1,19 @@
+# Hello world
+Same example as 01-hello-world, but uses 
+[Standard Http Server](http://webonyx.github.io/graphql-php/executing-queries/#using-server)
+instead of manual parsing of incoming data.
+
+### Run locally
+```
+php -S localhost:8080 ./graphql.php
+```
+
+### Try query
+```
+curl -d '{"query": "query { echo(message: \"Hello World\") }" }' -H "Content-Type: application/json" http://localhost:8080
+```
+
+### Try mutation
+```
+curl -d '{"query": "mutation { sum(x: 2, y: 2) }" }' -H "Content-Type: application/json" http://localhost:8080
+```

examples/03-server/graphql.php

@@ -0,0 +1,61 @@
+<?php
+// Test this using following command
+// php -S localhost:8080 ./graphql.php &
+// curl http://localhost:8080 -d '{"query": "query { echo(message: \"Hello World\") }" }'
+// curl http://localhost:8080 -d '{"query": "mutation { sum(x: 2, y: 2) }" }'
+require_once __DIR__ . '/../../vendor/autoload.php';
+
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Schema;
+use GraphQL\Server\StandardServer;
+
+try {
+    $queryType = new ObjectType([
+        'name' => 'Query',
+        'fields' => [
+            'echo' => [
+                'type' => Type::string(),
+                'args' => [
+                    'message' => ['type' => Type::string()],
+                ],
+                'resolve' => function ($rootValue, $args) {
+                    return $rootValue['prefix'] . $args['message'];
+                }
+            ],
+        ],
+    ]);
+
+    $mutationType = new ObjectType([
+        'name' => 'Calc',
+        'fields' => [
+            'sum' => [
+                'type' => Type::int(),
+                'args' => [
+                    'x' => ['type' => Type::int()],
+                    'y' => ['type' => Type::int()],
+                ],
+                'resolve' => function ($calc, $args) {
+                    return $args['x'] + $args['y'];
+                },
+            ],
+        ],
+    ]);
+
+    // See docs on schema options:
+    // http://webonyx.github.io/graphql-php/type-system/schema/#configuration-options
+    $schema = new Schema([
+        'query' => $queryType,
+        'mutation' => $mutationType,
+    ]);
+
+    // See docs on server options:
+    // http://webonyx.github.io/graphql-php/executing-queries/#server-configuration-options
+    $server = new StandardServer([
+        'schema' => $schema
+    ]);
+
+    $server->handleRequest();
+} catch (\Exception $e) {
+    StandardServer::send500Error($e);
+}

mkdocs.yml

@@ -0,0 +1,26 @@
+site_name: graphql-php
+pages:
+- About: index.md
+- Getting Started: getting-started.md
+- Complementary Tools: complementary-tools.md
+- Type Definitions:
+  - Introduction: type-system/index.md
+  - Object Types: type-system/object-types.md
+  - Scalar Types: type-system/scalar-types.md
+  - Enumeration Types: type-system/enum-types.md
+  - Lists and Non-Null: type-system/lists-and-nonnulls.md
+  - Interfaces: type-system/interfaces.md
+  - Unions: type-system/unions.md
+  - Mutations and Input Types: type-system/input-types.md
+  - Directives: type-system/directives.md
+  - Schema: type-system/schema.md
+  - Using Type Language: type-system/type-language.md
+- Executing Queries: executing-queries.md
+- Fetching Data: data-fetching.md
+- Handling Errors: error-handling.md
+# - Mutations: mutations.md
+- Security: security.md
+# - Performance tips: performance.md
+- How it works: how-it-works.md
+- Class Reference: reference.md
+theme: readthedocs

phpbench.json

@@ -0,0 +1,6 @@
+{
+  "bootstrap": "vendor/autoload.php",
+  "path": "benchmarks",
+  "retry_threshold": 5,
+  "time_unit": "milliseconds"
+}

phpcs.xml.dist

@@ -0,0 +1,102 @@
+<?xml version="1.0"?>
+<ruleset>
+    <arg name="basepath" value="." />
+    <arg name="extensions" value="php" />
+    <arg name="parallel" value="80" />
+    <arg name="cache" value=".phpcs-cache" />
+    <arg name="colors" />
+
+    <!-- Ignore warnings, show progress of the run and show sniff names -->
+    <arg value="nps" />
+
+    <file>src</file>
+    <file>tests</file>
+
+    <rule ref="Doctrine">
+        <!-- Disable PHP7+ features that might cause BC breaks for now -->
+        <exclude name="SlevomatCodingStandard.Classes.ClassConstantVisibility.MissingConstantVisibility" />
+        <exclude name="SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingParameterTypeHint" />
+        <exclude name="SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingReturnTypeHint" />
+        <!-- Enable when Slevomat starts supporting variadics, see https://github.com/slevomat/coding-standard/issues/251 -->
+        <exclude name="SlevomatCodingStandard.Namespaces.UnusedUses.UnusedUse" />
+    </rule>
+
+    <!--@api annotation is required for now -->
+    <rule ref="SlevomatCodingStandard.TypeHints.TypeHintDeclaration">
+        <properties>
+            <property
+                    name="usefulAnnotations"
+                    type="array"
+                    value="
+                    @after,
+                    @afterClass,
+                    @AfterMethods,
+                    @api,
+                    @Attribute,
+                    @Attributes,
+                    @before,
+                    @beforeClass,
+                    @BeforeMethods,
+                    @covers,
+                    @coversDefaultClass,
+                    @coversNothing,
+                    @dataProvider,
+                    @depends,
+                    @deprecated,
+                    @doesNotPerformAssertions,
+                    @Enum,
+                    @expectedDeprecation,
+                    @expectedException,
+                    @expectedExceptionCode,
+                    @expectedExceptionMessage,
+                    @expectedExceptionMessageRegExp,
+                    @group,
+                    @Groups,
+                    @IgnoreAnnotation,
+                    @internal,
+                    @Iterations,
+                    @link,
+                    @ODM\,
+                    @ORM\,
+                    @requires,
+                    @Required,
+                    @Revs,
+                    @runInSeparateProcess,
+                    @runTestsInSeparateProcesses,
+                    @see,
+                    @Target,
+                    @test,
+                    @throws,
+                    @uses
+                "
+            />
+        </properties>
+    </rule>
+
+    <rule ref="SlevomatCodingStandard.Commenting.ForbiddenAnnotations">
+        <properties>
+            <property
+                    name="forbiddenAnnotations"
+                    type="array"
+                    value="
+                    @author,
+                    @category,
+                    @copyright,
+                    @created,
+                    @license,
+                    @package,
+                    @since,
+                    @subpackage,
+                    @version
+                "
+            />
+        </properties>
+    </rule>
+
+    <!-- IDEs sort by PSR12, Slevomat coding standard uses old sorting for BC -->
+    <rule ref="SlevomatCodingStandard.Namespaces.AlphabeticallySortedUses">
+        <properties>
+            <property name="psr12Compatible" type="bool" value="true" />
+        </properties>
+    </rule>
+</ruleset>

phpstan.neon.dist

@@ -0,0 +1,17 @@
+parameters:
+    level: 1
+
+    paths:
+        - %currentWorkingDirectory%/src
+        - %currentWorkingDirectory%/tests
+
+    ignoreErrors:
+        - "~Construct empty\\(\\) is not allowed\\. Use more strict comparison~"
+        - "~(Method|Property) .+::.+(\\(\\))? (has parameter \\$\\w+ with no|has no return|has no) typehint specified~"
+        - "~Variable property access on .+~"
+        - "~Variable method call on static\\(GraphQL\\\\Server\\\\ServerConfig\\)~" # TODO get rid of
+
+includes:
+	- vendor/phpstan/phpstan-phpunit/extension.neon
+	- vendor/phpstan/phpstan-phpunit/rules.neon
+	- vendor/phpstan/phpstan-strict-rules/rules.neon

phpunit.xml.dist

@@ -1,34 +1,28 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="utf-8"?>
+<phpunit
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+        bootstrap="tests/bootstrap.php"
+>
+    <php>
+        <ini name="error_reporting" value="E_ALL"/>
+    </php>
 
-<phpunit backupGlobals="false"
-         backupStaticAttributes="false"
-         colors="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         processIsolation="false"
-         stopOnFailure="false"
-         syntaxCheck="false"
-         bootstrap="vendor/autoload.php"
-        >
     <testsuites>
         <testsuite name="webonyx/graphql-php Test Suite">
             <directory>./tests/</directory>
         </testsuite>
     </testsuites>
 
+    <groups>
+        <exclude>
+            <group>ReactPromise</group>
+        </exclude>
+    </groups>
+
     <filter>
         <whitelist>
-            <directory>./</directory>
-            <exclude>
-                <directory>./tests</directory>
-                <directory>./vendor</directory>
-            </exclude>
+            <directory suffix=".php">./src</directory>
         </whitelist>
     </filter>
-
-    <php>
-        <ini name="error_reporting" value="E_ALL"/>
-    </php>
-
 </phpunit>

src/Deferred.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL;
+
+use Exception;
+use GraphQL\Executor\Promise\Adapter\SyncPromise;
+use SplQueue;
+use Throwable;
+
+class Deferred
+{
+    /** @var SplQueue|null */
+    private static $queue;
+
+    /** @var callable */
+    private $callback;
+
+    /** @var SyncPromise */
+    public $promise;
+
+    public function __construct(callable $callback)
+    {
+        $this->callback = $callback;
+        $this->promise  = new SyncPromise();
+        self::getQueue()->enqueue($this);
+    }
+
+    public static function getQueue() : SplQueue
+    {
+        if (self::$queue === null) {
+            self::$queue = new SplQueue();
+        }
+
+        return self::$queue;
+    }
+
+    public static function runQueue() : void
+    {
+        $queue = self::getQueue();
+        while (! $queue->isEmpty()) {
+            /** @var self $dequeuedNodeValue */
+            $dequeuedNodeValue = $queue->dequeue();
+            $dequeuedNodeValue->run();
+        }
+    }
+
+    public function then($onFulfilled = null, $onRejected = null)
+    {
+        return $this->promise->then($onFulfilled, $onRejected);
+    }
+
+    public function run() : void
+    {
+        try {
+            $cb = $this->callback;
+            $this->promise->resolve($cb());
+        } catch (Exception $e) {
+            $this->promise->reject($e);
+        } catch (Throwable $e) {
+            $this->promise->reject($e);
+        }
+    }
+}

src/Error.php

@@ -1,132 +0,0 @@
-<?php
-namespace GraphQL;
-
-use GraphQL\Language\Source;
-
-// /graphql-js/src/error/GraphQLError.js
-
-class Error extends \Exception
-{
-    /**
-     * @var string
-     */
-    public $message;
-
-    /**
-     * @var array
-     */
-    public $nodes;
-
-    /**
-     * @var array
-     */
-    private $positions;
-
-    /**
-     * @var array<SourceLocation>
-     */
-    private $locations;
-
-    /**
-     * @var Source|null
-     */
-    private $source;
-
-    /**
-     * Given an arbitrary Error, presumably thrown while attempting to execute a
-     * GraphQL operation, produce a new GraphQLError aware of the location in the
-     * document responsible for the original Error.
-     *
-     * @param $error
-     * @param array|null $nodes
-     * @return Error
-     */
-    public static function createLocatedError($error, $nodes = null)
-    {
-        if ($error instanceof \Exception) {
-            $message = $error->getMessage();
-            $previous = $error;
-        } else {
-            $message = (string) $error;
-            $previous = null;
-        }
-
-        return new Error($message, $nodes, $previous);
-    }
-
-    /**
-     * @param Error $error
-     * @return array
-     */
-    public static function formatError(Error $error)
-    {
-        return FormattedError::create($error->getMessage(), $error->getLocations());
-    }
-
-    /**
-     * @param string|\Exception $message
-     * @param array|null $nodes
-     * @param Source $source
-     * @param null $positions
-     */
-    public function __construct($message, $nodes = null, \Exception $previous = null, Source $source = null, $positions = null)
-    {
-        parent::__construct($message, 0, $previous);
-
-        if ($nodes instanceof \Traversable) {
-            $nodes = iterator_to_array($nodes);
-        }
-
-        $this->nodes = $nodes;
-        $this->source = $source;
-        $this->positions = $positions;
-    }
-
-    /**
-     * @return Source|null
-     */
-    public function getSource()
-    {
-        if (null === $this->source) {
-            if (!empty($this->nodes[0]) && !empty($this->nodes[0]->loc)) {
-                $this->source = $this->nodes[0]->loc->source;
-            }
-        }
-        return $this->source;
-    }
-
-    /**
-     * @return array
-     */
-    public function getPositions()
-    {
-        if (null === $this->positions) {
-            if (!empty($this->nodes)) {
-                $positions = array_map(function($node) { return isset($node->loc) ? $node->loc->start : null; }, $this->nodes);
-                $this->positions = array_filter($positions);
-            }
-        }
-        return $this->positions;
-    }
-
-    /**
-     * @return array<SourceLocation>
-     */
-    public function getLocations()
-    {
-        if (null === $this->locations) {
-            $positions = $this->getPositions();
-            $source = $this->getSource();
-
-            if ($positions && $source) {
-                $this->locations = array_map(function ($pos) use ($source) {
-                    return $source->getLocation($pos);
-                }, $positions);
-            } else {
-                $this->locations = [];
-            }
-        }
-
-        return $this->locations;
-    }
-}

src/Error/ClientAware.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Error;
+
+/**
+ * This interface is used for [default error formatting](error-handling.md).
+ *
+ * Only errors implementing this interface (and returning true from `isClientSafe()`)
+ * will be formatted with original error message.
+ *
+ * All other errors will be formatted with generic "Internal server error".
+ */
+interface ClientAware
+{
+    /**
+     * Returns true when exception message is safe to be displayed to a client.
+     *
+     * @return bool
+     *
+     * @api
+     */
+    public function isClientSafe();
+
+    /**
+     * Returns string describing a category of the error.
+     *
+     * Value "graphql" is reserved for errors produced by query parsing or validation, do not use it.
+     *
+     * @return string
+     *
+     * @api
+     */
+    public function getCategory();
+}

src/Error/Debug.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Error;
+
+/**
+ * Collection of flags for [error debugging](error-handling.md#debugging-tools).
+ */
+class Debug
+{
+    const INCLUDE_DEBUG_MESSAGE       = 1;
+    const INCLUDE_TRACE               = 2;
+    const RETHROW_INTERNAL_EXCEPTIONS = 4;
+    const RETHROW_UNSAFE_EXCEPTIONS   = 8;
+}

src/Error/Error.php

@@ -0,0 +1,380 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Error;
+
+use Exception;
+use GraphQL\Language\AST\Node;
+use GraphQL\Language\Source;
+use GraphQL\Language\SourceLocation;
+use GraphQL\Utils\Utils;
+use JsonSerializable;
+use Throwable;
+use Traversable;
+use function array_filter;
+use function array_map;
+use function array_values;
+use function is_array;
+use function iterator_to_array;
+
+/**
+ * Describes an Error found during the parse, validate, or
+ * execute phases of performing a GraphQL operation. In addition to a message
+ * and stack trace, it also includes information about the locations in a
+ * GraphQL document and/or execution result that correspond to the Error.
+ *
+ * When the error was caused by an exception thrown in resolver, original exception
+ * is available via `getPrevious()`.
+ *
+ * Also read related docs on [error handling](error-handling.md)
+ *
+ * Class extends standard PHP `\Exception`, so all standard methods of base `\Exception` class
+ * are available in addition to those listed below.
+ */
+class Error extends Exception implements JsonSerializable, ClientAware
+{
+    const CATEGORY_GRAPHQL  = 'graphql';
+    const CATEGORY_INTERNAL = 'internal';
+
+    /**
+     * A message describing the Error for debugging purposes.
+     *
+     * @var string
+     */
+    public $message;
+
+    /** @var SourceLocation[] */
+    private $locations;
+
+    /**
+     * An array describing the JSON-path into the execution response which
+     * corresponds to this error. Only included for errors during execution.
+     *
+     * @var mixed[]|null
+     */
+    public $path;
+
+    /**
+     * An array of GraphQL AST Nodes corresponding to this error.
+     *
+     * @var Node[]|null
+     */
+    public $nodes;
+
+    /**
+     * The source GraphQL document for the first location of this error.
+     *
+     * Note that if this Error represents more than one node, the source may not
+     * represent nodes after the first node.
+     *
+     * @var Source|null
+     */
+    private $source;
+
+    /** @var int[]|null */
+    private $positions;
+
+    /** @var bool */
+    private $isClientSafe;
+
+    /** @var string */
+    protected $category;
+
+    /** @var mixed[]|null */
+    protected $extensions;
+
+    /**
+     * @param string                       $message
+     * @param Node|Node[]|Traversable|null $nodes
+     * @param mixed[]|null                 $positions
+     * @param mixed[]|null                 $path
+     * @param Throwable                    $previous
+     * @param mixed[]                      $extensions
+     */
+    public function __construct(
+        $message,
+        $nodes = null,
+        ?Source $source = null,
+        $positions = null,
+        $path = null,
+        $previous = null,
+        array $extensions = []
+    ) {
+        parent::__construct($message, 0, $previous);
+
+        // Compute list of blame nodes.
+        if ($nodes instanceof Traversable) {
+            $nodes = iterator_to_array($nodes);
+        } elseif ($nodes && ! is_array($nodes)) {
+            $nodes = [$nodes];
+        }
+
+        $this->nodes      = $nodes;
+        $this->source     = $source;
+        $this->positions  = $positions;
+        $this->path       = $path;
+        $this->extensions = $extensions ?: (
+        $previous && $previous instanceof self
+            ? $previous->extensions
+            : []
+        );
+
+        if ($previous instanceof ClientAware) {
+            $this->isClientSafe = $previous->isClientSafe();
+            $this->category     = $previous->getCategory() ?: self::CATEGORY_INTERNAL;
+        } elseif ($previous) {
+            $this->isClientSafe = false;
+            $this->category     = self::CATEGORY_INTERNAL;
+        } else {
+            $this->isClientSafe = true;
+            $this->category     = self::CATEGORY_GRAPHQL;
+        }
+    }
+
+    /**
+     * Given an arbitrary Error, presumably thrown while attempting to execute a
+     * GraphQL operation, produce a new GraphQLError aware of the location in the
+     * document responsible for the original Error.
+     *
+     * @param mixed        $error
+     * @param Node[]|null  $nodes
+     * @param mixed[]|null $path
+     *
+     * @return Error
+     */
+    public static function createLocatedError($error, $nodes = null, $path = null)
+    {
+        if ($error instanceof self) {
+            if ($error->path && $error->nodes) {
+                return $error;
+            }
+
+            $nodes = $nodes ?: $error->nodes;
+            $path  = $path ?: $error->path;
+        }
+
+        $source     = $positions = $originalError = null;
+        $extensions = [];
+
+        if ($error instanceof self) {
+            $message       = $error->getMessage();
+            $originalError = $error;
+            $nodes         = $error->nodes ?: $nodes;
+            $source        = $error->source;
+            $positions     = $error->positions;
+            $extensions    = $error->extensions;
+        } elseif ($error instanceof Exception || $error instanceof Throwable) {
+            $message       = $error->getMessage();
+            $originalError = $error;
+        } else {
+            $message = (string) $error;
+        }
+
+        return new static(
+            $message ?: 'An unknown error occurred.',
+            $nodes,
+            $source,
+            $positions,
+            $path,
+            $originalError,
+            $extensions
+        );
+    }
+
+    /**
+     * @return mixed[]
+     */
+    public static function formatError(Error $error)
+    {
+        return $error->toSerializableArray();
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function isClientSafe()
+    {
+        return $this->isClientSafe;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getCategory()
+    {
+        return $this->category;
+    }
+
+    /**
+     * @return Source|null
+     */
+    public function getSource()
+    {
+        if ($this->source === null) {
+            if (! empty($this->nodes[0]) && ! empty($this->nodes[0]->loc)) {
+                $this->source = $this->nodes[0]->loc->source;
+            }
+        }
+
+        return $this->source;
+    }
+
+    /**
+     * @return int[]
+     */
+    public function getPositions()
+    {
+        if ($this->positions === null && ! empty($this->nodes)) {
+            $positions = array_map(
+                static function ($node) {
+                    return isset($node->loc) ? $node->loc->start : null;
+                },
+                $this->nodes
+            );
+
+            $positions = array_filter(
+                $positions,
+                static function ($p) {
+                    return $p !== null;
+                }
+            );
+
+            $this->positions = array_values($positions);
+        }
+
+        return $this->positions;
+    }
+
+    /**
+     * An array of locations within the source GraphQL document which correspond to this error.
+     *
+     * Each entry has information about `line` and `column` within source GraphQL document:
+     * $location->line;
+     * $location->column;
+     *
+     * Errors during validation often contain multiple locations, for example to
+     * point out to field mentioned in multiple fragments. Errors during execution include a
+     * single location, the field which produced the error.
+     *
+     * @return SourceLocation[]
+     *
+     * @api
+     */
+    public function getLocations()
+    {
+        if ($this->locations === null) {
+            $positions = $this->getPositions();
+            $source    = $this->getSource();
+            $nodes     = $this->nodes;
+
+            if ($positions && $source) {
+                $this->locations = array_map(
+                    static function ($pos) use ($source) {
+                        return $source->getLocation($pos);
+                    },
+                    $positions
+                );
+            } elseif ($nodes) {
+                $locations       = array_filter(
+                    array_map(
+                        static function ($node) {
+                            if ($node->loc && $node->loc->source) {
+                                return $node->loc->source->getLocation($node->loc->start);
+                            }
+                        },
+                        $nodes
+                    )
+                );
+                $this->locations = array_values($locations);
+            } else {
+                $this->locations = [];
+            }
+        }
+
+        return $this->locations;
+    }
+
+    /**
+     * @return Node[]|null
+     */
+    public function getNodes()
+    {
+        return $this->nodes;
+    }
+
+    /**
+     * Returns an array describing the path from the root value to the field which produced this error.
+     * Only included for execution errors.
+     *
+     * @return mixed[]|null
+     *
+     * @api
+     */
+    public function getPath()
+    {
+        return $this->path;
+    }
+
+    /**
+     * @return mixed[]
+     */
+    public function getExtensions()
+    {
+        return $this->extensions;
+    }
+
+    /**
+     * Returns array representation of error suitable for serialization
+     *
+     * @deprecated Use FormattedError::createFromException() instead
+     *
+     * @return mixed[]
+     */
+    public function toSerializableArray()
+    {
+        $arr = [
+            'message' => $this->getMessage(),
+        ];
+
+        $locations = Utils::map(
+            $this->getLocations(),
+            static function (SourceLocation $loc) {
+                return $loc->toSerializableArray();
+            }
+        );
+
+        if (! empty($locations)) {
+            $arr['locations'] = $locations;
+        }
+        if (! empty($this->path)) {
+            $arr['path'] = $this->path;
+        }
+        if (! empty($this->extensions)) {
+            $arr['extensions'] = $this->extensions;
+        }
+
+        return $arr;
+    }
+
+    /**
+     * Specify data which should be serialized to JSON
+     *
+     * @link http://php.net/manual/en/jsonserializable.jsonserialize.php
+     *
+     * @return mixed data which can be serialized by <b>json_encode</b>,
+     * which is a value of any type other than a resource.
+     */
+    public function jsonSerialize()
+    {
+        return $this->toSerializableArray();
+    }
+
+    /**
+     * @return string
+     */
+    public function __toString()
+    {
+        return FormattedError::printError($this);
+    }
+}

src/Error/FormattedError.php

@@ -0,0 +1,440 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Error;
+
+use Countable;
+use ErrorException;
+use Exception;
+use GraphQL\Language\AST\Node;
+use GraphQL\Language\Source;
+use GraphQL\Language\SourceLocation;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\WrappingType;
+use GraphQL\Utils\Utils;
+use Throwable;
+use function addcslashes;
+use function array_filter;
+use function array_intersect_key;
+use function array_map;
+use function array_merge;
+use function array_shift;
+use function count;
+use function get_class;
+use function gettype;
+use function implode;
+use function is_array;
+use function is_bool;
+use function is_object;
+use function is_scalar;
+use function is_string;
+use function mb_strlen;
+use function preg_split;
+use function sprintf;
+use function str_repeat;
+use function strlen;
+
+/**
+ * This class is used for [default error formatting](error-handling.md).
+ * It converts PHP exceptions to [spec-compliant errors](https://facebook.github.io/graphql/#sec-Errors)
+ * and provides tools for error debugging.
+ */
+class FormattedError
+{
+    /** @var string */
+    private static $internalErrorMessage = 'Internal server error';
+
+    /**
+     * Set default error message for internal errors formatted using createFormattedError().
+     * This value can be overridden by passing 3rd argument to `createFormattedError()`.
+     *
+     * @param string $msg
+     *
+     * @api
+     */
+    public static function setInternalErrorMessage($msg)
+    {
+        self::$internalErrorMessage = $msg;
+    }
+
+    /**
+     * Prints a GraphQLError to a string, representing useful location information
+     * about the error's position in the source.
+     *
+     * @return string
+     */
+    public static function printError(Error $error)
+    {
+        $printedLocations = [];
+        if ($error->nodes) {
+            /** @var Node $node */
+            foreach ($error->nodes as $node) {
+                if (! $node->loc) {
+                    continue;
+                }
+
+                if ($node->loc->source === null) {
+                    continue;
+                }
+
+                $printedLocations[] = self::highlightSourceAtLocation(
+                    $node->loc->source,
+                    $node->loc->source->getLocation($node->loc->start)
+                );
+            }
+        } elseif ($error->getSource() && $error->getLocations()) {
+            $source = $error->getSource();
+            foreach ($error->getLocations() as $location) {
+                $printedLocations[] = self::highlightSourceAtLocation($source, $location);
+            }
+        }
+
+        return ! $printedLocations
+            ? $error->getMessage()
+            : implode("\n\n", array_merge([$error->getMessage()], $printedLocations)) . "\n";
+    }
+
+    /**
+     * Render a helpful description of the location of the error in the GraphQL
+     * Source document.
+     *
+     * @return string
+     */
+    private static function highlightSourceAtLocation(Source $source, SourceLocation $location)
+    {
+        $line          = $location->line;
+        $lineOffset    = $source->locationOffset->line - 1;
+        $columnOffset  = self::getColumnOffset($source, $location);
+        $contextLine   = $line + $lineOffset;
+        $contextColumn = $location->column + $columnOffset;
+        $prevLineNum   = (string) ($contextLine - 1);
+        $lineNum       = (string) $contextLine;
+        $nextLineNum   = (string) ($contextLine + 1);
+        $padLen        = strlen($nextLineNum);
+        $lines         = preg_split('/\r\n|[\n\r]/', $source->body);
+
+        $lines[0] = self::whitespace($source->locationOffset->column - 1) . $lines[0];
+
+        $outputLines = [
+            sprintf('%s (%s:%s)', $source->name, $contextLine, $contextColumn),
+            $line >= 2 ? (self::lpad($padLen, $prevLineNum) . ': ' . $lines[$line - 2]) : null,
+            self::lpad($padLen, $lineNum) . ': ' . $lines[$line - 1],
+            self::whitespace(2 + $padLen + $contextColumn - 1) . '^',
+            $line < count($lines) ? self::lpad($padLen, $nextLineNum) . ': ' . $lines[$line] : null,
+        ];
+
+        return implode("\n", array_filter($outputLines));
+    }
+
+    /**
+     * @return int
+     */
+    private static function getColumnOffset(Source $source, SourceLocation $location)
+    {
+        return $location->line === 1 ? $source->locationOffset->column - 1 : 0;
+    }
+
+    /**
+     * @param int $len
+     *
+     * @return string
+     */
+    private static function whitespace($len)
+    {
+        return str_repeat(' ', $len);
+    }
+
+    /**
+     * @param int $len
+     *
+     * @return string
+     */
+    private static function lpad($len, $str)
+    {
+        return self::whitespace($len - mb_strlen($str)) . $str;
+    }
+
+    /**
+     * Standard GraphQL error formatter. Converts any exception to array
+     * conforming to GraphQL spec.
+     *
+     * This method only exposes exception message when exception implements ClientAware interface
+     * (or when debug flags are passed).
+     *
+     * For a list of available debug flags see GraphQL\Error\Debug constants.
+     *
+     * @param Throwable $e
+     * @param bool|int  $debug
+     * @param string    $internalErrorMessage
+     *
+     * @return mixed[]
+     *
+     * @throws Throwable
+     *
+     * @api
+     */
+    public static function createFromException($e, $debug = false, $internalErrorMessage = null)
+    {
+        Utils::invariant(
+            $e instanceof Exception || $e instanceof Throwable,
+            'Expected exception, got %s',
+            Utils::getVariableType($e)
+        );
+
+        $internalErrorMessage = $internalErrorMessage ?: self::$internalErrorMessage;
+
+        if ($e instanceof ClientAware) {
+            $formattedError = [
+                'message'  => $e->isClientSafe() ? $e->getMessage() : $internalErrorMessage,
+                'extensions' => [
+                    'category' => $e->getCategory(),
+                ],
+            ];
+        } else {
+            $formattedError = [
+                'message'  => $internalErrorMessage,
+                'extensions' => [
+                    'category' => Error::CATEGORY_INTERNAL,
+                ],
+            ];
+        }
+
+        if ($e instanceof Error) {
+            $locations = Utils::map(
+                $e->getLocations(),
+                static function (SourceLocation $loc) {
+                    return $loc->toSerializableArray();
+                }
+            );
+            if (! empty($locations)) {
+                $formattedError['locations'] = $locations;
+            }
+            if (! empty($e->path)) {
+                $formattedError['path'] = $e->path;
+            }
+            if (! empty($e->getExtensions())) {
+                $formattedError['extensions'] = $e->getExtensions() + $formattedError['extensions'];
+            }
+        }
+
+        if ($debug) {
+            $formattedError = self::addDebugEntries($formattedError, $e, $debug);
+        }
+
+        return $formattedError;
+    }
+
+    /**
+     * Decorates spec-compliant $formattedError with debug entries according to $debug flags
+     * (see GraphQL\Error\Debug for available flags)
+     *
+     * @param mixed[]   $formattedError
+     * @param Throwable $e
+     * @param bool|int  $debug
+     *
+     * @return mixed[]
+     *
+     * @throws Throwable
+     */
+    public static function addDebugEntries(array $formattedError, $e, $debug)
+    {
+        if (! $debug) {
+            return $formattedError;
+        }
+
+        Utils::invariant(
+            $e instanceof Exception || $e instanceof Throwable,
+            'Expected exception, got %s',
+            Utils::getVariableType($e)
+        );
+
+        $debug = (int) $debug;
+
+        if ($debug & Debug::RETHROW_INTERNAL_EXCEPTIONS) {
+            if (! $e instanceof Error) {
+                throw $e;
+            }
+
+            if ($e->getPrevious()) {
+                throw $e->getPrevious();
+            }
+        }
+
+        $isUnsafe = ! $e instanceof ClientAware || ! $e->isClientSafe();
+
+        if (($debug & Debug::RETHROW_UNSAFE_EXCEPTIONS) && $isUnsafe) {
+            if ($e->getPrevious()) {
+                throw $e->getPrevious();
+            }
+        }
+
+        if (($debug & Debug::INCLUDE_DEBUG_MESSAGE) && $isUnsafe) {
+            // Displaying debugMessage as a first entry:
+            $formattedError = ['debugMessage' => $e->getMessage()] + $formattedError;
+        }
+
+        if ($debug & Debug::INCLUDE_TRACE) {
+            if ($e instanceof ErrorException || $e instanceof \Error) {
+                $formattedError += [
+                    'file' => $e->getFile(),
+                    'line' => $e->getLine(),
+                ];
+            }
+
+            $isTrivial = $e instanceof Error && ! $e->getPrevious();
+
+            if (! $isTrivial) {
+                $debugging               = $e->getPrevious() ?: $e;
+                $formattedError['trace'] = static::toSafeTrace($debugging);
+            }
+        }
+
+        return $formattedError;
+    }
+
+    /**
+     * Prepares final error formatter taking in account $debug flags.
+     * If initial formatter is not set, FormattedError::createFromException is used
+     *
+     * @param  bool|int $debug
+     *
+     * @return callable|callable
+     */
+    public static function prepareFormatter(?callable $formatter = null, $debug)
+    {
+        $formatter = $formatter ?: static function ($e) {
+            return FormattedError::createFromException($e);
+        };
+        if ($debug) {
+            $formatter = static function ($e) use ($formatter, $debug) {
+                return FormattedError::addDebugEntries($formatter($e), $e, $debug);
+            };
+        }
+
+        return $formatter;
+    }
+
+    /**
+     * Returns error trace as serializable array
+     *
+     * @param Throwable $error
+     *
+     * @return mixed[]
+     *
+     * @api
+     */
+    public static function toSafeTrace($error)
+    {
+        $trace = $error->getTrace();
+
+        if (isset($trace[0]['function']) && isset($trace[0]['class']) &&
+            // Remove invariant entries as they don't provide much value:
+            ($trace[0]['class'] . '::' . $trace[0]['function'] === 'GraphQL\Utils\Utils::invariant')) {
+            array_shift($trace);
+        } elseif (! isset($trace[0]['file'])) {
+            // Remove root call as it's likely error handler trace:
+            array_shift($trace);
+        }
+
+        return array_map(
+            static function ($err) {
+                $safeErr = array_intersect_key($err, ['file' => true, 'line' => true]);
+
+                if (isset($err['function'])) {
+                    $func    = $err['function'];
+                    $args    = ! empty($err['args']) ? array_map([self::class, 'printVar'], $err['args']) : [];
+                    $funcStr = $func . '(' . implode(', ', $args) . ')';
+
+                    if (isset($err['class'])) {
+                        $safeErr['call'] = $err['class'] . '::' . $funcStr;
+                    } else {
+                        $safeErr['function'] = $funcStr;
+                    }
+                }
+
+                return $safeErr;
+            },
+            $trace
+        );
+    }
+
+    /**
+     * @param mixed $var
+     *
+     * @return string
+     */
+    public static function printVar($var)
+    {
+        if ($var instanceof Type) {
+            // FIXME: Replace with schema printer call
+            if ($var instanceof WrappingType) {
+                $var = $var->getWrappedType(true);
+            }
+
+            return 'GraphQLType: ' . $var->name;
+        }
+
+        if (is_object($var)) {
+            return 'instance of ' . get_class($var) . ($var instanceof Countable ? '(' . count($var) . ')' : '');
+        }
+        if (is_array($var)) {
+            return 'array(' . count($var) . ')';
+        }
+        if ($var === '') {
+            return '(empty string)';
+        }
+        if (is_string($var)) {
+            return "'" . addcslashes($var, "'") . "'";
+        }
+        if (is_bool($var)) {
+            return $var ? 'true' : 'false';
+        }
+        if (is_scalar($var)) {
+            return $var;
+        }
+        if ($var === null) {
+            return 'null';
+        }
+
+        return gettype($var);
+    }
+
+    /**
+     * @deprecated as of v0.8.0
+     *
+     * @param string           $error
+     * @param SourceLocation[] $locations
+     *
+     * @return mixed[]
+     */
+    public static function create($error, array $locations = [])
+    {
+        $formatted = ['message' => $error];
+
+        if (! empty($locations)) {
+            $formatted['locations'] = array_map(
+                static function ($loc) {
+                    return $loc->toArray();
+                },
+                $locations
+            );
+        }
+
+        return $formatted;
+    }
+
+    /**
+     * @deprecated as of v0.10.0, use general purpose method createFromException() instead
+     *
+     * @return mixed[]
+     */
+    public static function createFromPHPError(ErrorException $e)
+    {
+        return [
+            'message'  => $e->getMessage(),
+            'severity' => $e->getSeverity(),
+            'trace'    => self::toSafeTrace($e),
+        ];
+    }
+}

src/Error/InvariantViolation.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Error;
+
+use LogicException;
+
+/**
+ * Note:
+ * This exception should not inherit base Error exception as it is raised when there is an error somewhere in
+ * user-land code
+ */
+class InvariantViolation extends LogicException
+{
+}

src/Error/SyntaxError.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Error;
+
+use GraphQL\Language\Source;
+use function sprintf;
+
+class SyntaxError extends Error
+{
+    /**
+     * @param int    $position
+     * @param string $description
+     */
+    public function __construct(Source $source, $position, $description)
+    {
+        parent::__construct(
+            sprintf('Syntax Error: %s', $description),
+            null,
+            $source,
+            [$position]
+        );
+    }
+}

src/Error/UserError.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Error;
+
+use RuntimeException;
+
+/**
+ * Error caused by actions of GraphQL clients. Can be safely displayed to a client...
+ */
+class UserError extends RuntimeException implements ClientAware
+{
+    /**
+     * @return bool
+     */
+    public function isClientSafe()
+    {
+        return true;
+    }
+
+    /**
+     * @return string
+     */
+    public function getCategory()
+    {
+        return 'user';
+    }
+}

src/Error/Warning.php

@@ -0,0 +1,117 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Error;
+
+use GraphQL\Exception\InvalidArgument;
+use function is_int;
+use function trigger_error;
+use const E_USER_WARNING;
+
+/**
+ * Encapsulates warnings produced by the library.
+ *
+ * Warnings can be suppressed (individually or all) if required.
+ * Also it is possible to override warning handler (which is **trigger_error()** by default)
+ */
+final class Warning
+{
+    public const WARNING_ASSIGN             = 2;
+    public const WARNING_CONFIG             = 4;
+    public const WARNING_FULL_SCHEMA_SCAN   = 8;
+    public const WARNING_CONFIG_DEPRECATION = 16;
+    public const WARNING_NOT_A_TYPE         = 32;
+    public const ALL                        = 63;
+
+    /** @var int */
+    private static $enableWarnings = self::ALL;
+
+    /** @var mixed[] */
+    private static $warned = [];
+
+    /** @var callable|null */
+    private static $warningHandler;
+
+    /**
+     * Sets warning handler which can intercept all system warnings.
+     * When not set, trigger_error() is used to notify about warnings.
+     *
+     * @api
+     */
+    public static function setWarningHandler(?callable $warningHandler = null) : void
+    {
+        self::$warningHandler = $warningHandler;
+    }
+
+    /**
+     * Suppress warning by id (has no effect when custom warning handler is set)
+     *
+     * Usage example:
+     * Warning::suppress(Warning::WARNING_NOT_A_TYPE)
+     *
+     * When passing true - suppresses all warnings.
+     *
+     * @param bool|int $suppress
+     *
+     * @api
+     */
+    public static function suppress($suppress = true) : void
+    {
+        if ($suppress === true) {
+            self::$enableWarnings = 0;
+        } elseif ($suppress === false) {
+            self::$enableWarnings = self::ALL;
+        } elseif (is_int($suppress)) {
+            self::$enableWarnings &= ~$suppress;
+        } else {
+            throw InvalidArgument::fromExpectedTypeAndArgument('bool|int', $suppress);
+        }
+    }
+
+    /**
+     * Re-enable previously suppressed warning by id
+     *
+     * Usage example:
+     * Warning::suppress(Warning::WARNING_NOT_A_TYPE)
+     *
+     * When passing true - re-enables all warnings.
+     *
+     * @param bool|int $enable
+     *
+     * @api
+     */
+    public static function enable($enable = true) : void
+    {
+        if ($enable === true) {
+            self::$enableWarnings = self::ALL;
+        } elseif ($enable === false) {
+            self::$enableWarnings = 0;
+        } elseif (is_int($enable)) {
+            self::$enableWarnings |= $enable;
+        } else {
+            throw InvalidArgument::fromExpectedTypeAndArgument('bool|int', $enable);
+        }
+    }
+
+    public static function warnOnce(string $errorMessage, int $warningId, ?int $messageLevel = null) : void
+    {
+        if (self::$warningHandler !== null) {
+            $fn = self::$warningHandler;
+            $fn($errorMessage, $warningId);
+        } elseif ((self::$enableWarnings & $warningId) > 0 && ! isset(self::$warned[$warningId])) {
+            self::$warned[$warningId] = true;
+            trigger_error($errorMessage, $messageLevel ?: E_USER_WARNING);
+        }
+    }
+
+    public static function warn(string $errorMessage, int $warningId, ?int $messageLevel = null) : void
+    {
+        if (self::$warningHandler !== null) {
+            $fn = self::$warningHandler;
+            $fn($errorMessage, $warningId);
+        } elseif ((self::$enableWarnings & $warningId) > 0) {
+            trigger_error($errorMessage, $messageLevel ?: E_USER_WARNING);
+        }
+    }
+}

src/Exception/InvalidArgument.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Exception;
+
+use InvalidArgumentException;
+use function gettype;
+use function sprintf;
+
+final class InvalidArgument extends InvalidArgumentException
+{
+    /**
+     * @param mixed $argument
+     */
+    public static function fromExpectedTypeAndArgument(string $expectedType, $argument) : self
+    {
+        return new self(sprintf('Expected type "%s", got "%s"', $expectedType, gettype($argument)));
+    }
+}

src/Executor/DeprecatedMappingExecutor.php

@@ -1,773 +0,0 @@
-<?php
-namespace GraphQL\Executor;
-
-use GraphQL\Error;
-use GraphQL\Language\AST\Document;
-use GraphQL\Language\AST\Field;
-use GraphQL\Language\AST\FragmentDefinition;
-use GraphQL\Language\AST\Node;
-use GraphQL\Language\AST\OperationDefinition;
-use GraphQL\Language\AST\SelectionSet;
-use GraphQL\Schema;
-use GraphQL\Type\Definition\AbstractType;
-use GraphQL\Type\Definition\Directive;
-use GraphQL\Type\Definition\EnumType;
-use GraphQL\Type\Definition\FieldDefinition;
-use GraphQL\Type\Definition\InterfaceType;
-use GraphQL\Type\Definition\ListOfType;
-use GraphQL\Type\Definition\NonNull;
-use GraphQL\Type\Definition\ObjectType;
-use GraphQL\Type\Definition\ResolveInfo;
-use GraphQL\Type\Definition\ScalarType;
-use GraphQL\Type\Definition\Type;
-use GraphQL\Type\Definition\UnionType;
-use GraphQL\Type\Introspection;
-use GraphQL\Utils;
-
-/**
- * @deprecated Use regular executor instead
- *
- * Terminology
- *
- * "Definitions" are the generic name for top-level statements in the document.
- * Examples of this include:
- * 1) Operations (such as a query)
- * 2) Fragments
- *
- * "Operations" are a generic name for requests in the document.
- * Examples of this include:
- * 1) query,
- * 2) mutation
- *
- * "Selections" are the statements that can appear legally and at
- * single level of the query. These include:
- * 1) field references e.g "a"
- * 2) fragment "spreads" e.g. "...c"
- * 3) inline fragment "spreads" e.g. "...on Type { a }"
- */
-class MappingExecutor
-{
-    private static $UNDEFINED;
-
-    private static $defaultResolveFn = [__CLASS__, 'defaultResolveFn'];
-
-    /**
-     * Custom default resolve function
-     *
-     * @param $fn
-     * @throws \Exception
-     */
-    public function setDefaultResolveFn($fn)
-    {
-        Utils::invariant(is_callable($fn), 'Expecting callable, but got ' . Utils::getVariableType($fn));
-        self::$defaultResolveFn = $fn;
-    }
-
-    /**
-     * @param Schema $schema
-     * @param Document $ast
-     * @param $rootValue
-     * @param array|\ArrayAccess $variableValues
-     * @param null $operationName
-     * @return ExecutionResult
-     */
-    public static function execute(Schema $schema, Document $ast, $rootValue = null, $variableValues = null, $operationName = null)
-    {
-        if (!self::$UNDEFINED) {
-            self::$UNDEFINED = new \stdClass();
-        }
-
-        if (null !== $variableValues) {
-            Utils::invariant(
-                is_array($variableValues) || $variableValues instanceof \ArrayAccess,
-                "Variable values are expected to be array or instance of ArrayAccess, got " . Utils::getVariableType($variableValues)
-            );
-        }
-        if (null !== $operationName) {
-            Utils::invariant(
-                is_string($operationName),
-                "Operation name is supposed to be string, got " . Utils::getVariableType($operationName)
-            );
-        }
-
-        $exeContext = self::buildExecutionContext($schema, $ast, $rootValue, $variableValues, $operationName);
-
-        try {
-            $data = self::executeOperation($exeContext, $exeContext->operation, $rootValue);
-        } catch (Error $e) {
-            $exeContext->addError($e);
-            $data = null;
-        }
-
-        return new ExecutionResult($data, $exeContext->errors);
-    }
-
-    /**
-     * Constructs a ExecutionContext object from the arguments passed to
-     * execute, which we will pass throughout the other execution methods.
-     */
-    private static function buildExecutionContext(Schema $schema, Document $documentAst, $rootValue, $rawVariableValues, $operationName = null)
-    {
-        $errors = [];
-        $operations = [];
-        $fragments = [];
-
-        foreach ($documentAst->definitions as $statement) {
-            switch ($statement->kind) {
-                case Node::OPERATION_DEFINITION:
-                    $operations[$statement->name ? $statement->name->value : ''] = $statement;
-                    break;
-                case Node::FRAGMENT_DEFINITION:
-                    $fragments[$statement->name->value] = $statement;
-                    break;
-            }
-        }
-
-        if (!$operationName && count($operations) !== 1) {
-            throw new Error(
-                'Must provide operation name if query contains multiple operations.'
-            );
-        }
-
-        $opName = $operationName ?: key($operations);
-        if (empty($operations[$opName])) {
-            throw new Error('Unknown operation named ' . $opName);
-        }
-        $operation = $operations[$opName];
-
-        $variableValues = Values::getVariableValues($schema, $operation->variableDefinitions ?: [], $rawVariableValues ?: []);
-        $exeContext = new ExecutionContext($schema, $fragments, $rootValue, $operation, $variableValues, $errors);
-        return $exeContext;
-    }
-
-    /**
-     * Implements the "Evaluating operations" section of the spec.
-     */
-    private static function executeOperation(ExecutionContext $exeContext, OperationDefinition $operation, $rootValue)
-    {
-        $type = self::getOperationRootType($exeContext->schema, $operation);
-        $fields = self::collectFields($exeContext, $type, $operation->selectionSet, new \ArrayObject(), new \ArrayObject());
-
-        if ($operation->operation === 'mutation') {
-            $result = self::executeFieldsSerially($exeContext, $type, [$rootValue], $fields);
-        } else {
-            $result = self::executeFields($exeContext, $type, [$rootValue], $fields);
-        }
-
-        return null === $result || $result === [] ? [] : $result[0];
-    }
-
-
-    /**
-     * Extracts the root type of the operation from the schema.
-     *
-     * @param Schema $schema
-     * @param OperationDefinition $operation
-     * @return ObjectType
-     * @throws Error
-     */
-    private static function getOperationRootType(Schema $schema, OperationDefinition $operation)
-    {
-        switch ($operation->operation) {
-            case 'query':
-                return $schema->getQueryType();
-            case 'mutation':
-                $mutationType = $schema->getMutationType();
-                if (!$mutationType) {
-                    throw new Error(
-                        'Schema is not configured for mutations',
-                        [$operation]
-                    );
-                }
-                return $mutationType;
-            default:
-                throw new Error(
-                    'Can only execute queries and mutations',
-                    [$operation]
-                );
-        }
-    }
-
-    /**
-     * Implements the "Evaluating selection sets" section of the spec
-     * for "write" mode.
-     *
-     * @param ExecutionContext $exeContext
-     * @param ObjectType $parentType
-     * @param $sourceList
-     * @param $fields
-     * @return array
-     * @throws Error
-     * @throws \Exception
-     */
-    private static function executeFieldsSerially(ExecutionContext $exeContext, ObjectType $parentType, $sourceList, $fields)
-    {
-        $results = [];
-        foreach ($fields as $responseName => $fieldASTs) {
-            self::resolveField($exeContext, $parentType, $sourceList, $fieldASTs, $responseName, $results);
-        }
-
-        return $results;
-    }
-
-    /**
-     * Implements the "Evaluating selection sets" section of the spec
-     * for "read" mode.
-     * @param ExecutionContext $exeContext
-     * @param ObjectType $parentType
-     * @param $sourceList
-     * @param $fields
-     * @return array
-     */
-    private static function executeFields(ExecutionContext $exeContext, ObjectType $parentType, $sourceList, $fields)
-    {
-        // Native PHP doesn't support promises.
-        // Custom executor should be built for platforms like ReactPHP
-        return self::executeFieldsSerially($exeContext, $parentType, $sourceList, $fields);
-    }
-
-
-    /**
-     * Given a selectionSet, adds all of the fields in that selection to
-     * the passed in map of fields, and returns it at the end.
-     *
-     * @return \ArrayObject
-     */
-    private static function collectFields(
-        ExecutionContext $exeContext,
-        ObjectType $type,
-        SelectionSet $selectionSet,
-        $fields,
-        $visitedFragmentNames
-    )
-    {
-        for ($i = 0; $i < count($selectionSet->selections); $i++) {
-            $selection = $selectionSet->selections[$i];
-            switch ($selection->kind) {
-                case Node::FIELD:
-                    if (!self::shouldIncludeNode($exeContext, $selection->directives)) {
-                        continue;
-                    }
-                    $name = self::getFieldEntryKey($selection);
-                    if (!isset($fields[$name])) {
-                        $fields[$name] = new \ArrayObject();
-                    }
-                    $fields[$name][] = $selection;
-                    break;
-                case Node::INLINE_FRAGMENT:
-                    if (!self::shouldIncludeNode($exeContext, $selection->directives) ||
-                        !self::doesFragmentConditionMatch($exeContext, $selection, $type)
-                    ) {
-                        continue;
-                    }
-                    self::collectFields(
-                        $exeContext,
-                        $type,
-                        $selection->selectionSet,
-                        $fields,
-                        $visitedFragmentNames
-                    );
-                    break;
-                case Node::FRAGMENT_SPREAD:
-                    $fragName = $selection->name->value;
-                    if (!empty($visitedFragmentNames[$fragName]) || !self::shouldIncludeNode($exeContext, $selection->directives)) {
-                        continue;
-                    }
-                    $visitedFragmentNames[$fragName] = true;
-
-                    /** @var FragmentDefinition|null $fragment */
-                    $fragment = isset($exeContext->fragments[$fragName]) ? $exeContext->fragments[$fragName] : null;
-                    if (!$fragment ||
-                        !self::shouldIncludeNode($exeContext, $fragment->directives) ||
-                        !self::doesFragmentConditionMatch($exeContext, $fragment, $type)
-                    ) {
-                        continue;
-                    }
-                    self::collectFields(
-                        $exeContext,
-                        $type,
-                        $fragment->selectionSet,
-                        $fields,
-                        $visitedFragmentNames
-                    );
-                    break;
-            }
-        }
-        return $fields;
-    }
-
-    /**
-     * Determines if a field should be included based on the @include and @skip
-     * directives, where @skip has higher precedence than @include.
-     */
-    private static function shouldIncludeNode(ExecutionContext $exeContext, $directives)
-    {
-        $skipDirective = Directive::skipDirective();
-        $includeDirective = Directive::includeDirective();
-
-        /** @var \GraphQL\Language\AST\Directive $skipAST */
-        $skipAST = $directives
-            ? Utils::find($directives, function(\GraphQL\Language\AST\Directive $directive) use ($skipDirective) {
-                return $directive->name->value === $skipDirective->name;
-            })
-            : null;
-
-        if ($skipAST) {
-            $argValues = Values::getArgumentValues($skipDirective->args, $skipAST->arguments, $exeContext->variableValues);
-            return empty($argValues['if']);
-        }
-
-        /** @var \GraphQL\Language\AST\Directive $includeAST */
-        $includeAST = $directives
-            ? Utils::find($directives, function(\GraphQL\Language\AST\Directive $directive) use ($includeDirective) {
-                return $directive->name->value === $includeDirective->name;
-            })
-            : null;
-
-        if ($includeAST) {
-            $argValues = Values::getArgumentValues($includeDirective->args, $includeAST->arguments, $exeContext->variableValues);
-            return !empty($argValues['if']);
-        }
-
-        return true;
-    }
-
-    /**
-     * Determines if a fragment is applicable to the given type.
-     */
-    private static function doesFragmentConditionMatch(ExecutionContext $exeContext,/* FragmentDefinition | InlineFragment*/ $fragment, ObjectType $type)
-    {
-        $conditionalType = Utils\TypeInfo::typeFromAST($exeContext->schema, $fragment->typeCondition);
-        if ($conditionalType === $type) {
-            return true;
-        }
-        if ($conditionalType instanceof InterfaceType ||
-            $conditionalType instanceof UnionType
-        ) {
-            return $conditionalType->isPossibleType($type);
-        }
-        return false;
-    }
-
-    /**
-     * Implements the logic to compute the key of a given fields entry
-     */
-    private static function getFieldEntryKey(Field $node)
-    {
-        return $node->alias ? $node->alias->value : $node->name->value;
-    }
-
-    /**
-     * Given list of parent type values returns corresponding list of field values
-     *
-     * In particular, this
-     * figures out the value that the field returns by calling its `resolve` or `map` function,
-     * then calls `completeValue` on each value to serialize scalars, or execute the sub-selection-set
-     * for objects.
-     *
-     * @param ExecutionContext $exeContext
-     * @param ObjectType $parentType
-     * @param $sourceValueList
-     * @param $fieldASTs
-     * @return array
-     * @throws Error
-     */
-    private static function resolveField(ExecutionContext $exeContext, ObjectType $parentType, $sourceValueList, $fieldASTs, $responseName, &$resolveResult)
-    {
-        $fieldAST = $fieldASTs[0];
-        $fieldName = $fieldAST->name->value;
-
-        $fieldDef = self::getFieldDef($exeContext->schema, $parentType, $fieldName);
-
-        if (!$fieldDef) {
-            return ;
-        }
-
-        $returnType = $fieldDef->getType();
-
-        // Build hash of arguments from the field.arguments AST, using the
-        // variables scope to fulfill any variable references.
-        // TODO: find a way to memoize, in case this field is within a List type.
-        $args = Values::getArgumentValues(
-            $fieldDef->args,
-            $fieldAST->arguments,
-            $exeContext->variableValues
-        );
-
-        // The resolve function's optional third argument is a collection of
-        // information about the current execution state.
-        $info = new ResolveInfo([
-            'fieldName' => $fieldName,
-            'fieldASTs' => $fieldASTs,
-            'returnType' => $returnType,
-            'parentType' => $parentType,
-            'schema' => $exeContext->schema,
-            'fragments' => $exeContext->fragments,
-            'rootValue' => $exeContext->rootValue,
-            'operation' => $exeContext->operation,
-            'variableValues' => $exeContext->variableValues,
-        ]);
-
-        $mapFn = $fieldDef->mapFn;
-
-        // If an error occurs while calling the field `map` or `resolve` function, ensure that
-        // it is wrapped as a GraphQLError with locations. Log this error and return
-        // null if allowed, otherwise throw the error so the parent field can handle
-        // it.
-        if ($mapFn) {
-            try {
-                $mapped = call_user_func($mapFn, $sourceValueList, $args, $info);
-                $validType = is_array($mapped) || ($mapped instanceof \Traversable && $mapped instanceof \Countable);
-                $mappedCount = count($mapped);
-                $sourceCount = count($sourceValueList);
-
-                Utils::invariant(
-                    $validType && count($mapped) === count($sourceValueList),
-                    "Function `map` of $parentType.$fieldName is expected to return array or " .
-                    "countable traversable with exact same number of items as list being mapped. ".
-                    "Got '%s' with count '$mappedCount' against '$sourceCount' expected.",
-                    Utils::getVariableType($mapped)
-                );
-
-            } catch (\Exception $error) {
-                $reportedError = Error::createLocatedError($error, $fieldASTs);
-
-                if ($returnType instanceof NonNull) {
-                    throw $reportedError;
-                }
-
-                $exeContext->addError($reportedError);
-                return null;
-            }
-
-            foreach ($mapped as $index => $value) {
-                $resolveResult[$index][$responseName] = self::completeValueCatchingError(
-                    $exeContext,
-                    $returnType,
-                    $fieldASTs,
-                    $info,
-                    $value
-                );
-            }
-        } else {
-            if (isset($fieldDef->resolveFn)) {
-                $resolveFn = $fieldDef->resolveFn;
-            } else if (isset($parentType->resolveFieldFn)) {
-                $resolveFn = $parentType->resolveFieldFn;
-            } else {
-                $resolveFn = self::$defaultResolveFn;
-            }
-
-            foreach ($sourceValueList as $index => $value) {
-                try {
-                    $resolved = call_user_func($resolveFn, $value, $args, $info);
-                } catch (\Exception $error) {
-                    $reportedError = Error::createLocatedError($error, $fieldASTs);
-
-                    if ($returnType instanceof NonNull) {
-                        throw $reportedError;
-                    }
-
-                    $exeContext->addError($reportedError);
-                    $resolved = null;
-                }
-
-                $resolveResult[$index][$responseName] = self::completeValueCatchingError(
-                    $exeContext,
-                    $returnType,
-                    $fieldASTs,
-                    $info,
-                    $resolved
-                );
-            }
-        }
-    }
-
-
-    public static function completeValueCatchingError(
-        ExecutionContext $exeContext,
-        Type $returnType,
-        $fieldASTs,
-        ResolveInfo $info,
-        $result
-    )
-    {
-        // If the field type is non-nullable, then it is resolved without any
-        // protection from errors.
-        if ($returnType instanceof NonNull) {
-            return self::completeValue($exeContext, $returnType, $fieldASTs, $info, $result);
-        }
-
-        // Otherwise, error protection is applied, logging the error and resolving
-        // a null value for this field if one is encountered.
-        try {
-            return self::completeValue($exeContext, $returnType, $fieldASTs, $info, $result);
-        } catch (Error $err) {
-            $exeContext->addError($err);
-            return null;
-        }
-    }
-
-    /**
-     * Implements the instructions for completeValue as defined in the
-     * "Field entries" section of the spec.
-     *
-     * If the field type is Non-Null, then this recursively completes the value
-     * for the inner type. It throws a field error if that completion returns null,
-     * as per the "Nullability" section of the spec.
-     *
-     * If the field type is a List, then this recursively completes the value
-     * for the inner type on each item in the list.
-     *
-     * If the field type is a Scalar or Enum, ensures the completed value is a legal
-     * value of the type by calling the `serialize` method of GraphQL type
-     * definition.
-     *
-     * Otherwise, the field type expects a sub-selection set, and will complete the
-     * value by evaluating all sub-selections.
-     */
-    private static function completeValue(ExecutionContext $exeContext, Type $returnType,/* Array<Field> */ $fieldASTs, ResolveInfo $info, &$result)
-    {
-        // If field type is NonNull, complete for inner type, and throw field error
-        // if result is null.
-        if ($returnType instanceof NonNull) {
-            $completed = self::completeValue(
-                $exeContext,
-                $returnType->getWrappedType(),
-                $fieldASTs,
-                $info,
-                $result
-            );
-            if ($completed === null) {
-                throw new Error(
-                    'Cannot return null for non-nullable type.',
-                    $fieldASTs instanceof \ArrayObject ? $fieldASTs->getArrayCopy() : $fieldASTs
-                );
-            }
-            return $completed;
-        }
-
-        // If result is null-like, return null.
-        if (null === $result) {
-            return null;
-        }
-
-        // If field type is Scalar or Enum, serialize to a valid value, returning
-        // null if serialization is not possible.
-        if ($returnType instanceof ScalarType ||
-            $returnType instanceof EnumType) {
-            return $returnType->serialize($result);
-        }
-
-        // If field type is List, and return type is Composite - complete by executing these fields with list value as parameter
-        if ($returnType instanceof ListOfType) {
-            $itemType = $returnType->getWrappedType();
-
-            Utils::invariant(
-                is_array($result) || $result instanceof \Traversable,
-                'User Error: expected iterable, but did not find one.'
-            );
-
-            // For Object[]:
-            // Allow all object fields to process list value in it's `map` callback:
-            if ($itemType instanceof ObjectType) {
-                // Filter out nulls (as `map` doesn't expect it):
-                $list = [];
-                foreach ($result as $index => $item) {
-                    if (null !== $item) {
-                        $list[] = $item;
-                    }
-                }
-
-                $subFieldASTs = self::collectSubFields($exeContext, $itemType, $fieldASTs);
-                $mapped = self::executeFields($exeContext, $itemType, $list, $subFieldASTs);
-
-                $i = 0;
-                $completed = [];
-                foreach ($result as $index => $item) {
-                    if (null === $item) {
-                        // Complete nulls separately
-                        $completed[] = self::completeValueCatchingError($exeContext, $itemType, $fieldASTs, $info, $item);
-                    } else {
-                        // Assuming same order of mapped values
-                        $completed[] = $mapped[$i++];
-                    }
-                }
-                return $completed;
-
-            } else if ($itemType instanceof AbstractType) {
-
-                // Values sharded by ObjectType
-                $listPerObjectType = [];
-
-                // Helper structures to restore ordering after resolve calls
-                $resultTypeMap = [];
-                $typeNameMap = [];
-                $cursors = [];
-                $copied = [];
-
-                foreach ($result as $index => $item) {
-                    $copied[$index] = $item;
-
-                    if (null !== $item) {
-                        $objectType = $itemType->getObjectType($item, $info);
-
-                        if ($objectType && !$itemType->isPossibleType($objectType)) {
-                            $exeContext->addError(new Error(
-                                "Runtime Object type \"$objectType\" is not a possible type for \"$itemType\"."
-                            ));
-                            $copied[$index] = null;
-                        } else {
-                            $listPerObjectType[$objectType->name][] = $item;
-                            $resultTypeMap[$index] = $objectType->name;
-                            $typeNameMap[$objectType->name] = $objectType;
-                        }
-                    }
-                }
-
-                $mapped = [];
-                foreach ($listPerObjectType as $typeName => $list) {
-                    $objectType = $typeNameMap[$typeName];
-                    $subFieldASTs = self::collectSubFields($exeContext, $objectType, $fieldASTs);
-                    $mapped[$typeName] = self::executeFields($exeContext, $objectType, $list, $subFieldASTs);
-                    $cursors[$typeName] = 0;
-                }
-
-                // Restore order:
-                $completed = [];
-                foreach ($copied as $index => $item) {
-                    if (null === $item) {
-                        // Complete nulls separately
-                        $completed[] = self::completeValueCatchingError($exeContext, $itemType, $fieldASTs, $info, $item);
-                    } else {
-                        $typeName = $resultTypeMap[$index];
-                        $completed[] = $mapped[$typeName][$cursors[$typeName]++];
-                    }
-                }
-
-                return $completed;
-            } else {
-
-                // For simple lists:
-                $tmp = [];
-                foreach ($result as $item) {
-                    $tmp[] = self::completeValueCatchingError($exeContext, $itemType, $fieldASTs, $info, $item);
-                }
-                return $tmp;
-            }
-
-        }
-
-        if ($returnType instanceof ObjectType) {
-            $objectType = $returnType;
-
-        } else if ($returnType instanceof AbstractType) {
-            $objectType = $returnType->getObjectType($result, $info);
-
-            if ($objectType && !$returnType->isPossibleType($objectType)) {
-                throw new Error(
-                    "Runtime Object type \"$objectType\" is not a possible type for \"$returnType\"."
-                );
-            }
-        } else {
-            $objectType = null;
-        }
-
-        if (!$objectType) {
-            return null;
-        }
-
-        // If there is an isTypeOf predicate function, call it with the
-        // current result. If isTypeOf returns false, then raise an error rather
-        // than continuing execution.
-        if (false === $objectType->isTypeOf($result, $info)) {
-            throw new Error(
-                "Expected value of type $objectType but got: $result.",
-                $fieldASTs
-            );
-        }
-
-        // Collect sub-fields to execute to complete this value.
-        $subFieldASTs = self::collectSubFields($exeContext, $objectType, $fieldASTs);
-        $executed = self::executeFields($exeContext, $objectType, [$result], $subFieldASTs);
-        return isset($executed[0]) ? $executed[0] : null;
-    }
-
-    /**
-     * @param ExecutionContext $exeContext
-     * @param ObjectType $objectType
-     * @param $fieldASTs
-     * @return \ArrayObject
-     */
-    private static function collectSubFields(ExecutionContext $exeContext, ObjectType $objectType, $fieldASTs)
-    {
-        $subFieldASTs = new \ArrayObject();
-        $visitedFragmentNames = new \ArrayObject();
-        for ($i = 0; $i < count($fieldASTs); $i++) {
-            $selectionSet = $fieldASTs[$i]->selectionSet;
-            if ($selectionSet) {
-                $subFieldASTs = self::collectFields(
-                    $exeContext,
-                    $objectType,
-                    $selectionSet,
-                    $subFieldASTs,
-                    $visitedFragmentNames
-                );
-            }
-        }
-        return $subFieldASTs;
-    }
-
-    /**
-     * If a resolve function is not given, then a default resolve behavior is used
-     * which takes the property of the source object of the same name as the field
-     * and returns it as the result, or if it's a function, returns the result
-     * of calling that function.
-     */
-    public static function defaultResolveFn($source, $args, ResolveInfo $info)
-    {
-        $fieldName = $info->fieldName;
-        $property = null;
-
-        if (is_array($source) || $source instanceof \ArrayAccess) {
-            if (isset($source[$fieldName])) {
-                $property = $source[$fieldName];
-            }
-        } else if (is_object($source)) {
-            if (isset($source->{$fieldName})) {
-                $property = $source->{$fieldName};
-            }
-        }
-
-        return $property instanceof \Closure ? $property($source) : $property;
-    }
-
-    /**
-     * This method looks up the field on the given type defintion.
-     * It has special casing for the two introspection fields, __schema
-     * and __typename. __typename is special because it can always be
-     * queried as a field, even in situations where no other fields
-     * are allowed, like on a Union. __schema could get automatically
-     * added to the query type, but that would require mutating type
-     * definitions, which would cause issues.
-     *
-     * @return FieldDefinition
-     */
-    private static function getFieldDef(Schema $schema, ObjectType $parentType, $fieldName)
-    {
-        $schemaMetaFieldDef = Introspection::schemaMetaFieldDef();
-        $typeMetaFieldDef = Introspection::typeMetaFieldDef();
-        $typeNameMetaFieldDef = Introspection::typeNameMetaFieldDef();
-
-        if ($fieldName === $schemaMetaFieldDef->name && $schema->getQueryType() === $parentType) {
-            return $schemaMetaFieldDef;
-        } else if ($fieldName === $typeMetaFieldDef->name && $schema->getQueryType() === $parentType) {
-            return $typeMetaFieldDef;
-        } else if ($fieldName === $typeNameMetaFieldDef->name) {
-            return $typeNameMetaFieldDef;
-        }
-
-        $tmp = $parentType->getFields();
-        return isset($tmp[$fieldName]) ? $tmp[$fieldName] : null;
-    }
-}

src/Executor/ExecutionContext.php

@@ -1,66 +1,78 @@
 <?php
+
+declare(strict_types=1);
+
 namespace GraphQL\Executor;
 
-use GraphQL\Error;
-use GraphQL\Language\AST\OperationDefinition;
-use GraphQL\Schema;
+use GraphQL\Error\Error;
+use GraphQL\Executor\Promise\PromiseAdapter;
+use GraphQL\Language\AST\FragmentDefinitionNode;
+use GraphQL\Language\AST\OperationDefinitionNode;
+use GraphQL\Type\Schema;
 
 /**
  * Data that must be available at all points during query execution.
  *
  * Namely, schema of the type system that is currently executing,
- * and the fragments defined in the query document
+ * and the fragments defined in the query document.
+ *
+ * @internal
  */
 class ExecutionContext
 {
-    /**
-     * @var Schema
-     */
+    /** @var Schema */
     public $schema;
 
-    /**
-     * @var array<string, FragmentDefinition>
-     */
+    /** @var FragmentDefinitionNode[] */
     public $fragments;
 
-    /**
-     * @var
-     */
+    /** @var mixed */
     public $rootValue;
 
-    /**
-     * @var OperationDefinition
-     */
+    /** @var mixed */
+    public $contextValue;
+
+    /** @var OperationDefinitionNode */
     public $operation;
 
-    /**
-     * @var array
-     */
+    /** @var mixed[] */
     public $variableValues;
 
-    /**
-     * @var array
-     */
+    /** @var callable */
+    public $fieldResolver;
+
+    /** @var Error[] */
     public $errors;
 
-    /**
-     * @var array
-     */
-    public $memoized = [];
+    /** @var PromiseAdapter */
+    public $promiseAdapter;
 
-    public function __construct($schema, $fragments, $root, $operation, $variables, $errors)
-    {
-        $this->schema = $schema;
-        $this->fragments = $fragments;
-        $this->rootValue = $root;
-        $this->operation = $operation;
-        $this->variableValues = $variables;
-        $this->errors = $errors ?: [];
+    public function __construct(
+        $schema,
+        $fragments,
+        $rootValue,
+        $contextValue,
+        $operation,
+        $variableValues,
+        $errors,
+        $fieldResolver,
+        $promiseAdapter
+    ) {
+        $this->schema         = $schema;
+        $this->fragments      = $fragments;
+        $this->rootValue      = $rootValue;
+        $this->contextValue   = $contextValue;
+        $this->operation      = $operation;
+        $this->variableValues = $variableValues;
+        $this->errors         = $errors ?: [];
+        $this->fieldResolver  = $fieldResolver;
+        $this->promiseAdapter = $promiseAdapter;
     }
 
     public function addError(Error $error)
     {
         $this->errors[] = $error;
+
         return $this;
     }
 }

src/Executor/ExecutionResult.php

@@ -1,39 +1,160 @@
 <?php
+
+declare(strict_types=1);
+
 namespace GraphQL\Executor;
 
-use GraphQL\Error;
+use GraphQL\Error\Error;
+use GraphQL\Error\FormattedError;
+use JsonSerializable;
+use function array_map;
 
-class ExecutionResult
+/**
+ * Returned after [query execution](executing-queries.md).
+ * Represents both - result of successful execution and of a failed one
+ * (with errors collected in `errors` prop)
+ *
+ * Could be converted to [spec-compliant](https://facebook.github.io/graphql/#sec-Response-Format)
+ * serializable array using `toArray()`
+ */
+class ExecutionResult implements JsonSerializable
 {
     /**
-     * @var array
+     * Data collected from resolvers during query execution
+     *
+     * @api
+     * @var mixed[]
      */
     public $data;
 
     /**
+     * Errors registered during query execution.
+     *
+     * If an error was caused by exception thrown in resolver, $error->getPrevious() would
+     * contain original exception.
+     *
+     * @api
      * @var Error[]
      */
     public $errors;
 
     /**
-     * @param array $data
-     * @param array $errors
+     * User-defined serializable array of extensions included in serialized result.
+     * Conforms to
+     *
+     * @api
+     * @var mixed[]
      */
-    public function __construct(array $data = null, array $errors = [])
+    public $extensions;
+
+    /** @var callable */
+    private $errorFormatter;
+
+    /** @var callable */
+    private $errorsHandler;
+
+    /**
+     * @param mixed[] $data
+     * @param Error[] $errors
+     * @param mixed[] $extensions
+     */
+    public function __construct($data = null, array $errors = [], array $extensions = [])
     {
-        $this->data = $data;
-        $this->errors = $errors;
+        $this->data       = $data;
+        $this->errors     = $errors;
+        $this->extensions = $extensions;
     }
 
     /**
-     * @return array
+     * Define custom error formatting (must conform to http://facebook.github.io/graphql/#sec-Errors)
+     *
+     * Expected signature is: function (GraphQL\Error\Error $error): array
+     *
+     * Default formatter is "GraphQL\Error\FormattedError::createFromException"
+     *
+     * Expected returned value must be an array:
+     * array(
+     *    'message' => 'errorMessage',
+     *    // ... other keys
+     * );
+     *
+     * @return self
+     *
+     * @api
      */
-    public function toArray()
+    public function setErrorFormatter(callable $errorFormatter)
     {
-        $result = ['data' => $this->data];
+        $this->errorFormatter = $errorFormatter;
 
-        if (!empty($this->errors)) {
-            $result['errors'] = array_map(['GraphQL\Error', 'formatError'], $this->errors);
+        return $this;
+    }
+
+    /**
+     * Define custom logic for error handling (filtering, logging, etc).
+     *
+     * Expected handler signature is: function (array $errors, callable $formatter): array
+     *
+     * Default handler is:
+     * function (array $errors, callable $formatter) {
+     *     return array_map($formatter, $errors);
+     * }
+     *
+     * @return self
+     *
+     * @api
+     */
+    public function setErrorsHandler(callable $handler)
+    {
+        $this->errorsHandler = $handler;
+
+        return $this;
+    }
+
+    /**
+     * @return mixed[]
+     */
+    public function jsonSerialize()
+    {
+        return $this->toArray();
+    }
+
+    /**
+     * Converts GraphQL query result to spec-compliant serializable array using provided
+     * errors handler and formatter.
+     *
+     * If debug argument is passed, output of error formatter is enriched which debugging information
+     * ("debugMessage", "trace" keys depending on flags).
+     *
+     * $debug argument must be either bool (only adds "debugMessage" to result) or sum of flags from
+     * GraphQL\Error\Debug
+     *
+     * @param bool|int $debug
+     *
+     * @return mixed[]
+     *
+     * @api
+     */
+    public function toArray($debug = false)
+    {
+        $result = [];
+
+        if (! empty($this->errors)) {
+            $errorsHandler = $this->errorsHandler ?: static function (array $errors, callable $formatter) {
+                return array_map($formatter, $errors);
+            };
+
+            $result['errors'] = $errorsHandler(
+                $this->errors,
+                FormattedError::prepareFormatter($this->errorFormatter, $debug)
+            );
+        }
+
+        if ($this->data !== null) {
+            $result['data'] = $this->data;
+        }
+
+        if (! empty($this->extensions)) {
+            $result['extensions'] = $this->extensions;
         }
 
         return $result;

src/Executor/Executor.php

@@ -1,678 +1,189 @@
 <?php
+
+declare(strict_types=1);
+
 namespace GraphQL\Executor;
 
-use GraphQL\Error;
-use GraphQL\Language\AST\Document;
-use GraphQL\Language\AST\Field;
-use GraphQL\Language\AST\FragmentDefinition;
-use GraphQL\Language\AST\Node;
-use GraphQL\Language\AST\OperationDefinition;
-use GraphQL\Language\AST\SelectionSet;
-use GraphQL\Schema;
-use GraphQL\Type\Definition\AbstractType;
-use GraphQL\Type\Definition\Directive;
-use GraphQL\Type\Definition\EnumType;
-use GraphQL\Type\Definition\FieldDefinition;
-use GraphQL\Type\Definition\InterfaceType;
-use GraphQL\Type\Definition\ListOfType;
-use GraphQL\Type\Definition\NonNull;
-use GraphQL\Type\Definition\ObjectType;
+use ArrayAccess;
+use Closure;
+use GraphQL\Executor\Promise\Adapter\SyncPromiseAdapter;
+use GraphQL\Executor\Promise\Promise;
+use GraphQL\Executor\Promise\PromiseAdapter;
+use GraphQL\Language\AST\DocumentNode;
 use GraphQL\Type\Definition\ResolveInfo;
-use GraphQL\Type\Definition\ScalarType;
-use GraphQL\Type\Definition\Type;
-use GraphQL\Type\Definition\UnionType;
-use GraphQL\Type\Introspection;
-use GraphQL\Utils;
+use GraphQL\Type\Schema;
+use function is_array;
+use function is_object;
 
 /**
- * Terminology
- *
- * "Definitions" are the generic name for top-level statements in the document.
- * Examples of this include:
- * 1) Operations (such as a query)
- * 2) Fragments
- *
- * "Operations" are a generic name for requests in the document.
- * Examples of this include:
- * 1) query,
- * 2) mutation
- *
- * "Selections" are the statements that can appear legally and at
- * single level of the query. These include:
- * 1) field references e.g "a"
- * 2) fragment "spreads" e.g. "...c"
- * 3) inline fragment "spreads" e.g. "...on Type { a }"
+ * Implements the "Evaluating requests" section of the GraphQL specification.
  */
 class Executor
 {
-    private static $UNDEFINED;
+    /** @var callable|string[] */
+    private static $defaultFieldResolver = [self::class, 'defaultFieldResolver'];
 
-    private static $defaultResolveFn = [__CLASS__, 'defaultResolveFn'];
+    /** @var PromiseAdapter */
+    private static $defaultPromiseAdapter;
+
+    /** @var callable */
+    private static $implementationFactory = [ReferenceExecutor::class, 'create'];
+
+    public static function getDefaultFieldResolver() : callable
+    {
+        return self::$defaultFieldResolver;
+    }
 
     /**
-     * Custom default resolve function
+     * Custom default resolve function.
+     */
+    public static function setDefaultFieldResolver(callable $fieldResolver)
+    {
+        self::$defaultFieldResolver = $fieldResolver;
+    }
+
+    public static function getPromiseAdapter() : PromiseAdapter
+    {
+        return self::$defaultPromiseAdapter ?: (self::$defaultPromiseAdapter = new SyncPromiseAdapter());
+    }
+
+    public static function setPromiseAdapter(?PromiseAdapter $defaultPromiseAdapter = null)
+    {
+        self::$defaultPromiseAdapter = $defaultPromiseAdapter;
+    }
+
+    public static function getImplementationFactory() : callable
+    {
+        return self::$implementationFactory;
+    }
+
+    /**
+     * Custom executor implementation factory.
      *
-     * @param $fn
-     * @throws \Exception
+     * Will be called with as
      */
-    public static function setDefaultResolveFn($fn)
+    public static function setImplementationFactory(callable $implementationFactory)
     {
-        Utils::invariant(is_callable($fn), 'Expecting callable, but got ' . Utils::getVariableType($fn));
-        self::$defaultResolveFn = $fn;
+        self::$implementationFactory = $implementationFactory;
     }
 
     /**
-     * @param Schema $schema
-     * @param Document $ast
-     * @param $rootValue
-     * @param array|\ArrayAccess $variableValues
-     * @param null $operationName
-     * @return ExecutionResult
-     */
-    public static function execute(Schema $schema, Document $ast, $rootValue = null, $variableValues = null, $operationName = null)
-    {
-        if (!self::$UNDEFINED) {
-            self::$UNDEFINED = new \stdClass();
-        }
-
-        if (null !== $variableValues) {
-            Utils::invariant(
-                is_array($variableValues) || $variableValues instanceof \ArrayAccess,
-                "Variable values are expected to be array or instance of ArrayAccess, got " . Utils::getVariableType($variableValues)
-            );
-        }
-        if (null !== $operationName) {
-            Utils::invariant(
-                is_string($operationName),
-                "Operation name is supposed to be string, got " . Utils::getVariableType($operationName)
-            );
-        }
-
-        $exeContext = self::buildExecutionContext($schema, $ast, $rootValue, $variableValues, $operationName);
-
-        try {
-            $data = self::executeOperation($exeContext, $exeContext->operation, $rootValue);
-        } catch (Error $e) {
-            $exeContext->addError($e);
-            $data = null;
-        }
-
-        return new ExecutionResult($data, $exeContext->errors);
-    }
-
-    /**
-     * Constructs a ExecutionContext object from the arguments passed to
-     * execute, which we will pass throughout the other execution methods.
-     */
-    private static function buildExecutionContext(Schema $schema, Document $documentAst, $rootValue, $rawVariableValues, $operationName = null)
-    {
-        $errors = [];
-        $operations = [];
-        $fragments = [];
-
-        foreach ($documentAst->definitions as $statement) {
-            switch ($statement->kind) {
-                case Node::OPERATION_DEFINITION:
-                    $operations[$statement->name ? $statement->name->value : ''] = $statement;
-                    break;
-                case Node::FRAGMENT_DEFINITION:
-                    $fragments[$statement->name->value] = $statement;
-                    break;
-            }
-        }
-
-        if (!$operationName && count($operations) !== 1) {
-            throw new Error(
-                'Must provide operation name if query contains multiple operations.'
-            );
-        }
-
-        $opName = $operationName ?: key($operations);
-        if (empty($operations[$opName])) {
-            throw new Error('Unknown operation named ' . $opName);
-        }
-        $operation = $operations[$opName];
-
-        $variableValues = Values::getVariableValues($schema, $operation->variableDefinitions ?: [], $rawVariableValues ?: []);
-        $exeContext = new ExecutionContext($schema, $fragments, $rootValue, $operation, $variableValues, $errors);
-        return $exeContext;
-    }
-
-    /**
-     * Implements the "Evaluating operations" section of the spec.
-     */
-    private static function executeOperation(ExecutionContext $exeContext, OperationDefinition $operation, $rootValue)
-    {
-        $type = self::getOperationRootType($exeContext->schema, $operation);
-        $fields = self::collectFields($exeContext, $type, $operation->selectionSet, new \ArrayObject(), new \ArrayObject());
-
-        if ($operation->operation === 'mutation') {
-            return self::executeFieldsSerially($exeContext, $type, $rootValue, $fields);
-        }
-
-        return self::executeFields($exeContext, $type, $rootValue, $fields);
-    }
-
-
-    /**
-     * Extracts the root type of the operation from the schema.
+     * Executes DocumentNode against given $schema.
      *
-     * @param Schema $schema
-     * @param OperationDefinition $operation
-     * @return ObjectType
-     * @throws Error
-     */
-    private static function getOperationRootType(Schema $schema, OperationDefinition $operation)
-    {
-        switch ($operation->operation) {
-            case 'query':
-                return $schema->getQueryType();
-            case 'mutation':
-                $mutationType = $schema->getMutationType();
-                if (!$mutationType) {
-                    throw new Error(
-                        'Schema is not configured for mutations',
-                        [$operation]
-                    );
-                }
-                return $mutationType;
-            default:
-                throw new Error(
-                    'Can only execute queries and mutations',
-                    [$operation]
-                );
-        }
-    }
-
-    /**
-     * Implements the "Evaluating selection sets" section of the spec
-     * for "write" mode.
-     */
-    private static function executeFieldsSerially(ExecutionContext $exeContext, ObjectType $parentType, $sourceValue, $fields)
-    {
-        $results = [];
-        foreach ($fields as $responseName => $fieldASTs) {
-            $result = self::resolveField($exeContext, $parentType, $sourceValue, $fieldASTs);
-
-            if ($result !== self::$UNDEFINED) {
-                // Undefined means that field is not defined in schema
-                $results[$responseName] = $result;
-            }
-        }
-        return $results;
-    }
-
-    /**
-     * Implements the "Evaluating selection sets" section of the spec
-     * for "read" mode.
-     */
-    private static function executeFields(ExecutionContext $exeContext, ObjectType $parentType, $source, $fields)
-    {
-        // Native PHP doesn't support promises.
-        // Custom executor should be built for platforms like ReactPHP
-        return self::executeFieldsSerially($exeContext, $parentType, $source, $fields);
-    }
-
-
-    /**
-     * Given a selectionSet, adds all of the fields in that selection to
-     * the passed in map of fields, and returns it at the end.
+     * Always returns ExecutionResult and never throws. All errors which occur during operation
+     * execution are collected in `$result->errors`.
      *
-     * @return \ArrayObject
+     * @param mixed|null               $rootValue
+     * @param mixed|null               $contextValue
+     * @param mixed[]|ArrayAccess|null $variableValues
+     * @param string|null              $operationName
+     *
+     * @return ExecutionResult|Promise
+     *
+     * @api
      */
-    private static function collectFields(
-        ExecutionContext $exeContext,
-        ObjectType $type,
-        SelectionSet $selectionSet,
-        $fields,
-        $visitedFragmentNames
-    )
-    {
-        for ($i = 0; $i < count($selectionSet->selections); $i++) {
-            $selection = $selectionSet->selections[$i];
-            switch ($selection->kind) {
-                case Node::FIELD:
-                    if (!self::shouldIncludeNode($exeContext, $selection->directives)) {
-                        continue;
-                    }
-                    $name = self::getFieldEntryKey($selection);
-                    if (!isset($fields[$name])) {
-                        $fields[$name] = new \ArrayObject();
-                    }
-                    $fields[$name][] = $selection;
-                    break;
-                case Node::INLINE_FRAGMENT:
-                    if (!self::shouldIncludeNode($exeContext, $selection->directives) ||
-                        !self::doesFragmentConditionMatch($exeContext, $selection, $type)
-                    ) {
-                        continue;
-                    }
-                    self::collectFields(
-                        $exeContext,
-                        $type,
-                        $selection->selectionSet,
-                        $fields,
-                        $visitedFragmentNames
-                    );
-                    break;
-                case Node::FRAGMENT_SPREAD:
-                    $fragName = $selection->name->value;
-                    if (!empty($visitedFragmentNames[$fragName]) || !self::shouldIncludeNode($exeContext, $selection->directives)) {
-                        continue;
-                    }
-                    $visitedFragmentNames[$fragName] = true;
+    public static function execute(
+        Schema $schema,
+        DocumentNode $documentNode,
+        $rootValue = null,
+        $contextValue = null,
+        $variableValues = null,
+        $operationName = null,
+        ?callable $fieldResolver = null
+    ) {
+        // TODO: deprecate (just always use SyncAdapter here) and have `promiseToExecute()` for other cases
 
-                    /** @var FragmentDefinition|null $fragment */
-                    $fragment = isset($exeContext->fragments[$fragName]) ? $exeContext->fragments[$fragName] : null;
-                    if (!$fragment ||
-                        !self::shouldIncludeNode($exeContext, $fragment->directives) ||
-                        !self::doesFragmentConditionMatch($exeContext, $fragment, $type)
-                    ) {
-                        continue;
-                    }
-                    self::collectFields(
-                        $exeContext,
-                        $type,
-                        $fragment->selectionSet,
-                        $fields,
-                        $visitedFragmentNames
-                    );
-                    break;
-            }
-        }
-        return $fields;
-    }
+        $promiseAdapter = static::getPromiseAdapter();
 
-    /**
-     * Determines if a field should be included based on the @include and @skip
-     * directives, where @skip has higher precedence than @include.
-     */
-    private static function shouldIncludeNode(ExecutionContext $exeContext, $directives)
-    {
-        $skipDirective = Directive::skipDirective();
-        $includeDirective = Directive::includeDirective();
+        $result = static::promiseToExecute(
+            $promiseAdapter,
+            $schema,
+            $documentNode,
+            $rootValue,
+            $contextValue,
+            $variableValues,
+            $operationName,
+            $fieldResolver
+        );
 
-        /** @var \GraphQL\Language\AST\Directive $skipAST */
-        $skipAST = $directives
-            ? Utils::find($directives, function(\GraphQL\Language\AST\Directive $directive) use ($skipDirective) {
-                return $directive->name->value === $skipDirective->name;
-            })
-            : null;
-
-        if ($skipAST) {
-            $argValues = Values::getArgumentValues($skipDirective->args, $skipAST->arguments, $exeContext->variableValues);
-            return empty($argValues['if']);
-        }
-
-        /** @var \GraphQL\Language\AST\Directive $includeAST */
-        $includeAST = $directives
-            ? Utils::find($directives, function(\GraphQL\Language\AST\Directive $directive) use ($includeDirective) {
-                return $directive->name->value === $includeDirective->name;
-            })
-            : null;
-
-        if ($includeAST) {
-            $argValues = Values::getArgumentValues($includeDirective->args, $includeAST->arguments, $exeContext->variableValues);
-            return !empty($argValues['if']);
-        }
-
-        return true;
-    }
-
-    /**
-     * Determines if a fragment is applicable to the given type.
-     */
-    private static function doesFragmentConditionMatch(ExecutionContext $exeContext,/* FragmentDefinition | InlineFragment*/ $fragment, ObjectType $type)
-    {
-        $typeConditionAST = $fragment->typeCondition;
-
-        if (!$typeConditionAST) {
-            return true;
-        }
-
-        $conditionalType = Utils\TypeInfo::typeFromAST($exeContext->schema, $typeConditionAST);
-        if ($conditionalType === $type) {
-            return true;
-        }
-        if ($conditionalType instanceof InterfaceType ||
-            $conditionalType instanceof UnionType
-        ) {
-            return $conditionalType->isPossibleType($type);
-        }
-        return false;
-    }
-
-    /**
-     * Implements the logic to compute the key of a given fields entry
-     */
-    private static function getFieldEntryKey(Field $node)
-    {
-        return $node->alias ? $node->alias->value : $node->name->value;
-    }
-
-    /**
-     * Resolves the field on the given source object. In particular, this
-     * figures out the value that the field returns by calling its resolve function,
-     * then calls completeValue to complete promises, serialize scalars, or execute
-     * the sub-selection-set for objects.
-     */
-    private static function resolveField(ExecutionContext $exeContext, ObjectType $parentType, $source, $fieldASTs)
-    {
-        $fieldAST = $fieldASTs[0];
-
-        $uid = self::getFieldUid($fieldAST, $parentType);
-
-        // Get memoized variables if they exist
-        if (isset($exeContext->memoized['resolveField'][$uid])) {
-            $memoized = $exeContext->memoized['resolveField'][$uid];
-            $fieldDef = $memoized['fieldDef'];
-            $returnType = $fieldDef->getType();
-            $args = $memoized['args'];
-            $info = $memoized['info'];
-        }
-        else {
-            $fieldName = $fieldAST->name->value;
-
-            $fieldDef = self::getFieldDef($exeContext->schema, $parentType, $fieldName);
-
-            if (!$fieldDef) {
-                return self::$UNDEFINED;
-            }
-
-            $returnType = $fieldDef->getType();
-
-            // Build hash of arguments from the field.arguments AST, using the
-            // variables scope to fulfill any variable references.
-            $args = Values::getArgumentValues(
-                $fieldDef->args,
-                $fieldAST->arguments,
-                $exeContext->variableValues
-            );
-
-            // The resolve function's optional third argument is a collection of
-            // information about the current execution state.
-            $info = new ResolveInfo([
-                'fieldName' => $fieldName,
-                'fieldASTs' => $fieldASTs,
-                'returnType' => $returnType,
-                'parentType' => $parentType,
-                'schema' => $exeContext->schema,
-                'fragments' => $exeContext->fragments,
-                'rootValue' => $exeContext->rootValue,
-                'operation' => $exeContext->operation,
-                'variableValues' => $exeContext->variableValues,
-            ]);
-
-            // Memoizing results for same query field
-            // (useful for lists when several values are resolved against the same field)
-            $exeContext->memoized['resolveField'][$uid] = $memoized = [
-                'fieldDef' => $fieldDef,
-                'args' => $args,
-                'info' => $info,
-                'results' => new \SplObjectStorage
-            ];
-        }
-
-        // When source value is object it is possible to memoize certain subset of results
-        $isObject = is_object($source);
-
-        if ($isObject && isset($memoized['results'][$source])) {
-            $result = $memoized['results'][$source];
-        } else {
-            if (isset($fieldDef->resolveFn)) {
-                $resolveFn = $fieldDef->resolveFn;
-            } else if (isset($parentType->resolveFieldFn)) {
-                $resolveFn = $parentType->resolveFieldFn;
-            } else {
-                $resolveFn = self::$defaultResolveFn;
-            }
-
-            // Get the resolve function, regardless of if its result is normal
-            // or abrupt (error).
-            $result = self::resolveOrError($resolveFn, $source, $args, $info);
-
-            $result = self::completeValueCatchingError(
-                $exeContext,
-                $returnType,
-                $fieldASTs,
-                $info,
-                $result
-            );
-
-            if ($isObject) {
-                $memoized['results'][$source] = $result;
-            }
+        if ($promiseAdapter instanceof SyncPromiseAdapter) {
+            $result = $promiseAdapter->wait($result);
         }
 
         return $result;
     }
 
-    // Isolates the "ReturnOrAbrupt" behavior to not de-opt the `resolveField`
-    // function. Returns the result of resolveFn or the abrupt-return Error object.
-    private static function resolveOrError($resolveFn, $source, $args, $info)
-    {
-        try {
-            return call_user_func($resolveFn, $source, $args, $info);
-        } catch (\Exception $error) {
-            return $error;
-        }
-    }
-
-    public static function completeValueCatchingError(
-        ExecutionContext $exeContext,
-        Type $returnType,
-        $fieldASTs,
-        ResolveInfo $info,
-        $result
-    )
-    {
-        // If the field type is non-nullable, then it is resolved without any
-        // protection from errors.
-        if ($returnType instanceof NonNull) {
-            return self::completeValue($exeContext, $returnType, $fieldASTs, $info, $result);
-        }
-
-        // Otherwise, error protection is applied, logging the error and resolving
-        // a null value for this field if one is encountered.
-        try {
-            return self::completeValue($exeContext, $returnType, $fieldASTs, $info, $result);
-        } catch (Error $err) {
-            // If `completeValue` returned abruptly (threw an error), log the error
-            // and return null.
-            $exeContext->addError($err);
-            return null;
-        }
-    }
-
     /**
-     * Implements the instructions for completeValue as defined in the
-     * "Field entries" section of the spec.
+     * Same as execute(), but requires promise adapter and returns a promise which is always
+     * fulfilled with an instance of ExecutionResult and never rejected.
      *
-     * If the field type is Non-Null, then this recursively completes the value
-     * for the inner type. It throws a field error if that completion returns null,
-     * as per the "Nullability" section of the spec.
+     * Useful for async PHP platforms.
      *
-     * If the field type is a List, then this recursively completes the value
-     * for the inner type on each item in the list.
+     * @param mixed|null   $rootValue
+     * @param mixed|null   $contextValue
+     * @param mixed[]|null $variableValues
+     * @param string|null  $operationName
      *
-     * If the field type is a Scalar or Enum, ensures the completed value is a legal
-     * value of the type by calling the `serialize` method of GraphQL type
-     * definition.
+     * @return Promise
      *
-     * Otherwise, the field type expects a sub-selection set, and will complete the
-     * value by evaluating all sub-selections.
+     * @api
      */
-    private static function completeValue(ExecutionContext $exeContext, Type $returnType,/* Array<Field> */ $fieldASTs, ResolveInfo $info, &$result)
-    {
-        if ($result instanceof \Exception) {
-            throw Error::createLocatedError($result, $fieldASTs);
-        }
+    public static function promiseToExecute(
+        PromiseAdapter $promiseAdapter,
+        Schema $schema,
+        DocumentNode $documentNode,
+        $rootValue = null,
+        $contextValue = null,
+        $variableValues = null,
+        $operationName = null,
+        ?callable $fieldResolver = null
+    ) {
+        $factory = self::$implementationFactory;
 
-        // If field type is NonNull, complete for inner type, and throw field error
-        // if result is null.
-        if ($returnType instanceof NonNull) {
-            $completed = self::completeValue(
-                $exeContext,
-                $returnType->getWrappedType(),
-                $fieldASTs,
-                $info,
-                $result
-            );
-            if ($completed === null) {
-                throw new Error(
-                    'Cannot return null for non-nullable type.',
-                    $fieldASTs instanceof \ArrayObject ? $fieldASTs->getArrayCopy() : $fieldASTs
-                );
-            }
-            return $completed;
-        }
+        /** @var ExecutorImplementation $executor */
+        $executor = $factory(
+            $promiseAdapter,
+            $schema,
+            $documentNode,
+            $rootValue,
+            $contextValue,
+            $variableValues,
+            $operationName,
+            $fieldResolver ?: self::$defaultFieldResolver
+        );
 
-        // If result is null-like, return null.
-        if (null === $result) {
-            return null;
-        }
-
-        // If field type is List, complete each item in the list with the inner type
-        if ($returnType instanceof ListOfType) {
-            $itemType = $returnType->getWrappedType();
-            Utils::invariant(
-                is_array($result) || $result instanceof \Traversable,
-                'User Error: expected iterable, but did not find one.'
-            );
-
-            $tmp = [];
-            foreach ($result as $item) {
-                $tmp[] = self::completeValueCatchingError($exeContext, $itemType, $fieldASTs, $info, $item);
-            }
-            return $tmp;
-        }
-
-        // If field type is Scalar or Enum, serialize to a valid value, returning
-        // null if serialization is not possible.
-        if ($returnType instanceof ScalarType ||
-            $returnType instanceof EnumType) {
-            Utils::invariant(method_exists($returnType, 'serialize'), 'Missing serialize method on type');
-            return $returnType->serialize($result);
-        }
-
-        // Field type must be Object, Interface or Union and expect sub-selections.
-        if ($returnType instanceof ObjectType) {
-            $runtimeType = $returnType;
-        } else if ($returnType instanceof AbstractType) {
-            $runtimeType = $returnType->getObjectType($result, $info);
-
-            if ($runtimeType && !$returnType->isPossibleType($runtimeType)) {
-                throw new Error(
-                    "Runtime Object type \"$runtimeType\" is not a possible type for \"$returnType\"."
-                );
-            }
-        } else {
-            $runtimeType = null;
-        }
-
-        if (!$runtimeType) {
-            return null;
-        }
-
-        // If there is an isTypeOf predicate function, call it with the
-        // current result. If isTypeOf returns false, then raise an error rather
-        // than continuing execution.
-        if (false === $runtimeType->isTypeOf($result, $info)) {
-            throw new Error(
-                "Expected value of type $runtimeType but got: " . Utils::getVariableType($result),
-                $fieldASTs
-            );
-        }
-
-        // Collect sub-fields to execute to complete this value.
-        $subFieldASTs = new \ArrayObject();
-        $visitedFragmentNames = new \ArrayObject();
-        for ($i = 0; $i < count($fieldASTs); $i++) {
-            // Get memoized value if it exists
-            $uid = self::getFieldUid($fieldASTs[$i], $runtimeType);
-            if (isset($exeContext->memoized['collectSubFields'][$uid])) {
-                $subFieldASTs = $exeContext->memoized['collectSubFields'][$uid];
-            }
-            else {
-                $selectionSet = $fieldASTs[$i]->selectionSet;
-                if ($selectionSet) {
-                    $subFieldASTs = self::collectFields(
-                        $exeContext,
-                        $runtimeType,
-                        $selectionSet,
-                        $subFieldASTs,
-                        $visitedFragmentNames
-                    );
-                    $exeContext->memoized['collectSubFields'][$uid] = $subFieldASTs;
-                }
-            }
-        }
-
-        return self::executeFields($exeContext, $runtimeType, $result, $subFieldASTs);
+        return $executor->doExecute();
     }
 
-
     /**
      * If a resolve function is not given, then a default resolve behavior is used
-     * which takes the property of the source object of the same name as the field
+     * which takes the property of the root value of the same name as the field
      * and returns it as the result, or if it's a function, returns the result
-     * of calling that function.
+     * of calling that function while passing along args and context.
+     *
+     * @param mixed      $objectValue
+     * @param mixed[]    $args
+     * @param mixed|null $context
+     *
+     * @return mixed|null
      */
-    public static function defaultResolveFn($source, $args, ResolveInfo $info)
+    public static function defaultFieldResolver($objectValue, $args, $context, ResolveInfo $info)
     {
         $fieldName = $info->fieldName;
-        $property = null;
+        $property  = null;
 
-        if (is_array($source) || $source instanceof \ArrayAccess) {
-            if (isset($source[$fieldName])) {
-                $property = $source[$fieldName];
+        if (is_array($objectValue) || $objectValue instanceof ArrayAccess) {
+            if (isset($objectValue[$fieldName])) {
+                $property = $objectValue[$fieldName];
             }
-        } else if (is_object($source)) {
-            if (isset($source->{$fieldName})) {
-                $property = $source->{$fieldName};
+        } elseif (is_object($objectValue)) {
+            if (isset($objectValue->{$fieldName})) {
+                $property = $objectValue->{$fieldName};
             }
         }
 
-        return $property instanceof \Closure ? $property($source) : $property;
-    }
-
-    /**
-     * This method looks up the field on the given type defintion.
-     * It has special casing for the two introspection fields, __schema
-     * and __typename. __typename is special because it can always be
-     * queried as a field, even in situations where no other fields
-     * are allowed, like on a Union. __schema could get automatically
-     * added to the query type, but that would require mutating type
-     * definitions, which would cause issues.
-     *
-     * @return FieldDefinition
-     */
-    private static function getFieldDef(Schema $schema, ObjectType $parentType, $fieldName)
-    {
-        $schemaMetaFieldDef = Introspection::schemaMetaFieldDef();
-        $typeMetaFieldDef = Introspection::typeMetaFieldDef();
-        $typeNameMetaFieldDef = Introspection::typeNameMetaFieldDef();
-
-        if ($fieldName === $schemaMetaFieldDef->name && $schema->getQueryType() === $parentType) {
-            return $schemaMetaFieldDef;
-        } else if ($fieldName === $typeMetaFieldDef->name && $schema->getQueryType() === $parentType) {
-            return $typeMetaFieldDef;
-        } else if ($fieldName === $typeNameMetaFieldDef->name) {
-            return $typeNameMetaFieldDef;
-        }
-
-        $tmp = $parentType->getFields();
-        return isset($tmp[$fieldName]) ? $tmp[$fieldName] : null;
-    }
-
-    /**
-     * Get an unique identifier for a FieldAST.
-     *
-     * @param  object $fieldAST
-     * @return string
-     */
-    private static function getFieldUid($fieldAST, ObjectType $fieldType)
-    {
-        return $fieldAST->loc->start . '-' . $fieldAST->loc->end . '-' . $fieldType->name;
+        return $property instanceof Closure
+            ? $property($objectValue, $args, $context, $info)
+            : $property;
     }
 }

src/Executor/ExecutorImplementation.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Executor;
+
+use GraphQL\Executor\Promise\Promise;
+
+interface ExecutorImplementation
+{
+    /**
+     * Returns promise of {@link ExecutionResult}. Promise should always resolve, never reject.
+     */
+    public function doExecute() : Promise;
+}

src/Executor/Promise/Adapter/ReactPromiseAdapter.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Executor\Promise\Adapter;
+
+use GraphQL\Executor\Promise\Promise;
+use GraphQL\Executor\Promise\PromiseAdapter;
+use GraphQL\Utils\Utils;
+use React\Promise\Promise as ReactPromise;
+use React\Promise\PromiseInterface as ReactPromiseInterface;
+use function React\Promise\all;
+use function React\Promise\reject;
+use function React\Promise\resolve;
+
+class ReactPromiseAdapter implements PromiseAdapter
+{
+    /**
+     * @inheritdoc
+     */
+    public function isThenable($value)
+    {
+        return $value instanceof ReactPromiseInterface;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function convertThenable($thenable)
+    {
+        return new Promise($thenable, $this);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function then(Promise $promise, ?callable $onFulfilled = null, ?callable $onRejected = null)
+    {
+        /** @var ReactPromiseInterface $adoptedPromise */
+        $adoptedPromise = $promise->adoptedPromise;
+
+        return new Promise($adoptedPromise->then($onFulfilled, $onRejected), $this);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function create(callable $resolver)
+    {
+        $promise = new ReactPromise($resolver);
+
+        return new Promise($promise, $this);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function createFulfilled($value = null)
+    {
+        $promise = resolve($value);
+
+        return new Promise($promise, $this);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function createRejected($reason)
+    {
+        $promise = reject($reason);
+
+        return new Promise($promise, $this);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function all(array $promisesOrValues)
+    {
+        // TODO: rework with generators when PHP minimum required version is changed to 5.5+
+        $promisesOrValues = Utils::map(
+            $promisesOrValues,
+            static function ($item) {
+                return $item instanceof Promise ? $item->adoptedPromise : $item;
+            }
+        );
+
+        $promise = all($promisesOrValues)->then(static function ($values) use ($promisesOrValues) {
+            $orderedResults = [];
+
+            foreach ($promisesOrValues as $key => $value) {
+                $orderedResults[$key] = $values[$key];
+            }
+
+            return $orderedResults;
+        });
+
+        return new Promise($promise, $this);
+    }
+}

src/Executor/Promise/Adapter/SyncPromise.php

@@ -0,0 +1,170 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Executor\Promise\Adapter;
+
+use Exception;
+use GraphQL\Executor\ExecutionResult;
+use GraphQL\Utils\Utils;
+use SplQueue;
+use Throwable;
+use function is_object;
+use function method_exists;
+
+/**
+ * Simplistic (yet full-featured) implementation of Promises A+ spec for regular PHP `sync` mode
+ * (using queue to defer promises execution)
+ */
+class SyncPromise
+{
+    const PENDING   = 'pending';
+    const FULFILLED = 'fulfilled';
+    const REJECTED  = 'rejected';
+
+    /** @var SplQueue */
+    public static $queue;
+
+    /** @var string */
+    public $state = self::PENDING;
+
+    /** @var ExecutionResult|Throwable */
+    public $result;
+
+    /**
+     * Promises created in `then` method of this promise and awaiting for resolution of this promise
+     *
+     * @var mixed[][]
+     */
+    private $waiting = [];
+
+    public static function runQueue() : void
+    {
+        $q = self::$queue;
+        while ($q !== null && ! $q->isEmpty()) {
+            $task = $q->dequeue();
+            $task();
+        }
+    }
+
+    public function resolve($value) : self
+    {
+        switch ($this->state) {
+            case self::PENDING:
+                if ($value === $this) {
+                    throw new Exception('Cannot resolve promise with self');
+                }
+                if (is_object($value) && method_exists($value, 'then')) {
+                    $value->then(
+                        function ($resolvedValue) {
+                            $this->resolve($resolvedValue);
+                        },
+                        function ($reason) {
+                            $this->reject($reason);
+                        }
+                    );
+
+                    return $this;
+                }
+
+                $this->state  = self::FULFILLED;
+                $this->result = $value;
+                $this->enqueueWaitingPromises();
+                break;
+            case self::FULFILLED:
+                if ($this->result !== $value) {
+                    throw new Exception('Cannot change value of fulfilled promise');
+                }
+                break;
+            case self::REJECTED:
+                throw new Exception('Cannot resolve rejected promise');
+        }
+
+        return $this;
+    }
+
+    public function reject($reason) : self
+    {
+        if (! $reason instanceof Exception && ! $reason instanceof Throwable) {
+            throw new Exception('SyncPromise::reject() has to be called with an instance of \Throwable');
+        }
+
+        switch ($this->state) {
+            case self::PENDING:
+                $this->state  = self::REJECTED;
+                $this->result = $reason;
+                $this->enqueueWaitingPromises();
+                break;
+            case self::REJECTED:
+                if ($reason !== $this->result) {
+                    throw new Exception('Cannot change rejection reason');
+                }
+                break;
+            case self::FULFILLED:
+                throw new Exception('Cannot reject fulfilled promise');
+        }
+
+        return $this;
+    }
+
+    private function enqueueWaitingPromises() : void
+    {
+        Utils::invariant(
+            $this->state !== self::PENDING,
+            'Cannot enqueue derived promises when parent is still pending'
+        );
+
+        foreach ($this->waiting as $descriptor) {
+            self::getQueue()->enqueue(function () use ($descriptor) {
+                /** @var self $promise */
+                [$promise, $onFulfilled, $onRejected] = $descriptor;
+
+                if ($this->state === self::FULFILLED) {
+                    try {
+                        $promise->resolve($onFulfilled === null ? $this->result : $onFulfilled($this->result));
+                    } catch (Exception $e) {
+                        $promise->reject($e);
+                    } catch (Throwable $e) {
+                        $promise->reject($e);
+                    }
+                } elseif ($this->state === self::REJECTED) {
+                    try {
+                        if ($onRejected === null) {
+                            $promise->reject($this->result);
+                        } else {
+                            $promise->resolve($onRejected($this->result));
+                        }
+                    } catch (Exception $e) {
+                        $promise->reject($e);
+                    } catch (Throwable $e) {
+                        $promise->reject($e);
+                    }
+                }
+            });
+        }
+        $this->waiting = [];
+    }
+
+    public static function getQueue() : SplQueue
+    {
+        return self::$queue ?: self::$queue = new SplQueue();
+    }
+
+    public function then(?callable $onFulfilled = null, ?callable $onRejected = null)
+    {
+        if ($this->state === self::REJECTED && $onRejected === null) {
+            return $this;
+        }
+        if ($this->state === self::FULFILLED && $onFulfilled === null) {
+            return $this;
+        }
+        $tmp             = new self();
+        $this->waiting[] = [$tmp, $onFulfilled, $onRejected];
+
+        if ($this->state !== self::PENDING) {
+            $this->enqueueWaitingPromises();
+        }
+
+        return $tmp;
+    }
+}

src/Executor/Promise/Adapter/SyncPromiseAdapter.php

@@ -0,0 +1,185 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Executor\Promise\Adapter;
+
+use Exception;
+use GraphQL\Deferred;
+use GraphQL\Error\InvariantViolation;
+use GraphQL\Executor\ExecutionResult;
+use GraphQL\Executor\Promise\Promise;
+use GraphQL\Executor\Promise\PromiseAdapter;
+use GraphQL\Utils\Utils;
+use Throwable;
+use function count;
+
+/**
+ * Allows changing order of field resolution even in sync environments
+ * (by leveraging queue of deferreds and promises)
+ */
+class SyncPromiseAdapter implements PromiseAdapter
+{
+    /**
+     * @inheritdoc
+     */
+    public function isThenable($value)
+    {
+        return $value instanceof Deferred;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function convertThenable($thenable)
+    {
+        if (! $thenable instanceof Deferred) {
+            throw new InvariantViolation('Expected instance of GraphQL\Deferred, got ' . Utils::printSafe($thenable));
+        }
+
+        return new Promise($thenable->promise, $this);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function then(Promise $promise, ?callable $onFulfilled = null, ?callable $onRejected = null)
+    {
+        /** @var SyncPromise $adoptedPromise */
+        $adoptedPromise = $promise->adoptedPromise;
+
+        return new Promise($adoptedPromise->then($onFulfilled, $onRejected), $this);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function create(callable $resolver)
+    {
+        $promise = new SyncPromise();
+
+        try {
+            $resolver(
+                [
+                    $promise,
+                    'resolve',
+                ],
+                [
+                    $promise,
+                    'reject',
+                ]
+            );
+        } catch (Exception $e) {
+            $promise->reject($e);
+        } catch (Throwable $e) {
+            $promise->reject($e);
+        }
+
+        return new Promise($promise, $this);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function createFulfilled($value = null)
+    {
+        $promise = new SyncPromise();
+
+        return new Promise($promise->resolve($value), $this);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function createRejected($reason)
+    {
+        $promise = new SyncPromise();
+
+        return new Promise($promise->reject($reason), $this);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function all(array $promisesOrValues)
+    {
+        $all = new SyncPromise();
+
+        $total  = count($promisesOrValues);
+        $count  = 0;
+        $result = [];
+
+        foreach ($promisesOrValues as $index => $promiseOrValue) {
+            if ($promiseOrValue instanceof Promise) {
+                $result[$index] = null;
+                $promiseOrValue->then(
+                    static function ($value) use ($index, &$count, $total, &$result, $all) {
+                        $result[$index] = $value;
+                        $count++;
+                        if ($count < $total) {
+                            return;
+                        }
+
+                        $all->resolve($result);
+                    },
+                    [$all, 'reject']
+                );
+            } else {
+                $result[$index] = $promiseOrValue;
+                $count++;
+            }
+        }
+        if ($count === $total) {
+            $all->resolve($result);
+        }
+
+        return new Promise($all, $this);
+    }
+
+    /**
+     * Synchronously wait when promise completes
+     *
+     * @return ExecutionResult
+     */
+    public function wait(Promise $promise)
+    {
+        $this->beforeWait($promise);
+        $dfdQueue     = Deferred::getQueue();
+        $promiseQueue = SyncPromise::getQueue();
+
+        while ($promise->adoptedPromise->state === SyncPromise::PENDING &&
+            ! ($dfdQueue->isEmpty() && $promiseQueue->isEmpty())
+        ) {
+            Deferred::runQueue();
+            SyncPromise::runQueue();
+            $this->onWait($promise);
+        }
+
+        /** @var SyncPromise $syncPromise */
+        $syncPromise = $promise->adoptedPromise;
+
+        if ($syncPromise->state === SyncPromise::FULFILLED) {
+            return $syncPromise->result;
+        }
+
+        if ($syncPromise->state === SyncPromise::REJECTED) {
+            throw $syncPromise->result;
+        }
+
+        throw new InvariantViolation('Could not resolve promise');
+    }
+
+    /**
+     * Execute just before starting to run promise completion
+     */
+    protected function beforeWait(Promise $promise)
+    {
+    }
+
+    /**
+     * Execute while running promise completion
+     */
+    protected function onWait(Promise $promise)
+    {
+    }
+}

src/Executor/Promise/Promise.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Executor\Promise;
+
+use GraphQL\Executor\Promise\Adapter\SyncPromise;
+use GraphQL\Utils\Utils;
+use React\Promise\Promise as ReactPromise;
+
+/**
+ * Convenience wrapper for promises represented by Promise Adapter
+ */
+class Promise
+{
+    /** @var SyncPromise|ReactPromise */
+    public $adoptedPromise;
+
+    /** @var PromiseAdapter */
+    private $adapter;
+
+    /**
+     * @param mixed $adoptedPromise
+     */
+    public function __construct($adoptedPromise, PromiseAdapter $adapter)
+    {
+        Utils::invariant(! $adoptedPromise instanceof self, 'Expecting promise from adapted system, got ' . self::class);
+
+        $this->adapter        = $adapter;
+        $this->adoptedPromise = $adoptedPromise;
+    }
+
+    /**
+     * @return Promise
+     */
+    public function then(?callable $onFulfilled = null, ?callable $onRejected = null)
+    {
+        return $this->adapter->then($this, $onFulfilled, $onRejected);
+    }
+}

src/Executor/Promise/PromiseAdapter.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Executor\Promise;
+
+use Throwable;
+
+/**
+ * Provides a means for integration of async PHP platforms ([related docs](data-fetching.md#async-php))
+ */
+interface PromiseAdapter
+{
+    /**
+     * Return true if the value is a promise or a deferred of the underlying platform
+     *
+     * @param mixed $value
+     *
+     * @return bool
+     *
+     * @api
+     */
+    public function isThenable($value);
+
+    /**
+     * Converts thenable of the underlying platform into GraphQL\Executor\Promise\Promise instance
+     *
+     * @param object $thenable
+     *
+     * @return Promise
+     *
+     * @api
+     */
+    public function convertThenable($thenable);
+
+    /**
+     * Accepts our Promise wrapper, extracts adopted promise out of it and executes actual `then` logic described
+     * in Promises/A+ specs. Then returns new wrapped instance of GraphQL\Executor\Promise\Promise.
+     *
+     * @return Promise
+     *
+     * @api
+     */
+    public function then(Promise $promise, ?callable $onFulfilled = null, ?callable $onRejected = null);
+
+    /**
+     * Creates a Promise
+     *
+     * Expected resolver signature:
+     *     function(callable $resolve, callable $reject)
+     *
+     * @return Promise
+     *
+     * @api
+     */
+    public function create(callable $resolver);
+
+    /**
+     * Creates a fulfilled Promise for a value if the value is not a promise.
+     *
+     * @param mixed $value
+     *
+     * @return Promise
+     *
+     * @api
+     */
+    public function createFulfilled($value = null);
+
+    /**
+     * Creates a rejected promise for a reason if the reason is not a promise. If
+     * the provided reason is a promise, then it is returned as-is.
+     *
+     * @param Throwable $reason
+     *
+     * @return Promise
+     *
+     * @api
+     */
+    public function createRejected($reason);
+
+    /**
+     * Given an array of promises (or values), returns a promise that is fulfilled when all the
+     * items in the array are fulfilled.
+     *
+     * @param Promise[]|mixed[] $promisesOrValues Promises or values.
+     *
+     * @return Promise
+     *
+     * @api
+     */
+    public function all(array $promisesOrValues);
+}

src/Executor/Values.php

@@ -1,30 +1,38 @@
 <?php
+
+declare(strict_types=1);
+
 namespace GraphQL\Executor;
 
-
-use GraphQL\Error;
-use GraphQL\Language\AST\Argument;
-use GraphQL\Language\AST\ListType;
-use GraphQL\Language\AST\ListValue;
+use GraphQL\Error\Error;
+use GraphQL\Language\AST\ArgumentNode;
+use GraphQL\Language\AST\DirectiveNode;
+use GraphQL\Language\AST\EnumValueDefinitionNode;
+use GraphQL\Language\AST\FieldDefinitionNode;
+use GraphQL\Language\AST\FieldNode;
+use GraphQL\Language\AST\FragmentSpreadNode;
+use GraphQL\Language\AST\InlineFragmentNode;
 use GraphQL\Language\AST\Node;
-use GraphQL\Language\AST\ObjectValue;
-use GraphQL\Language\AST\Value;
-use GraphQL\Language\AST\Variable;
-use GraphQL\Language\AST\VariableDefinition;
+use GraphQL\Language\AST\NodeList;
+use GraphQL\Language\AST\ValueNode;
+use GraphQL\Language\AST\VariableDefinitionNode;
+use GraphQL\Language\AST\VariableNode;
 use GraphQL\Language\Printer;
-use GraphQL\Schema;
 use GraphQL\Type\Definition\Directive;
-use GraphQL\Type\Definition\EnumType;
-use GraphQL\Type\Definition\FieldArgument;
 use GraphQL\Type\Definition\FieldDefinition;
-use GraphQL\Type\Definition\InputObjectType;
 use GraphQL\Type\Definition\InputType;
-use GraphQL\Type\Definition\ListOfType;
 use GraphQL\Type\Definition\NonNull;
-use GraphQL\Type\Definition\ObjectType;
-use GraphQL\Type\Definition\ScalarType;
 use GraphQL\Type\Definition\Type;
-use GraphQL\Utils;
+use GraphQL\Type\Schema;
+use GraphQL\Utils\AST;
+use GraphQL\Utils\TypeInfo;
+use GraphQL\Utils\Utils;
+use GraphQL\Utils\Value;
+use stdClass;
+use Throwable;
+use function array_key_exists;
+use function array_map;
+use function sprintf;
 
 class Values
 {
@@ -33,254 +41,239 @@ class Values
      * variable definitions and arbitrary input. If the input cannot be coerced
      * to match the variable definitions, a Error will be thrown.
      *
-     * @param Schema $schema
-     * @param VariableDefinition[] $definitionASTs
-     * @param array $inputs
-     * @return array
-     * @throws Error
+     * @param VariableDefinitionNode[] $varDefNodes
+     * @param mixed[]                  $inputs
+     *
+     * @return mixed[]
      */
-    public static function getVariableValues(Schema $schema, $definitionASTs, array $inputs)
+    public static function getVariableValues(Schema $schema, $varDefNodes, array $inputs)
     {
-        $values = [];
-        foreach ($definitionASTs as $defAST) {
-            $varName = $defAST->variable->name->value;
-            $values[$varName] = self::getvariableValue($schema, $defAST, isset($inputs[$varName]) ? $inputs[$varName] : null);
+        $errors        = [];
+        $coercedValues = [];
+        foreach ($varDefNodes as $varDefNode) {
+            $varName = $varDefNode->variable->name->value;
+            /** @var InputType|Type $varType */
+            $varType = TypeInfo::typeFromAST($schema, $varDefNode->type);
+
+            if (Type::isInputType($varType)) {
+                if (array_key_exists($varName, $inputs)) {
+                    $value   = $inputs[$varName];
+                    $coerced = Value::coerceValue($value, $varType, $varDefNode);
+                    /** @var Error[] $coercionErrors */
+                    $coercionErrors = $coerced['errors'];
+                    if (empty($coercionErrors)) {
+                        $coercedValues[$varName] = $coerced['value'];
+                    } else {
+                        $messagePrelude = sprintf(
+                            'Variable "$%s" got invalid value %s; ',
+                            $varName,
+                            Utils::printSafeJson($value)
+                        );
+
+                        foreach ($coercionErrors as $error) {
+                            $errors[] = new Error(
+                                $messagePrelude . $error->getMessage(),
+                                $error->getNodes(),
+                                $error->getSource(),
+                                $error->getPositions(),
+                                $error->getPath(),
+                                $error,
+                                $error->getExtensions()
+                            );
+                        }
+                    }
+                } else {
+                    if ($varType instanceof NonNull) {
+                        $errors[] = new Error(
+                            sprintf(
+                                'Variable "$%s" of required type "%s" was not provided.',
+                                $varName,
+                                $varType
+                            ),
+                            [$varDefNode]
+                        );
+                    } elseif ($varDefNode->defaultValue !== null) {
+                        $coercedValues[$varName] = AST::valueFromAST($varDefNode->defaultValue, $varType);
+                    }
+                }
+            } else {
+                $errors[] = new Error(
+                    sprintf(
+                        'Variable "$%s" expected value of type "%s" which cannot be used as an input type.',
+                        $varName,
+                        Printer::doPrint($varDefNode->type)
+                    ),
+                    [$varDefNode->type]
+                );
+            }
         }
-        return $values;
+
+        if (! empty($errors)) {
+            return [$errors, null];
+        }
+
+        return [null, $coercedValues];
+    }
+
+    /**
+     * Prepares an object map of argument values given a directive definition
+     * and a AST node which may contain directives. Optionally also accepts a map
+     * of variable values.
+     *
+     * If the directive does not exist on the node, returns undefined.
+     *
+     * @param FragmentSpreadNode|FieldNode|InlineFragmentNode|EnumValueDefinitionNode|FieldDefinitionNode $node
+     * @param mixed[]|null                                                                                $variableValues
+     *
+     * @return mixed[]|null
+     */
+    public static function getDirectiveValues(Directive $directiveDef, $node, $variableValues = null)
+    {
+        if (isset($node->directives) && $node->directives instanceof NodeList) {
+            $directiveNode = Utils::find(
+                $node->directives,
+                static function (DirectiveNode $directive) use ($directiveDef) {
+                    return $directive->name->value === $directiveDef->name;
+                }
+            );
+
+            if ($directiveNode !== null) {
+                return self::getArgumentValues($directiveDef, $directiveNode, $variableValues);
+            }
+        }
+
+        return null;
     }
 
     /**
      * Prepares an object map of argument values given a list of argument
      * definitions and list of argument AST nodes.
      *
-     * @param FieldArgument[] $argDefs
-     * @param Argument[] $argASTs
-     * @param $variableValues
-     * @return array
+     * @param FieldDefinition|Directive $def
+     * @param FieldNode|DirectiveNode   $node
+     * @param mixed[]                   $variableValues
+     *
+     * @return mixed[]
+     *
+     * @throws Error
      */
-    public static function getArgumentValues($argDefs, $argASTs, $variableValues)
+    public static function getArgumentValues($def, $node, $variableValues = null)
     {
-        if (!$argDefs) {
+        if (empty($def->args)) {
             return [];
         }
-        $argASTMap = $argASTs ? Utils::keyMap($argASTs, function ($arg) {
-            return $arg->name->value;
-        }) : [];
-        $result = [];
-        foreach ($argDefs as $argDef) {
-            $name = $argDef->name;
-            $valueAST = isset($argASTMap[$name]) ? $argASTMap[$name]->value : null;
-            $value = self::valueFromAST($valueAST, $argDef->getType(), $variableValues);
 
-            if (null === $value) {
-                $value = $argDef->defaultValue;
-            }
-            if (null !== $value) {
-                $result[$name] = $value;
-            }
-        }
-        return $result;
-    }
-
-    public static function valueFromAST($valueAST, InputType $type, $variables = null)
-    {
-        if ($type instanceof NonNull) {
-            return self::valueFromAST($valueAST, $type->getWrappedType(), $variables);
+        $argumentNodes = $node->arguments;
+        if (empty($argumentNodes)) {
+            return [];
         }
 
-        if (!$valueAST) {
-            return null;
+        $argumentValueMap = [];
+        foreach ($argumentNodes as $argumentNode) {
+            $argumentValueMap[$argumentNode->name->value] = $argumentNode->value;
         }
 
-        if ($valueAST instanceof Variable) {
-            $variableName = $valueAST->name->value;
-
-            if (!$variables || !isset($variables[$variableName])) {
-                return null;
-            }
-            return $variables[$variableName];
-        }
-
-        if ($type instanceof ListOfType) {
-            $itemType = $type->getWrappedType();
-            if ($valueAST instanceof ListValue) {
-                return array_map(function($itemAST) use ($itemType, $variables) {
-                    return Values::valueFromAST($itemAST, $itemType, $variables);
-                }, $valueAST->values);
-            } else {
-                return [self::valueFromAST($valueAST, $itemType, $variables)];
-            }
-        }
-
-        if ($type instanceof InputObjectType) {
-            $fields = $type->getFields();
-            if (!$valueAST instanceof ObjectValue) {
-                return null;
-            }
-            $fieldASTs = Utils::keyMap($valueAST->fields, function($field) {return $field->name->value;});
-            $values = [];
-            foreach ($fields as $field) {
-                $fieldAST = isset($fieldASTs[$field->name]) ? $fieldASTs[$field->name] : null;
-                $fieldValue = self::valueFromAST($fieldAST ? $fieldAST->value : null, $field->getType(), $variables);
-
-                if (null === $fieldValue) {
-                    $fieldValue = $field->defaultValue;
-                }
-                if (null !== $fieldValue) {
-                    $values[$field->name] = $fieldValue;
-                }
-            }
-            return $values;
-        }
-
-        Utils::invariant($type instanceof ScalarType || $type instanceof EnumType, 'Must be input type');
-        return $type->parseLiteral($valueAST);
+        return static::getArgumentValuesForMap($def, $argumentValueMap, $variableValues, $node);
     }
 
     /**
-     * Given a variable definition, and any value of input, return a value which
-     * adheres to the variable definition, or throw an error.
-     */
-    private static function getVariableValue(Schema $schema, VariableDefinition $definitionAST, $input)
-    {
-        $type = Utils\TypeInfo::typeFromAST($schema, $definitionAST->type);
-        $variable = $definitionAST->variable;
-
-        if (!$type || !Type::isInputType($type)) {
-            $printed = Printer::doPrint($definitionAST->type);
-            throw new Error(
-                "Variable \"\${$variable->name->value}\" expected value of type " .
-                "\"$printed\" which cannot be used as an input type.",
-                [ $definitionAST ]
-            );
-        }
-        if (self::isValidValue($input, $type)) {
-            if (null === $input) {
-                $defaultValue = $definitionAST->defaultValue;
-                if ($defaultValue) {
-                    return self::valueFromAST($defaultValue, $type);
-                }
-            }
-            return self::coerceValue($type, $input);
-        }
-
-        throw new Error(
-            "Variable \${$definitionAST->variable->name->value} expected value of type " .
-            Printer::doPrint($definitionAST->type) . " but got: " . json_encode($input) . '.',
-            [$definitionAST]
-        );
-    }
-
-
-    /**
-     * Given a PHP value and a GraphQL type, determine if the value will be
-     * accepted for that type. This is primarily useful for validating the
-     * runtime values of query variables.
+     * @param FieldDefinition|Directive $fieldDefinition
+     * @param ArgumentNode[]            $argumentValueMap
+     * @param mixed[]                   $variableValues
+     * @param Node|null                 $referenceNode
      *
-     * @param $value
-     * @param Type $type
-     * @return bool
+     * @return mixed[]
+     *
+     * @throws Error
      */
-    private static function isValidValue($value, Type $type)
+    public static function getArgumentValuesForMap($fieldDefinition, $argumentValueMap, $variableValues = null, $referenceNode = null)
     {
-        if ($type instanceof NonNull) {
-            if (null === $value) {
-                return false;
-            }
-            return self::isValidValue($value, $type->getWrappedType());
-        }
+        $argumentDefinitions = $fieldDefinition->args;
+        $coercedValues       = [];
 
-        if ($value === null) {
-            return true;
-        }
+        foreach ($argumentDefinitions as $argumentDefinition) {
+            $name              = $argumentDefinition->name;
+            $argType           = $argumentDefinition->getType();
+            $argumentValueNode = $argumentValueMap[$name] ?? null;
 
-        if ($type instanceof ListOfType) {
-            $itemType = $type->getWrappedType();
-            if (is_array($value)) {
-                foreach ($value as $item) {
-                    if (!self::isValidValue($item, $itemType)) {
-                        return false;
-                    }
+            if ($argumentValueNode === null) {
+                if ($argumentDefinition->defaultValueExists()) {
+                    $coercedValues[$name] = $argumentDefinition->defaultValue;
+                } elseif ($argType instanceof NonNull) {
+                    throw new Error(
+                        'Argument "' . $name . '" of required type ' .
+                        '"' . Utils::printSafe($argType) . '" was not provided.',
+                        $referenceNode
+                    );
+                }
+            } elseif ($argumentValueNode instanceof VariableNode) {
+                $variableName = $argumentValueNode->name->value;
+
+                if ($variableValues !== null && array_key_exists($variableName, $variableValues)) {
+                    // Note: this does not check that this variable value is correct.
+                    // This assumes that this query has been validated and the variable
+                    // usage here is of the correct type.
+                    $coercedValues[$name] = $variableValues[$variableName];
+                } elseif ($argumentDefinition->defaultValueExists()) {
+                    $coercedValues[$name] = $argumentDefinition->defaultValue;
+                } elseif ($argType instanceof NonNull) {
+                    throw new Error(
+                        'Argument "' . $name . '" of required type "' . Utils::printSafe($argType) . '" was ' .
+                        'provided the variable "$' . $variableName . '" which was not provided ' .
+                        'a runtime value.',
+                        [$argumentValueNode]
+                    );
                 }
-                return true;
             } else {
-                return self::isValidValue($value, $itemType);
-            }
-        }
-
-        if ($type instanceof InputObjectType) {
-            if (!is_array($value)) {
-                return false;
-            }
-            $fields = $type->getFields();
-            $fieldMap = [];
-
-            // Ensure every defined field is valid.
-            foreach ($fields as $fieldName => $field) {
-                /** @var FieldDefinition $field */
-                if (!self::isValidValue(isset($value[$fieldName]) ? $value[$fieldName] : null, $field->getType())) {
-                    return false;
+                $valueNode    = $argumentValueNode;
+                $coercedValue = AST::valueFromAST($valueNode, $argType, $variableValues);
+                if (Utils::isInvalid($coercedValue)) {
+                    // Note: ValuesOfCorrectType validation should catch this before
+                    // execution. This is a runtime check to ensure execution does not
+                    // continue with an invalid argument value.
+                    throw new Error(
+                        'Argument "' . $name . '" has invalid value ' . Printer::doPrint($valueNode) . '.',
+                        [$argumentValueNode]
+                    );
                 }
-                $fieldMap[$field->name] = $field;
+                $coercedValues[$name] = $coercedValue;
             }
-
-            // Ensure every provided field is defined.
-            $diff = array_diff_key($value, $fieldMap);
-
-            if (!empty($diff)) {
-                return false;
-            }
-
-            return true;
         }
 
-        Utils::invariant($type instanceof ScalarType || $type instanceof EnumType, 'Must be input type');
-        return null !== $type->parseValue($value);
+        return $coercedValues;
     }
 
     /**
-     * Given a type and any value, return a runtime value coerced to match the type.
+     * @deprecated as of 8.0 (Moved to \GraphQL\Utils\AST::valueFromAST)
+     *
+     * @param ValueNode    $valueNode
+     * @param mixed[]|null $variables
+     *
+     * @return mixed[]|stdClass|null
      */
-    private static function coerceValue(Type $type, $value)
+    public static function valueFromAST($valueNode, InputType $type, ?array $variables = null)
     {
-        if ($type instanceof NonNull) {
-            // Note: we're not checking that the result of coerceValue is non-null.
-            // We only call this function after calling isValidValue.
-            return self::coerceValue($type->getWrappedType(), $value);
-        }
+        return AST::valueFromAST($valueNode, $type, $variables);
+    }
 
-        if (null === $value) {
-            return null;
-        }
+    /**
+     * @deprecated as of 0.12 (Use coerceValue() directly for richer information)
+     *
+     * @param mixed[] $value
+     *
+     * @return string[]
+     */
+    public static function isValidPHPValue($value, InputType $type)
+    {
+        $errors = Value::coerceValue($value, $type)['errors'];
 
-        if ($type instanceof ListOfType) {
-            $itemType = $type->getWrappedType();
-            // TODO: support iterable input
-            if (is_array($value)) {
-                return array_map(function ($item) use ($itemType) {
-                    return Values::coerceValue($itemType, $item);
-                }, $value);
-            } else {
-                return [self::coerceValue($itemType, $value)];
-            }
-        }
-
-        if ($type instanceof InputObjectType) {
-            $fields = $type->getFields();
-            $obj = [];
-            foreach ($fields as $fieldName => $field) {
-                $fieldValue = self::coerceValue($field->getType(), isset($value[$fieldName]) ? $value[$fieldName] : null);
-                if (null === $fieldValue) {
-                    $fieldValue = $field->defaultValue;
-                }
-                if (null !== $fieldValue) {
-                    $obj[$fieldName] = $fieldValue;
-                }
-            }
-            return $obj;
-
-        }
-        Utils::invariant($type instanceof ScalarType || $type instanceof EnumType, 'Must be input type');
-        return $type->parseValue($value);
+        return $errors
+            ? array_map(
+                static function (Throwable $error) {
+                    return $error->getMessage();
+                },
+                $errors
+            )
+            : [];
     }
 }

src/Experimental/Executor/Collector.php

@@ -0,0 +1,283 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Experimental\Executor;
+
+use Generator;
+use GraphQL\Error\Error;
+use GraphQL\Language\AST\DefinitionNode;
+use GraphQL\Language\AST\DocumentNode;
+use GraphQL\Language\AST\FieldNode;
+use GraphQL\Language\AST\FragmentDefinitionNode;
+use GraphQL\Language\AST\FragmentSpreadNode;
+use GraphQL\Language\AST\InlineFragmentNode;
+use GraphQL\Language\AST\Node;
+use GraphQL\Language\AST\NodeKind;
+use GraphQL\Language\AST\OperationDefinitionNode;
+use GraphQL\Language\AST\SelectionSetNode;
+use GraphQL\Language\AST\ValueNode;
+use GraphQL\Type\Definition\AbstractType;
+use GraphQL\Type\Definition\Directive;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Introspection;
+use GraphQL\Type\Schema;
+use function sprintf;
+
+/**
+ * @internal
+ */
+class Collector
+{
+    /** @var Schema */
+    private $schema;
+
+    /** @var Runtime */
+    private $runtime;
+
+    /** @var OperationDefinitionNode|null */
+    public $operation = null;
+
+    /** @var FragmentDefinitionNode[] */
+    public $fragments = [];
+
+    /** @var ObjectType|null */
+    public $rootType;
+
+    /** @var FieldNode[][] */
+    private $fields;
+
+    /** @var string[] */
+    private $visitedFragments;
+
+    public function __construct(Schema $schema, Runtime $runtime)
+    {
+        $this->schema  = $schema;
+        $this->runtime = $runtime;
+    }
+
+    public function initialize(DocumentNode $documentNode, ?string $operationName = null)
+    {
+        $hasMultipleAssumedOperations = false;
+
+        foreach ($documentNode->definitions as $definitionNode) {
+            /** @var DefinitionNode|Node $definitionNode */
+
+            if ($definitionNode instanceof OperationDefinitionNode) {
+                /** @var OperationDefinitionNode $definitionNode */
+                if ($operationName === null && $this->operation !== null) {
+                    $hasMultipleAssumedOperations = true;
+                }
+                if ($operationName === null ||
+                    (isset($definitionNode->name) && $definitionNode->name->value === $operationName)
+                ) {
+                    $this->operation = $definitionNode;
+                }
+            } elseif ($definitionNode instanceof FragmentDefinitionNode) {
+                /** @var FragmentDefinitionNode $definitionNode */
+                $this->fragments[$definitionNode->name->value] = $definitionNode;
+            }
+        }
+
+        if ($this->operation === null) {
+            if ($operationName !== null) {
+                $this->runtime->addError(new Error(sprintf('Unknown operation named "%s".', $operationName)));
+            } else {
+                $this->runtime->addError(new Error('Must provide an operation.'));
+            }
+
+            return;
+        }
+
+        if ($hasMultipleAssumedOperations) {
+            $this->runtime->addError(new Error('Must provide operation name if query contains multiple operations.'));
+
+            return;
+        }
+
+        if ($this->operation->operation === 'query') {
+            $this->rootType = $this->schema->getQueryType();
+        } elseif ($this->operation->operation === 'mutation') {
+            $this->rootType = $this->schema->getMutationType();
+        } elseif ($this->operation->operation === 'subscription') {
+            $this->rootType = $this->schema->getSubscriptionType();
+        } else {
+            $this->runtime->addError(new Error(sprintf('Cannot initialize collector with operation type "%s".', $this->operation->operation)));
+        }
+    }
+
+    /**
+     * @return Generator
+     */
+    public function collectFields(ObjectType $runtimeType, ?SelectionSetNode $selectionSet)
+    {
+        $this->fields           = [];
+        $this->visitedFragments = [];
+
+        $this->doCollectFields($runtimeType, $selectionSet);
+
+        foreach ($this->fields as $resultName => $fieldNodes) {
+            $fieldNode = $fieldNodes[0];
+            $fieldName = $fieldNode->name->value;
+
+            $argumentValueMap = null;
+            if (! empty($fieldNode->arguments)) {
+                foreach ($fieldNode->arguments as $argumentNode) {
+                    $argumentValueMap                             = $argumentValueMap ?? [];
+                    $argumentValueMap[$argumentNode->name->value] = $argumentNode->value;
+                }
+            }
+
+            if ($fieldName !== Introspection::TYPE_NAME_FIELD_NAME &&
+                ! ($runtimeType === $this->schema->getQueryType() && ($fieldName === Introspection::SCHEMA_FIELD_NAME || $fieldName === Introspection::TYPE_FIELD_NAME)) &&
+                ! $runtimeType->hasField($fieldName)
+            ) {
+                // do not emit error
+                continue;
+            }
+
+            yield new CoroutineContextShared($fieldNodes, $fieldName, $resultName, $argumentValueMap);
+        }
+    }
+
+    private function doCollectFields(ObjectType $runtimeType, ?SelectionSetNode $selectionSet)
+    {
+        if ($selectionSet === null) {
+            return;
+        }
+
+        foreach ($selectionSet->selections as $selection) {
+            /** @var FieldNode|FragmentSpreadNode|InlineFragmentNode $selection */
+
+            if (! empty($selection->directives)) {
+                foreach ($selection->directives as $directiveNode) {
+                    if ($directiveNode->name->value === Directive::SKIP_NAME) {
+                        /** @var ValueNode|null $condition */
+                        $condition = null;
+                        foreach ($directiveNode->arguments as $argumentNode) {
+                            if ($argumentNode->name->value === Directive::IF_ARGUMENT_NAME) {
+                                $condition = $argumentNode->value;
+                                break;
+                            }
+                        }
+
+                        if ($condition === null) {
+                            $this->runtime->addError(new Error(
+                                sprintf('@%s directive is missing "%s" argument.', Directive::SKIP_NAME, Directive::IF_ARGUMENT_NAME),
+                                $selection
+                            ));
+                        } else {
+                            if ($this->runtime->evaluate($condition, Type::boolean()) === true) {
+                                continue 2; // !!! advances outer loop
+                            }
+                        }
+                    } elseif ($directiveNode->name->value === Directive::INCLUDE_NAME) {
+                        /** @var ValueNode|null $condition */
+                        $condition = null;
+                        foreach ($directiveNode->arguments as $argumentNode) {
+                            if ($argumentNode->name->value === Directive::IF_ARGUMENT_NAME) {
+                                $condition = $argumentNode->value;
+                                break;
+                            }
+                        }
+
+                        if ($condition === null) {
+                            $this->runtime->addError(new Error(
+                                sprintf('@%s directive is missing "%s" argument.', Directive::INCLUDE_NAME, Directive::IF_ARGUMENT_NAME),
+                                $selection
+                            ));
+                        } else {
+                            if ($this->runtime->evaluate($condition, Type::boolean()) !== true) {
+                                continue 2; // !!! advances outer loop
+                            }
+                        }
+                    }
+                }
+            }
+
+            if ($selection instanceof FieldNode) {
+                /** @var FieldNode $selection */
+
+                $resultName = $selection->alias === null ? $selection->name->value : $selection->alias->value;
+
+                if (! isset($this->fields[$resultName])) {
+                    $this->fields[$resultName] = [];
+                }
+
+                $this->fields[$resultName][] = $selection;
+            } elseif ($selection instanceof FragmentSpreadNode) {
+                /** @var FragmentSpreadNode $selection */
+
+                $fragmentName = $selection->name->value;
+
+                if (isset($this->visitedFragments[$fragmentName])) {
+                    continue;
+                }
+
+                if (! isset($this->fragments[$fragmentName])) {
+                    $this->runtime->addError(new Error(
+                        sprintf('Fragment "%s" does not exist.', $fragmentName),
+                        $selection
+                    ));
+                    continue;
+                }
+
+                $this->visitedFragments[$fragmentName] = true;
+
+                $fragmentDefinition = $this->fragments[$fragmentName];
+                $conditionTypeName  = $fragmentDefinition->typeCondition->name->value;
+
+                if (! $this->schema->hasType($conditionTypeName)) {
+                    $this->runtime->addError(new Error(
+                        sprintf('Cannot spread fragment "%s", type "%s" does not exist.', $fragmentName, $conditionTypeName),
+                        $selection
+                    ));
+                    continue;
+                }
+
+                $conditionType = $this->schema->getType($conditionTypeName);
+
+                if ($conditionType instanceof ObjectType) {
+                    if ($runtimeType->name !== $conditionType->name) {
+                        continue;
+                    }
+                } elseif ($conditionType instanceof AbstractType) {
+                    if (! $this->schema->isPossibleType($conditionType, $runtimeType)) {
+                        continue;
+                    }
+                }
+
+                $this->doCollectFields($runtimeType, $fragmentDefinition->selectionSet);
+            } elseif ($selection instanceof InlineFragmentNode) {
+                /** @var InlineFragmentNode $selection */
+
+                if ($selection->typeCondition !== null) {
+                    $conditionTypeName = $selection->typeCondition->name->value;
+
+                    if (! $this->schema->hasType($conditionTypeName)) {
+                        $this->runtime->addError(new Error(
+                            sprintf('Cannot spread inline fragment, type "%s" does not exist.', $conditionTypeName),
+                            $selection
+                        ));
+                        continue;
+                    }
+
+                    $conditionType = $this->schema->getType($conditionTypeName);
+
+                    if ($conditionType instanceof ObjectType) {
+                        if ($runtimeType->name !== $conditionType->name) {
+                            continue;
+                        }
+                    } elseif ($conditionType instanceof AbstractType) {
+                        if (! $this->schema->isPossibleType($conditionType, $runtimeType)) {
+                            continue;
+                        }
+                    }
+                }
+
+                $this->doCollectFields($runtimeType, $selection->selectionSet);
+            }
+        }
+    }
+}

src/Experimental/Executor/CoroutineContext.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Experimental\Executor;
+
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\ResolveInfo;
+
+/**
+ * @internal
+ */
+class CoroutineContext
+{
+    /** @var CoroutineContextShared */
+    public $shared;
+
+    /** @var ObjectType */
+    public $type;
+
+    /** @var mixed */
+    public $value;
+
+    /** @var object */
+    public $result;
+
+    /** @var string[] */
+    public $path;
+
+    /** @var ResolveInfo|null */
+    public $resolveInfo;
+
+    /** @var string[]|null */
+    public $nullFence;
+
+    /**
+     * @param mixed         $value
+     * @param object        $result
+     * @param string[]      $path
+     * @param string[]|null $nullFence
+     */
+    public function __construct(
+        CoroutineContextShared $shared,
+        ObjectType $type,
+        $value,
+        $result,
+        array $path,
+        ?array $nullFence = null
+    ) {
+        $this->shared    = $shared;
+        $this->type      = $type;
+        $this->value     = $value;
+        $this->result    = $result;
+        $this->path      = $path;
+        $this->nullFence = $nullFence;
+    }
+}

src/Experimental/Executor/CoroutineContextShared.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Experimental\Executor;
+
+use GraphQL\Language\AST\FieldNode;
+use GraphQL\Language\AST\SelectionSetNode;
+use GraphQL\Language\AST\ValueNode;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\ResolveInfo;
+
+/**
+ * @internal
+ */
+class CoroutineContextShared
+{
+    /** @var FieldNode[] */
+    public $fieldNodes;
+
+    /** @var string */
+    public $fieldName;
+
+    /** @var string */
+    public $resultName;
+
+    /** @var ValueNode[]|null */
+    public $argumentValueMap;
+
+    /** @var SelectionSetNode|null */
+    public $mergedSelectionSet;
+
+    /** @var ObjectType|null */
+    public $typeGuard1;
+
+    /** @var callable|null */
+    public $resolveIfType1;
+
+    /** @var mixed */
+    public $argumentsIfType1;
+
+    /** @var ResolveInfo|null */
+    public $resolveInfoIfType1;
+
+    /** @var ObjectType|null */
+    public $typeGuard2;
+
+    /** @var CoroutineContext[]|null */
+    public $childContextsIfType2;
+
+    /**
+     * @param FieldNode[]  $fieldNodes
+     * @param mixed[]|null $argumentValueMap
+     */
+    public function __construct(array $fieldNodes, string $fieldName, string $resultName, ?array $argumentValueMap)
+    {
+        $this->fieldNodes       = $fieldNodes;
+        $this->fieldName        = $fieldName;
+        $this->resultName       = $resultName;
+        $this->argumentValueMap = $argumentValueMap;
+    }
+}

src/Experimental/Executor/CoroutineExecutor.php

@@ -0,0 +1,952 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Experimental\Executor;
+
+use Generator;
+use GraphQL\Error\Error;
+use GraphQL\Error\InvariantViolation;
+use GraphQL\Error\Warning;
+use GraphQL\Executor\ExecutionResult;
+use GraphQL\Executor\ExecutorImplementation;
+use GraphQL\Executor\Promise\Promise;
+use GraphQL\Executor\Promise\PromiseAdapter;
+use GraphQL\Executor\Values;
+use GraphQL\Language\AST\DocumentNode;
+use GraphQL\Language\AST\SelectionSetNode;
+use GraphQL\Language\AST\ValueNode;
+use GraphQL\Type\Definition\AbstractType;
+use GraphQL\Type\Definition\CompositeType;
+use GraphQL\Type\Definition\InputType;
+use GraphQL\Type\Definition\InterfaceType;
+use GraphQL\Type\Definition\LeafType;
+use GraphQL\Type\Definition\ListOfType;
+use GraphQL\Type\Definition\NonNull;
+use GraphQL\Type\Definition\ObjectType;
+use GraphQL\Type\Definition\ResolveInfo;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\UnionType;
+use GraphQL\Type\Introspection;
+use GraphQL\Type\Schema;
+use GraphQL\Utils\AST;
+use GraphQL\Utils\Utils;
+use SplQueue;
+use stdClass;
+use Throwable;
+use function is_array;
+use function is_string;
+use function sprintf;
+
+class CoroutineExecutor implements Runtime, ExecutorImplementation
+{
+    /** @var object */
+    private static $undefined;
+
+    /** @var Schema */
+    private $schema;
+
+    /** @var callable */
+    private $fieldResolver;
+
+    /** @var PromiseAdapter */
+    private $promiseAdapter;
+
+    /** @var mixed|null */
+    private $rootValue;
+
+    /** @var mixed|null */
+    private $contextValue;
+
+    /** @var mixed|null */
+    private $rawVariableValues;
+
+    /** @var mixed|null */
+    private $variableValues;
+
+    /** @var DocumentNode */
+    private $documentNode;
+
+    /** @var string|null */
+    private $operationName;
+
+    /** @var Collector */
+    private $collector;
+
+    /** @var Error[] */
+    private $errors;
+
+    /** @var SplQueue */
+    private $queue;
+
+    /** @var SplQueue */
+    private $schedule;
+
+    /** @var stdClass */
+    private $rootResult;
+
+    /** @var int */
+    private $pending;
+
+    /** @var callable */
+    private $doResolve;
+
+    public function __construct(
+        PromiseAdapter $promiseAdapter,
+        Schema $schema,
+        DocumentNode $documentNode,
+        $rootValue,
+        $contextValue,
+        $rawVariableValues,
+        ?string $operationName,
+        callable $fieldResolver
+    ) {
+        if (self::$undefined === null) {
+            self::$undefined = Utils::undefined();
+        }
+
+        $this->schema            = $schema;
+        $this->fieldResolver     = $fieldResolver;
+        $this->promiseAdapter    = $promiseAdapter;
+        $this->rootValue         = $rootValue;
+        $this->contextValue      = $contextValue;
+        $this->rawVariableValues = $rawVariableValues;
+        $this->documentNode      = $documentNode;
+        $this->operationName     = $operationName;
+    }
+
+    public static function create(
+        PromiseAdapter $promiseAdapter,
+        Schema $schema,
+        DocumentNode $documentNode,
+        $rootValue,
+        $contextValue,
+        $variableValues,
+        ?string $operationName,
+        callable $fieldResolver
+    ) {
+        return new static(
+            $promiseAdapter,
+            $schema,
+            $documentNode,
+            $rootValue,
+            $contextValue,
+            $variableValues,
+            $operationName,
+            $fieldResolver
+        );
+    }
+
+    private static function resultToArray($value, $emptyObjectAsStdClass = true)
+    {
+        if ($value instanceof stdClass) {
+            $array = [];
+            foreach ($value as $propertyName => $propertyValue) {
+                $array[$propertyName] = self::resultToArray($propertyValue);
+            }
+            if ($emptyObjectAsStdClass && empty($array)) {
+                return new stdClass();
+            }
+
+            return $array;
+        }
+
+        if (is_array($value)) {
+            $array = [];
+            foreach ($value as $key => $item) {
+                $array[$key] = self::resultToArray($item);
+            }
+
+            return $array;
+        }
+
+        return $value;
+    }
+
+    public function doExecute() : Promise
+    {
+        $this->rootResult = new stdClass();
+        $this->errors     = [];
+        $this->queue      = new SplQueue();
+        $this->schedule   = new SplQueue();
+        $this->pending    = 0;
+
+        $this->collector = new Collector($this->schema, $this);
+        $this->collector->initialize($this->documentNode, $this->operationName);
+
+        if (! empty($this->errors)) {
+            return $this->promiseAdapter->createFulfilled($this->finishExecute(null, $this->errors));
+        }
+
+        [$errors, $coercedVariableValues] = Values::getVariableValues(
+            $this->schema,
+            $this->collector->operation->variableDefinitions ?: [],
+            $this->rawVariableValues ?: []
+        );
+
+        if (! empty($errors)) {
+            return $this->promiseAdapter->createFulfilled($this->finishExecute(null, $errors));
+        }
+
+        $this->variableValues = $coercedVariableValues;
+
+        foreach ($this->collector->collectFields($this->collector->rootType, $this->collector->operation->selectionSet) as $shared) {
+            /** @var CoroutineContextShared $shared */
+
+            // !!! assign to keep object keys sorted
+            $this->rootResult->{$shared->resultName} = null;
+
+            $ctx = new CoroutineContext(
+                $shared,
+                $this->collector->rootType,
+                $this->rootValue,
+                $this->rootResult,
+                [$shared->resultName]
+            );
+
+            $fieldDefinition = $this->findFieldDefinition($ctx);
+            if (! $fieldDefinition->getType() instanceof NonNull) {
+                $ctx->nullFence = [$shared->resultName];
+            }
+
+            if ($this->collector->operation->operation === 'mutation' && ! $this->queue->isEmpty()) {
+                $this->schedule->enqueue($ctx);
+            } else {
+                $this->queue->enqueue(new Strand($this->spawn($ctx)));
+            }
+        }
+
+        $this->run();
+
+        if ($this->pending > 0) {
+            return $this->promiseAdapter->create(function (callable $resolve) {
+                $this->doResolve = $resolve;
+            });
+        }
+
+        return $this->promiseAdapter->createFulfilled($this->finishExecute($this->rootResult, $this->errors));
+    }
+
+    /**
+     * @param object|null $value
+     * @param Error[]     $errors
+     */
+    private function finishExecute($value, array $errors) : ExecutionResult
+    {
+        $this->rootResult     = null;
+        $this->errors         = null;
+        $this->queue          = null;
+        $this->schedule       = null;
+        $this->pending        = null;
+        $this->collector      = null;
+        $this->variableValues = null;
+
+        if ($value !== null) {
+            $value = self::resultToArray($value, false);
+        }
+
+        return new ExecutionResult($value, $errors);
+    }
+
+    /**
+     * @internal
+     */
+    public function evaluate(ValueNode $valueNode, InputType $type)
+    {
+        return AST::valueFromAST($valueNode, $type, $this->variableValues);
+    }
+
+    /**
+     * @internal
+     */
+    public function addError($error)
+    {
+        $this->errors[] = $error;
+    }
+
+    private function run()
+    {
+        RUN:
+        while (! $this->queue->isEmpty()) {
+            /** @var Strand $strand */
+            $strand = $this->queue->dequeue();
+
+            try {
+                if ($strand->success !== null) {
+                    RESUME:
+
+                    if ($strand->success) {
+                        $strand->current->send($strand->value);
+                    } else {
+                        $strand->current->throw($strand->value);
+                    }
+
+                    $strand->success = null;
+                    $strand->value   = null;
+                }
+
+                START:
+                if ($strand->current->valid()) {
+                    $value = $strand->current->current();
+
+                    if ($value instanceof Generator) {
+                        $strand->stack[$strand->depth++] = $strand->current;
+                        $strand->current                 = $value;
+                        goto START;
+                    } elseif ($this->isPromise($value)) {
+                        // !!! increment pending before calling ->then() as it may invoke the callback right away
+                        ++$this->pending;
+
+                        if (! $value instanceof Promise) {
+                            $value = $this->promiseAdapter->convertThenable($value);
+                        }
+
+                        $this->promiseAdapter
+                            ->then(
+                                $value,
+                                function ($value) use ($strand) {
+                                    $strand->success = true;
+                                    $strand->value   = $value;
+                                    $this->queue->enqueue($strand);
+                                    $this->done();
+                                },
+                                function (Throwable $throwable) use ($strand) {
+                                    $strand->success = false;
+                                    $strand->value   = $throwable;
+                                    $this->queue->enqueue($strand);
+                                    $this->done();
+                                }
+                            );
+                        continue;
+                    } else {
+                        $strand->success = true;
+                        $strand->value   = $value;
+                        goto RESUME;
+                    }
+                }
+
+                $strand->success = true;
+                $strand->value   = $strand->current->getReturn();
+            } catch (Throwable $reason) {
+                $strand->success = false;
+                $strand->value   = $reason;
+            }
+
+            if ($strand->depth <= 0) {
+                continue;
+            }
+
+            $current         = &$strand->stack[--$strand->depth];
+            $strand->current = $current;
+            $current         = null;
+            goto RESUME;
+        }
+
+        if ($this->pending > 0 || $this->schedule->isEmpty()) {
+            return;
+        }
+
+        /** @var CoroutineContext $ctx */
+        $ctx = $this->schedule->dequeue();
+        $this->queue->enqueue(new Strand($this->spawn($ctx)));
+        goto RUN;
+    }
+
+    private function done()
+    {
+        --$this->pending;
+
+        $this->run();
+
+        if ($this->pending > 0) {
+            return;
+        }
+
+        $doResolve = $this->doResolve;
+        $doResolve($this->finishExecute($this->rootResult, $this->errors));
+    }
+
+    private function spawn(CoroutineContext $ctx)
+    {
+        // short-circuit evaluation for __typename
+        if ($ctx->shared->fieldName === Introspection::TYPE_NAME_FIELD_NAME) {
+            $ctx->result->{$ctx->shared->resultName} = $ctx->type->name;
+
+            return;
+        }
+
+        try {
+            if ($ctx->shared->typeGuard1 === $ctx->type) {
+                $resolve                = $ctx->shared->resolveIfType1;
+                $ctx->resolveInfo       = clone $ctx->shared->resolveInfoIfType1;
+                $ctx->resolveInfo->path = $ctx->path;
+                $arguments              = $ctx->shared->argumentsIfType1;
+                $returnType             = $ctx->resolveInfo->returnType;
+            } else {
+                $fieldDefinition = $this->findFieldDefinition($ctx);
+
+                if ($fieldDefinition->resolveFn !== null) {
+                    $resolve = $fieldDefinition->resolveFn;
+                } elseif ($ctx->type->resolveFieldFn !== null) {
+                    $resolve = $ctx->type->resolveFieldFn;
+                } else {
+                    $resolve = $this->fieldResolver;
+                }
+
+                $returnType = $fieldDefinition->getType();
+
+                $ctx->resolveInfo = new ResolveInfo(
+                    $ctx->shared->fieldName,
+                    $ctx->shared->fieldNodes,
+                    $returnType,
+                    $ctx->type,
+                    $ctx->path,
+                    $this->schema,
+                    $this->collector->fragments,
+                    $this->rootValue,
+                    $this->collector->operation,
+                    $this->variableValues
+                );
+
+                $arguments = Values::getArgumentValuesForMap(
+                    $fieldDefinition,
+                    $ctx->shared->argumentValueMap,
+                    $this->variableValues
+                );
+
+                // !!! assign only in batch when no exception can be thrown in-between
+                $ctx->shared->typeGuard1         = $ctx->type;
+                $ctx->shared->resolveIfType1     = $resolve;
+                $ctx->shared->argumentsIfType1   = $arguments;
+                $ctx->shared->resolveInfoIfType1 = $ctx->resolveInfo;
+            }
+
+            $value = $resolve($ctx->value, $arguments, $this->contextValue, $ctx->resolveInfo);
+
+            if (! $this->completeValueFast($ctx, $returnType, $value, $ctx->path, $returnValue)) {
+                $returnValue = yield $this->completeValue(
+                    $ctx,
+                    $returnType,
+                    $value,
+                    $ctx->path,
+                    $ctx->nullFence
+                );
+            }
+        } catch (Throwable $reason) {
+            $this->addError(Error::createLocatedError(
+                $reason,
+                $ctx->shared->fieldNodes,
+                $ctx->path
+            ));
+
+            $returnValue = self::$undefined;
+        }
+
+        if ($returnValue !== self::$undefined) {
+            $ctx->result->{$ctx->shared->resultName} = $returnValue;
+        } elseif ($ctx->resolveInfo !== null && $ctx->resolveInfo->returnType instanceof NonNull) { // !!! $ctx->resolveInfo might not have been initialized yet
+            $result =& $this->rootResult;
+            foreach ($ctx->nullFence ?? [] as $key) {
+                if (is_string($key)) {
+                    $result =& $result->{$key};
+                } else {
+                    $result =& $result[$key];
+                }
+            }
+            $result = null;
+        }
+    }
+
+    private function findFieldDefinition(CoroutineContext $ctx)
+    {
+        if ($ctx->shared->fieldName === Introspection::SCHEMA_FIELD_NAME && $ctx->type === $this->schema->getQueryType()) {
+            return Introspection::schemaMetaFieldDef();
+        }
+
+        if ($ctx->shared->fieldName === Introspection::TYPE_FIELD_NAME && $ctx->type === $this->schema->getQueryType()) {
+            return Introspection::typeMetaFieldDef();
+        }
+
+        if ($ctx->shared->fieldName === Introspection::TYPE_NAME_FIELD_NAME) {
+            return Introspection::typeNameMetaFieldDef();
+        }
+
+        return $ctx->type->getField($ctx->shared->fieldName);
+    }
+
+    /**
+     * @param mixed    $value
+     * @param string[] $path
+     * @param mixed    $returnValue
+     */
+    private function completeValueFast(CoroutineContext $ctx, Type $type, $value, array $path, &$returnValue) : bool
+    {
+        // special handling of Throwable inherited from JS reference implementation, but makes no sense in this PHP
+        if ($this->isPromise($value) || $value instanceof Throwable) {
+            return false;
+        }
+
+        $nonNull = false;
+        if ($type instanceof NonNull) {
+            $nonNull = true;
+            $type    = $type->getWrappedType();
+        }
+
+        if (! $type instanceof LeafType) {
+            return false;
+        }
+
+        if ($type !== $this->schema->getType($type->name)) {
+            $hint = '';
+            if ($this->schema->getConfig()->typeLoader !== null) {
+                $hint = sprintf(
+                    'Make sure that type loader returns the same instance as defined in %s.%s',
+                    $ctx->type,
+                    $ctx->shared->fieldName
+                );
+            }
+            $this->addError(Error::createLocatedError(
+                new InvariantViolation(
+                    sprintf(
+                        'Schema must contain unique named types but contains multiple types named "%s". %s ' .
+                        '(see http://webonyx.github.io/graphql-php/type-system/#type-registry).',
+                        $type->name,
+                        $hint
+                    )
+                ),
+                $ctx->shared->fieldNodes,
+                $path
+            ));
+
+            $value = null;
+        }
+
+        if ($value === null) {
+            $returnValue = null;
+        } else {
+            try {
+                $returnValue = $type->serialize($value);
+            } catch (Throwable $error) {
+                $this->addError(Error::createLocatedError(
+                    new InvariantViolation(
+                        'Expected a value of type "' . Utils::printSafe($type) . '" but received: ' . Utils::printSafe($value),
+                        0,
+                        $error
+                    ),
+                    $ctx->shared->fieldNodes,
+                    $path
+                ));
+                $returnValue = null;
+            }
+        }
+
+        if ($nonNull && $returnValue === null) {
+            $this->addError(Error::createLocatedError(
+                new InvariantViolation(sprintf(
+                    'Cannot return null for non-nullable field %s.%s.',
+                    $ctx->type->name,
+                    $ctx->shared->fieldName
+                )),
+                $ctx->shared->fieldNodes,
+                $path
+            ));
+
+            $returnValue = self::$undefined;
+        }
+
+        return true;
+    }
+
+    /**
+     * @param mixed         $value
+     * @param string[]      $path
+     * @param string[]|null $nullFence
+     *
+     * @return mixed
+     */
+    private function completeValue(CoroutineContext $ctx, Type $type, $value, array $path, ?array $nullFence)
+    {
+        $nonNull     = false;
+        $returnValue = null;
+
+        if ($type instanceof NonNull) {
+            $nonNull = true;
+            $type    = $type->getWrappedType();
+        } else {
+            $nullFence = $path;
+        }
+
+        // !!! $value might be promise, yield to resolve
+        try {
+            if ($this->isPromise($value)) {
+                $value = yield $value;
+            }
+        } catch (Throwable $reason) {
+            $this->addError(Error::createLocatedError(
+                $reason,
+                $ctx->shared->fieldNodes,
+                $path
+            ));
+            if ($nonNull) {
+                $returnValue = self::$undefined;
+            } else {
+                $returnValue = null;
+            }
+            goto CHECKED_RETURN;
+        }
+
+        if ($value === null) {
+            $returnValue = $value;
+            goto CHECKED_RETURN;
+        } elseif ($value instanceof Throwable) {
+            // special handling of Throwable inherited from JS reference implementation, but makes no sense in this PHP
+            $this->addError(Error::createLocatedError(
+                $value,
+                $ctx->shared->fieldNodes,
+                $path
+            ));
+            if ($nonNull) {
+                $returnValue = self::$undefined;
+            } else {
+                $returnValue = null;
+            }
+            goto CHECKED_RETURN;
+        }
+
+        if ($type instanceof ListOfType) {
+            $returnValue = [];
+            $index       = -1;
+            $itemType    = $type->getWrappedType();
+            foreach ($value as $itemValue) {
+                ++$index;
+
+                $itemPath               = $path;
+                $itemPath[]             = $index; // !!! use arrays COW semantics
+                $ctx->resolveInfo->path = $itemPath;
+
+                try {
+                    if (! $this->completeValueFast($ctx, $itemType, $itemValue, $itemPath, $itemReturnValue)) {
+                        $itemReturnValue = yield $this->completeValue($ctx, $itemType, $itemValue, $itemPath, $nullFence);
+                    }
+                } catch (Throwable $reason) {
+                    $this->addError(Error::createLocatedError(
+                        $reason,
+                        $ctx->shared->fieldNodes,
+                        $itemPath
+                    ));
+                    $itemReturnValue = null;
+                }
+                if ($itemReturnValue === self::$undefined) {
+                    $returnValue = self::$undefined;
+                    goto CHECKED_RETURN;
+                }
+                $returnValue[$index] = $itemReturnValue;
+            }
+
+            goto CHECKED_RETURN;
+        } else {
+            if ($type !== $this->schema->getType($type->name)) {
+                $hint = '';
+                if ($this->schema->getConfig()->typeLoader !== null) {
+                    $hint = sprintf(
+                        'Make sure that type loader returns the same instance as defined in %s.%s',
+                        $ctx->type,
+                        $ctx->shared->fieldName
+                    );
+                }
+                $this->addError(Error::createLocatedError(
+                    new InvariantViolation(
+                        sprintf(
+                            'Schema must contain unique named types but contains multiple types named "%s". %s ' .
+                            '(see http://webonyx.github.io/graphql-php/type-system/#type-registry).',
+                            $type->name,
+                            $hint
+                        )
+                    ),
+                    $ctx->shared->fieldNodes,
+                    $path
+                ));
+
+                $returnValue = null;
+                goto CHECKED_RETURN;
+            }
+
+            if ($type instanceof LeafType) {
+                try {
+                    $returnValue = $type->serialize($value);
+                } catch (Throwable $error) {
+                    $this->addError(Error::createLocatedError(
+                        new InvariantViolation(
+                            'Expected a value of type "' . Utils::printSafe($type) . '" but received: ' . Utils::printSafe($value),
+                            0,
+                            $error
+                        ),
+                        $ctx->shared->fieldNodes,
+                        $path
+                    ));
+                    $returnValue = null;
+                }
+                goto CHECKED_RETURN;
+            } elseif ($type instanceof CompositeType) {
+                /** @var ObjectType|null $objectType */
+                $objectType = null;
+                if ($type instanceof InterfaceType || $type instanceof UnionType) {
+                    $objectType = $type->resolveType($value, $this->contextValue, $ctx->resolveInfo);
+
+                    if ($objectType === null) {
+                        $objectType = yield $this->resolveTypeSlow($ctx, $value, $type);
+                    }
+
+                    // !!! $objectType->resolveType() might return promise, yield to resolve
+                    $objectType = yield $objectType;
+                    if (is_string($objectType)) {
+                        $objectType = $this->schema->getType($objectType);
+                    }
+
+                    if ($objectType === null) {
+                        $this->addError(Error::createLocatedError(
+                            sprintf(
+                                'Composite type "%s" did not resolve concrete object type for value: %s.',
+                                $type->name,
+                                Utils::printSafe($value)
+                            ),
+                            $ctx->shared->fieldNodes,
+                            $path
+                        ));
+
+                        $returnValue = self::$undefined;
+                        goto CHECKED_RETURN;
+                    } elseif (! $objectType instanceof ObjectType) {
+                        $this->addError(Error::createLocatedError(
+                            new InvariantViolation(sprintf(
+                                'Abstract type %s must resolve to an Object type at ' .
+                                'runtime for field %s.%s with value "%s", received "%s". ' .
+                                'Either the %s type should provide a "resolveType" ' .
+                                'function or each possible type should provide an "isTypeOf" function.',
+                                $type,
+                                $ctx->resolveInfo->parentType,
+                                $ctx->resolveInfo->fieldName,
+                                Utils::printSafe($value),
+                                Utils::printSafe($objectType),
+                                $type
+                            )),
+                            $ctx->shared->fieldNodes,
+                            $path
+                        ));
+
+                        $returnValue = null;
+                        goto CHECKED_RETURN;
+                    } elseif (! $this->schema->isPossibleType($type, $objectType)) {
+                        $this->addError(Error::createLocatedError(
+                            new InvariantViolation(sprintf(
+                                'Runtime Object type "%s" is not a possible type for "%s".',
+                                $objectType,
+                                $type
+                            )),
+                            $ctx->shared->fieldNodes,
+                            $path
+                        ));
+
+                        $returnValue = null;
+                        goto CHECKED_RETURN;
+                    } elseif ($objectType !== $this->schema->getType($objectType->name)) {
+                        $this->addError(Error::createLocatedError(
+                            new InvariantViolation(
+                                sprintf(
+                                    'Schema must contain unique named types but contains multiple types named "%s". ' .
+                                    'Make sure that `resolveType` function of abstract type "%s" returns the same ' .
+                                    'type instance as referenced anywhere else within the schema ' .
+                                    '(see http://webonyx.github.io/graphql-php/type-system/#type-registry).',
+                                    $objectType,
+                                    $type
+                                )
+                            ),
+                            $ctx->shared->fieldNodes,
+                            $path
+                        ));
+
+                        $returnValue = null;
+                        goto CHECKED_RETURN;
+                    }
+                } elseif ($type instanceof ObjectType) {
+                    $objectType = $type;
+                } else {
+                    $this->addError(Error::createLocatedError(
+                        sprintf(
+                            'Unexpected field type "%s".',
+                            Utils::printSafe($type)
+                        ),
+                        $ctx->shared->fieldNodes,
+                        $path
+                    ));
+
+                    $returnValue = self::$undefined;
+                    goto CHECKED_RETURN;
+                }
+
+                $typeCheck = $objectType->isTypeOf($value, $this->contextValue, $ctx->resolveInfo);
+                if ($typeCheck !== null) {
+                    // !!! $objectType->isTypeOf() might return promise, yield to resolve
+                    $typeCheck = yield $typeCheck;
+                    if (! $typeCheck) {
+                        $this->addError(Error::createLocatedError(
+                            sprintf('Expected value of type "%s" but got: %s.', $type->name, Utils::printSafe($value)),
+                            $ctx->shared->fieldNodes,
+                            $path
+                        ));
+
+                        $returnValue = null;
+                        goto CHECKED_RETURN;
+                    }
+                }
+
+                $returnValue = new stdClass();
+
+                if ($ctx->shared->typeGuard2 === $objectType) {
+                    foreach ($ctx->shared->childContextsIfType2 as $childCtx) {
+                        $childCtx              = clone $childCtx;
+                        $childCtx->type        = $objectType;
+                        $childCtx->value       = $value;
+                        $childCtx->result      = $returnValue;
+                        $childCtx->path        = $path;
+                        $childCtx->path[]      = $childCtx->shared->resultName; // !!! uses array COW semantics
+                        $childCtx->nullFence   = $nullFence;
+                        $childCtx->resolveInfo = null;
+
+                        $this->queue->enqueue(new Strand($this->spawn($childCtx)));
+
+                        // !!! assign null to keep object keys sorted
+                        $returnValue->{$childCtx->shared->resultName} = null;
+                    }
+                } else {
+                    $childContexts = [];
+
+                    foreach ($this->collector->collectFields(
+                        $objectType,
+                        $ctx->shared->mergedSelectionSet ?? $this->mergeSelectionSets($ctx)
+                    ) as $childShared) {
+                        /** @var CoroutineContextShared $childShared */
+
+                        $childPath   = $path;
+                        $childPath[] = $childShared->resultName; // !!! uses array COW semantics
+                        $childCtx    = new CoroutineContext(
+                            $childShared,
+                            $objectType,
+                            $value,
+                            $returnValue,
+                            $childPath,
+                            $nullFence
+                        );
+
+                        $childContexts[] = $childCtx;
+
+                        $this->queue->enqueue(new Strand($this->spawn($childCtx)));
+
+                        // !!! assign null to keep object keys sorted
+                        $returnValue->{$childShared->resultName} = null;
+                    }
+
+                    $ctx->shared->typeGuard2           = $objectType;
+                    $ctx->shared->childContextsIfType2 = $childContexts;
+                }
+
+                goto CHECKED_RETURN;
+            } else {
+                $this->addError(Error::createLocatedError(
+                    sprintf('Unhandled type "%s".', Utils::printSafe($type)),
+                    $ctx->shared->fieldNodes,
+                    $path
+                ));
+
+                $returnValue = null;
+                goto CHECKED_RETURN;
+            }
+        }
+
+        CHECKED_RETURN:
+        if ($nonNull && $returnValue === null) {
+            $this->addError(Error::createLocatedError(
+                new InvariantViolation(sprintf(
+                    'Cannot return null for non-nullable field %s.%s.',
+                    $ctx->type->name,
+                    $ctx->shared->fieldName
+                )),
+                $ctx->shared->fieldNodes,
+                $path
+            ));
+
+            return self::$undefined;
+        }
+
+        return $returnValue;
+    }
+
+    private function mergeSelectionSets(CoroutineContext $ctx)
+    {
+        $selections = [];
+
+        foreach ($ctx->shared->fieldNodes as $fieldNode) {
+            if ($fieldNode->selectionSet === null) {
+                continue;
+            }
+
+            foreach ($fieldNode->selectionSet->selections as $selection) {
+                $selections[] = $selection;
+            }
+        }
+
+        return $ctx->shared->mergedSelectionSet = new SelectionSetNode(['selections' => $selections]);
+    }
+
+    private function resolveTypeSlow(CoroutineContext $ctx, $value, AbstractType $abstractType)
+    {
+        if ($value !== null &&
+            is_array($value) &&
+            isset($value['__typename']) &&
+            is_string($value['__typename'])
+        ) {
+            return $this->schema->getType($value['__typename']);
+        }
+
+        if ($abstractType instanceof InterfaceType && $this->schema->getConfig()->typeLoader !== null) {
+            Warning::warnOnce(
+                sprintf(
+                    'GraphQL Interface Type `%s` returned `null` from its `resolveType` function ' .
+                    'for value: %s. Switching to slow resolution method using `isTypeOf` ' .
+                    'of all possible implementations. It requires full schema scan and degrades query performance significantly. ' .
+                    ' Make sure your `resolveType` always returns valid implementation or throws.',
+                    $abstractType->name,
+                    Utils::printSafe($value)
+                ),
+                Warning::WARNING_FULL_SCHEMA_SCAN
+            );
+        }
+
+        $possibleTypes = $this->schema->getPossibleTypes($abstractType);
+
+        // to be backward-compatible with old executor, ->isTypeOf() is called for all possible types,
+        // it cannot short-circuit when the match is found
+
+        $selectedType = null;
+        foreach ($possibleTypes as $type) {
+            $typeCheck = yield $type->isTypeOf($value, $this->contextValue, $ctx->resolveInfo);
+            if ($selectedType !== null || $typeCheck !== true) {
+                continue;
+            }
+
+            $selectedType = $type;
+        }
+
+        return $selectedType;
+    }
+
+    /**
+     * @param mixed $value
+     *
+     * @return bool
+     */
+    private function isPromise($value)
+    {
+        return $value instanceof Promise || $this->promiseAdapter->isThenable($value);
+    }
+}

src/Experimental/Executor/Runtime.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Experimental\Executor;
+
+use GraphQL\Language\AST\ValueNode;
+use GraphQL\Type\Definition\InputType;
+
+/**
+ * @internal
+ */
+interface Runtime
+{
+    public function evaluate(ValueNode $valueNode, InputType $type);
+
+    public function addError($error);
+}

src/Experimental/Executor/Strand.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GraphQL\Experimental\Executor;
+
+use Generator;
+
+/**
+ * @internal
+ */
+class Strand
+{
+    /** @var Generator */
+    public $current;
+
+    /** @var Generator[] */
+    public $stack;
+
+    /** @var int */
+    public $depth;
+
+    /** @var bool|null */
+    public $success;
+
+    /** @var mixed */
+    public $value;
+
+    public function __construct(Generator $coroutine)
+    {
+        $this->current = $coroutine;
+        $this->stack   = [];
+        $this->depth   = 0;
+    }
+}