From 7f346d56581a3bd99611acd85016c778ea94d678 Mon Sep 17 00:00:00 2001 From: Vladimir Razuvaev Date: Sun, 20 Aug 2017 22:10:37 +0700 Subject: [PATCH] Documentation improvements --- UPGRADE.md | 2 + docs/complementary-tools.md | 1 + docs/data-fetching.md | 64 ++-- docs/error-handling.md | 70 ++-- docs/executing-queries.md | 34 +- docs/getting-started.md | 12 +- docs/how-it-works.md | 15 +- docs/index.md | 17 +- docs/reference.md | 470 ++++++++++++++++++------- docs/security.md | 16 +- docs/type-system/directives.md | 40 +-- docs/type-system/enum-types.md | 33 +- docs/type-system/index.md | 24 +- docs/type-system/input-types.md | 81 ++++- docs/type-system/interfaces.md | 33 +- docs/type-system/lists-and-nonnulls.md | 19 +- docs/type-system/object-types.md | 40 ++- docs/type-system/scalar-types.md | 19 +- docs/type-system/schema.md | 56 +-- docs/type-system/type-language.md | 27 +- docs/type-system/unions.md | 13 +- mkdocs.yml | 2 +- 22 files changed, 711 insertions(+), 377 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index a35e094..848a2f6 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -146,6 +146,8 @@ 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. diff --git a/docs/complementary-tools.md b/docs/complementary-tools.md index 1dbbefc..4e7860c 100644 --- a/docs/complementary-tools.md +++ b/docs/complementary-tools.md @@ -11,3 +11,4 @@ - [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 +- [DataLoader PHP](https://github.com/overblog/dataloader-php) - as a ready implementation for [deferred resolvers](data-fetching.md#solving-n1-problem) \ No newline at end of file diff --git a/docs/data-fetching.md b/docs/data-fetching.md index f6e6fa3..df357d0 100644 --- a/docs/data-fetching.md +++ b/docs/data-fetching.md @@ -2,11 +2,11 @@ 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 GraphQL query to PHP array **graphql-php** traverses query fields (using depth-first algorithm) and +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 response (for scalars and enums) +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: @@ -25,6 +25,9 @@ Let's walk through an example. Consider following GraphQL query: We need a Schema that can fulfill it. On the very top level the Schema contains Query type: ```php + 'Query', 'fields' => [ @@ -46,12 +49,16 @@ $queryType = new ObjectType([ As we see field **lastStory** has **resolve** function that is responsible for fetching data. -In our example we simply return array value, but in real-world application you would query -your database/cache/search index and return result. +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 + 'BlogStory', 'fields' => [ @@ -83,8 +90,8 @@ $blogStoryType = new ObjectType([ Here **$blogStory** is the array returned by **lastStory** field above. -Again: in real-world applications you would fetch user data from datastore 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 +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? @@ -95,7 +102,8 @@ for a field you simply override this default resolver. # Default Field Resolver **graphql-php** provides following default field resolver: ```php -function defaultFieldResolver($source, $args, $context, ResolveInfo $info) +fieldName; $property = null; @@ -115,7 +123,7 @@ function defaultFieldResolver($source, $args, $context, ResolveInfo $info) ``` As you see it returns value by key (for arrays) or property (for objects). -If value is not set - it returns **null**. +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. @@ -124,6 +132,11 @@ Sometimes it might be convenient to set default field resolver per type. You can [resolveField option in type config](type-system/object-types.md#configuration-options). For example: ```php + 'User', 'fields' => [ @@ -167,13 +180,14 @@ Consider following GraphQL query: } ``` -Naive field resolution process would require up to 10 calls to underlying data store to fetch authors for all 10 stories. +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 later stage +**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: +Here is an example of **BlogStory** resolver for field **author** that uses deferring: ```php + function($blogStory) { MyUserBuffer::add($blogStory['authorId']); @@ -184,18 +198,16 @@ Here is an example of `BlogStory` resolver for field `author` that uses deferrin } ``` -In this example we fill up buffer with 10 author ids first. Then **graphql-php** continues +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 return final field value. +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. +project. This solution enables very interesting optimizations at no cost. Consider the following query: -This solution enables very interesting optimizations at no cost. Consider following query: - -``` +```graphql { topStories(limit: 10) { author { @@ -212,14 +224,14 @@ This solution enables very interesting optimizations at no cost. Consider follow } ``` -Even if `author` field is located on different levels of 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 naive implementation. +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 is deprecated) +Since: 0.10.0 (version 0.9.0 had slightly different API which still works, but is deprecated) -If your project runs in environment that supports async operations +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. @@ -230,6 +242,10 @@ To start using this feature, switch facade method for query execution from **executeQuery** to **promiseToExecute**: ```php + - `GraphQL\Executor\Promise\PromiseAdapter`. + [`GraphQL\Executor\Promise\PromiseAdapter`](reference.md#graphqlexecutorpromisepromiseadapter). Then your **resolve** functions should return promises of your platform instead of `GraphQL\Deferred`s. \ No newline at end of file diff --git a/docs/error-handling.md b/docs/error-handling.md index 556527c..a79e42b 100644 --- a/docs/error-handling.md +++ b/docs/error-handling.md @@ -1,47 +1,52 @@ # Errors in GraphQL -Query execution process never throws exceptions. Instead all errors are caught and collected in -[execution result](executing-queries.md#execution-result). +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). -Later `$result->toArray()` automatically converts these errors to array using default -error formatting. But you can apply [custom error filtering and formatting](#custom-error-filtering-and-formatting) +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 associative array with following structure: +By default, each error entry is converted to an associative array with following structure: ```php + 'Error message', 'category' => 'graphql', 'locations' => [ ['line' => 1, 'column' => 2] ], - 'path': [ + 'path' => [ 'listField', 0, 'fieldWithException' ] -] +]; ``` -Entry at key **locations** points to character in query string which caused the error. -In some cases (like deep fragment fields) locations will include several entries to track down path to -field with error in query. +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 path -from the very root field to actual field value producing an error +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"**. +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` and claiming themselves as **safe** will -be reported with full error message. +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 + 'My reported error', 'category' => 'businessLogic', 'locations' => [ ['line' => 10, 'column' => 2] ], - 'path': [ + 'path' => [ 'path', 'to', 'fieldWithException' ] -] +]; ``` To change default **"Internal server error"** message to something else, use: @@ -91,6 +97,7 @@ $result = GraphQL::executeQuery(/*args*/)->toArray($debug); This will make each error entry to look like this: ```php + 'Actual exception message', 'message' => 'Internal server error', @@ -98,7 +105,7 @@ This will make each error entry to look like this: 'locations' => [ ['line' => 10, 'column' => 2] ], - 'path': [ + 'path' => [ 'listField', 0, 'fieldWithException' @@ -106,11 +113,13 @@ This will make each error entry to look like this: 'trace' => [ /* Formatted original exception trace */ ] -] +]; ``` If you prefer first resolver exception to be re-thrown, use following flags: ```php +toArray($debug); # 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` to array. -**Handler** is useful for error filtering and logging. +**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: +For example, these are default formatter and handler: ```php +toArray(); ``` -Note that when you pass [debug flags](#debugging-tools) to `toArray()` your custom formatter will still be +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 @@ -155,6 +166,11 @@ Usually such errors mean that there is some logical error in your schema and it when it makes sense to return `500` error code for GraphQL endpoint: ```php + 'Unexpected error' - ]); + $body = [ + 'errors' => [FormattedError::createFromException($e)] + ]; $status = 500; } diff --git a/docs/executing-queries.md b/docs/executing-queries.md index db676ec..0a00e0d 100644 --- a/docs/executing-queries.md +++ b/docs/executing-queries.md @@ -2,10 +2,11 @@ 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 convenient facade for this process in class +**graphql-php** provides a convenient facade for this process in class [`GraphQL\GraphQL`](reference.md#graphqlgraphql): ```php +toArray(); ``` -Returned array contains **data** and **errors** keys, as described by +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 section on [error handling and formatting](error-handling.md). +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 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.

It will be available as 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. +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.

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. Default value is all available rules. Empty array would allow to skip query validation (may be convenient for persisted queries which are validated before persisting and assumed valid during execution) +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 spec-compliant response; [batched queries](#query-batching); persisted queries. +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): @@ -88,20 +89,20 @@ 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/request/psr7.html) - [Slim](https://www.slimframework.com/docs/concepts/value-objects.html) -- [Zend Diactoros](https://zendframework.github.io/zend-diactoros/) +- [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 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.

It will be available as 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. +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.

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. Default value is all available rules. Empty array would allow to skip query validation (may be convenient for persisted queries which are validated before persisting and assumed valid during execution).

Pass `callable` to return different validation rules for different queries (e.g. empty array for persisted query and full list of rules for regular queries). When passed, it is expected to have following signature:

**function (OperationParams $params, DocumentNode $node, $operationType): array**

See also docs on [OperationParams](reference.md#graphqlserveroperationparams). +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).

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:

**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)).

Defaults to **false** debug | `int` | Debug flags. See [docs on error debugging](error-handling.md#debugging-tools) (flag values are the same). -persistentQueryLoader | `callable` | Function which is called to fetch actual query when server encounters **queryId** in request vs **query**.

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.

Expected function signature:
**function ($queryId, OperationParams $params)**

Function is expected to return query **string** or parsed **DocumentNode**

See also docs on [OperationParams](reference.md#graphqlserveroperationparams).

[Read more about persisted queries](https://dev-blog.apollodata.com/persisted-graphql-queries-with-apollo-client-119fd7e6bba5). +persistentQueryLoader | `callable` | A function which is called to fetch actual query when server encounters **queryId** in request vs **query**.

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.

Expected function signature:
**function ($queryId, [OperationParams](reference.md#graphqlserveroperationparams) $params)**

Function is expected to return query **string** or parsed **DocumentNode**

[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. @@ -109,7 +110,7 @@ promiseAdapter | [`PromiseAdapter`](reference.md#graphqlexecutorpromisepromisead **Server config instance** If you prefer fluid interface for config with autocomplete in IDE and static time validation, -use `GraphQL\Server\ServerConfig` instead of an array: +use [`GraphQL\Server\ServerConfig`](reference.md#graphqlserverserverconfig) instead of an array: ```php fieldName up to $depth levels + * + * Example: + * query MyQuery{ + * { + * root { + * id, + * nested { + * nested1 + * nested2 { + * nested3 + * } + * } + * } + * } + * + * Given this ResolveInfo instance is a part of "root" field resolution, and $depth === 1, + * method will return: + * [ + * 'id' => true, + * 'nested' => [ + * nested1 => true, + * nested2 => true + * ] + * ] + * + * Warning: this method it is a naive implementation which does not take into account + * conditional typed fragments. So use it with care for fields of interface and union types. + * + * @api + * @param int $depth How many levels to include in output + * @return array + */ +function getFieldSelection($depth = 0) +``` +# GraphQL\Type\Definition\DirectiveLocation +List of available directive locations + +**Class Constants:** +```php +const IFACE = "INTERFACE"; +const SUBSCRIPTION = "SUBSCRIPTION"; +const FRAGMENT_SPREAD = "FRAGMENT_SPREAD"; +const QUERY = "QUERY"; +const MUTATION = "MUTATION"; +const FRAGMENT_DEFINITION = "FRAGMENT_DEFINITION"; +const INPUT_OBJECT = "INPUT_OBJECT"; +const INLINE_FRAGMENT = "INLINE_FRAGMENT"; +const UNION = "UNION"; +const SCALAR = "SCALAR"; +const FIELD_DEFINITION = "FIELD_DEFINITION"; +const ARGUMENT_DEFINITION = "ARGUMENT_DEFINITION"; +const ENUM = "ENUM"; +const OBJECT = "OBJECT"; +const ENUM_VALUE = "ENUM_VALUE"; +const FIELD = "FIELD"; +const SCHEMA = "SCHEMA"; +const INPUT_FIELD_DEFINITION = "INPUT_FIELD_DEFINITION"; +``` + # GraphQL\Type\SchemaConfig Schema configuration class. Could be passed directly to schema constructor. List of options accepted by **create** method is @@ -808,7 +959,6 @@ Implements the "Evaluating requests" section of the GraphQL specification. * @param array|\ArrayAccess $variableValues * @param null $operationName * @param callable $fieldResolver - * @param PromiseAdapter $promiseAdapter * * @return ExecutionResult|Promise */ @@ -819,14 +969,13 @@ static function execute( $contextValue = null, $variableValues = null, $operationName = null, - callable $fieldResolver = null, - GraphQL\Executor\Promise\PromiseAdapter $promiseAdapter = null + callable $fieldResolver = null ) ``` ```php /** - * Same as executeQuery(), but requires promise adapter and returns a promise which is always + * Same as execute(), but requires promise adapter and returns a promise which is always * fulfilled with an instance of ExecutionResult and never rejected. * * Useful for async PHP platforms. @@ -1042,132 +1191,6 @@ function createRejected($reason) */ function all(array $promisesOrValues) ``` -# GraphQL\Type\Definition\ResolveInfo -Structure containing information useful for field resolution process. -Passed as 3rd argument to every field resolver. See [docs on field resolving (data fetching)](data-fetching.md). - -**Class Props:** -```php -/** - * The name of the field being resolved - * - * @api - * @var string - */ -public $fieldName; - -/** - * AST of all nodes referencing this field in the query. - * - * @api - * @var FieldNode[] - */ -public $fieldNodes; - -/** - * Expected return type of the field being resolved - * - * @api - * @var ScalarType|ObjectType|InterfaceType|UnionType|EnumType|ListOfType|NonNull - */ -public $returnType; - -/** - * Parent type of the field being resolved - * - * @api - * @var ObjectType - */ -public $parentType; - -/** - * Path to this field from the very root value - * - * @api - * @var array - */ -public $path; - -/** - * Instance of a schema used for execution - * - * @api - * @var Schema - */ -public $schema; - -/** - * AST of all fragments defined in query - * - * @api - * @var FragmentDefinitionNode[] - */ -public $fragments; - -/** - * Root value passed to query execution - * - * @api - * @var mixed - */ -public $rootValue; - -/** - * AST of operation definition node (query, mutation) - * - * @api - * @var OperationDefinitionNode - */ -public $operation; - -/** - * Array of variables passed to query execution - * - * @api - * @var array - */ -public $variableValues; -``` - -**Class Methods:** -```php -/** - * Helper method that returns names of all fields selected in query for - * $this->fieldName up to $depth levels - * - * Example: - * query MyQuery{ - * { - * root { - * id, - * nested { - * nested1 - * nested2 { - * nested3 - * } - * } - * } - * } - * - * Given this ResolveInfo instance is a part of "root" field resolution, and $depth === 1, - * method will return: - * [ - * 'id' => true, - * 'nested' => [ - * nested1 => true, - * nested2 => true - * ] - * ] - * - * Warning: this method it is a naive implementation which does not take into account - * conditional typed fragments. So use it with care for fields of interface and union types. - * - * @api - * @param int $depth How many levels to include in output - * @return array - */ -function getFieldSelection($depth = 0) -``` # GraphQL\Validator\DocumentValidator Implements the "Validation" section of the spec. @@ -1888,3 +1911,186 @@ function getOriginalInput($key) */ function isReadOnly() ``` +# GraphQL\Utils\BuildSchema +Build instance of `GraphQL\Type\Schema` out of type language definition (string or parsed AST) +See [section in docs](type-system/type-language.md) for details. + +**Class Methods:** +```php +/** + * This takes the ast of a schema document produced by the parse function in + * GraphQL\Language\Parser. + * + * If no schema definition is provided, then it will look for types named Query + * and Mutation. + * + * Given that AST it constructs a GraphQL\Type\Schema. The resulting schema + * has no resolve methods, so execution will use default resolvers. + * + * @api + * @param DocumentNode $ast + * @param callable $typeConfigDecorator + * @return Schema + * @throws Error + */ +static function buildAST(GraphQL\Language\AST\DocumentNode $ast, callable $typeConfigDecorator = null) +``` + +```php +/** + * A helper function to build a GraphQLSchema directly from a source + * document. + * + * @api + * @param DocumentNode|Source|string $source + * @param callable $typeConfigDecorator + * @return Schema + */ +static function build($source, callable $typeConfigDecorator = null) +``` +# GraphQL\Utils\AST +Various utilities dealing with AST + +**Class Methods:** +```php +/** + * Convert representation of AST as an associative array to instance of GraphQL\Language\AST\Node. + * + * For example: + * + * ```php + * Node::fromArray([ + * 'kind' => 'ListValue', + * 'values' => [ + * ['kind' => 'StringValue', 'value' => 'my str'], + * ['kind' => 'StringValue', 'value' => 'my other str'] + * ], + * 'loc' => ['start' => 21, 'end' => 25] + * ]); + * ``` + * + * Will produce instance of `ListValueNode` where `values` prop is a lazily-evaluated `NodeList` + * returning instances of `StringValueNode` on access. + * + * This is a reverse operation for AST::toArray($node) + * + * @api + * @param array $node + * @return Node + */ +static function fromArray(array $node) +``` + +```php +/** + * Convert AST node to serializable array + * + * @api + * @param Node $node + * @return array + */ +static function toArray(GraphQL\Language\AST\Node $node) +``` + +```php +/** + * Produces a GraphQL Value AST given a PHP value. + * + * Optionally, a GraphQL type may be provided, which will be used to + * disambiguate between value primitives. + * + * | PHP Value | GraphQL Value | + * | ------------- | -------------------- | + * | Object | Input Object | + * | Assoc Array | Input Object | + * | Array | List | + * | Boolean | Boolean | + * | String | String / Enum Value | + * | Int | Int | + * | Float | Int / Float | + * | Mixed | Enum Value | + * | null | NullValue | + * + * @api + * @param $value + * @param InputType $type + * @return ObjectValueNode|ListValueNode|BooleanValueNode|IntValueNode|FloatValueNode|EnumValueNode|StringValueNode|NullValueNode + */ +static function astFromValue($value, GraphQL\Type\Definition\InputType $type) +``` + +```php +/** + * Produces a PHP value given a GraphQL Value AST. + * + * A GraphQL type must be provided, which will be used to interpret different + * GraphQL Value literals. + * + * Returns `null` when the value could not be validly coerced according to + * the provided type. + * + * | GraphQL Value | PHP Value | + * | -------------------- | ------------- | + * | Input Object | Assoc Array | + * | List | Array | + * | Boolean | Boolean | + * | String | String | + * | Int / Float | Int / Float | + * | Enum Value | Mixed | + * | Null Value | null | + * + * @api + * @param $valueNode + * @param InputType $type + * @param null $variables + * @return array|null|\stdClass + * @throws \Exception + */ +static function valueFromAST($valueNode, GraphQL\Type\Definition\InputType $type, $variables = null) +``` + +```php +/** + * Returns type definition for given AST Type node + * + * @api + * @param Schema $schema + * @param NamedTypeNode|ListTypeNode|NonNullTypeNode $inputTypeNode + * @return Type + * @throws InvariantViolation + */ +static function typeFromAST(GraphQL\Type\Schema $schema, $inputTypeNode) +``` + +```php +/** + * Returns operation type ("query", "mutation" or "subscription") given a document and operation name + * + * @api + * @param DocumentNode $document + * @param string $operationName + * @return bool + */ +static function getOperation(GraphQL\Language\AST\DocumentNode $document, $operationName = null) +``` +# GraphQL\Utils\SchemaPrinter +Given an instance of Schema, prints it in GraphQL type language. + +**Class Methods:** +```php +/** + * @api + * @param Schema $schema + * @return string + */ +static function doPrint(GraphQL\Type\Schema $schema) +``` + +```php +/** + * @api + * @param Schema $schema + * @return string + */ +static function printIntrosepctionSchema(GraphQL\Type\Schema $schema) +``` diff --git a/docs/security.md b/docs/security.md index 57a23e7..5f1cc61 100644 --- a/docs/security.md +++ b/docs/security.md @@ -21,7 +21,7 @@ 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). +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 @@ -51,7 +51,7 @@ $type = new ObjectType([ # 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**. +For example, max depth of the introspection query is **7**. It is disabled by default. To enable it, add following validation rule: @@ -67,16 +67,16 @@ 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). +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 autocompletion, query validation, etc. +It is used by tools like GraphiQL for auto-completion, query validation, etc. -Introspection is enabled by default. It means that anybody can get full description of your schema by -sending special query containing meta fields **__type** and **__schema** . +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 general public, it makes sense to disable this feature. +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: @@ -91,4 +91,4 @@ 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). +This will set the rule globally. Alternatively, you can provide validation rules [per execution](executing-queries.md#custom-validation-rules). diff --git a/docs/type-system/directives.md b/docs/type-system/directives.md index 5bdced6..6b12588 100644 --- a/docs/type-system/directives.md +++ b/docs/type-system/directives.md @@ -1,12 +1,12 @@ # Built-in directives -Directive is a way for client to give GraphQL server additional context and hints on how to execute -the query. Directive can be attached to a field or fragment inclusion, and can affect execution of the +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` +* **@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 @@ -19,47 +19,43 @@ query Hero($episode: Episode, $withFriends: Boolean!) { } } ``` -Here if `$withFriends` variable is set to `false` - friends section will be ignored and excluded -from response. Important implementation detail: those fields will never be executed +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 execution of fields. -But you can use `GraphQL\Type\Definition\ResolveInfo` in field resolvers to modify the output depending -on those directives or perform statistics collection. +**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 it subclasses) which accepts an array with following options: +(or one of its subclasses) which accepts an array of following options: ```php + 'track', - 'description' => 'Instruction to record usage of the field by client' + 'description' => 'Instruction to record usage of the field by client', 'locations' => [ - Directive::LOCATION_FIELD, + DirectiveLocation::FIELD, ], 'args' => [ new FieldArgument([ 'name' => 'details', 'type' => Type::string(), - 'description' => 'String with additional details of field usage scenario' + 'description' => 'String with additional details of field usage scenario', 'defaultValue' => '' ]) ] ]); ``` -Directive location can be one of the following values: - -* `Directive::LOCATION_QUERY` -* `Directive::LOCATION_MUTATION` -* `Directive::LOCATION_SUBSCRIPTION` -* `Directive::LOCATION_FIELD` -* `Directive::LOCATION_FRAGMENT_DEFINITION` -* `Directive::LOCATION_FRAGMENT_SPREAD` -* `Directive::LOCATION_INLINE_FRAGMENT` +See possible directive locations in +[`GraphQL\Type\Definition\DirectiveLocation`](../reference.md#graphqltypedefinitiondirectivelocation). diff --git a/docs/type-system/enum-types.md b/docs/type-system/enum-types.md index b2c5866..4cebdec 100644 --- a/docs/type-system/enum-types.md +++ b/docs/type-system/enum-types.md @@ -6,6 +6,7 @@ In **graphql-php** enum type is an instance of `GraphQL\Type\Definition\EnumType which accepts configuration array in constructor: ```php + 'Episode', 'description' => 'One of the films in the Star Wars Trilogy', @@ -64,6 +68,9 @@ $episodeEnum = new EnumType([ which is equivalent of: ```php + 'Episode', 'description' => 'One of the films in the Star Wars Trilogy', @@ -75,9 +82,12 @@ $episodeEnum = new EnumType([ ]); ``` -which is in turn equivalent of full form: +which is in turn equivalent of the full form: ```php + 'Episode', 'description' => 'One of the films in the Star Wars Trilogy', @@ -90,11 +100,12 @@ $episodeEnum = new EnumType([ ``` # Field Resolution -When object field is of Enum Type, field resolver is expected to return internal +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 + 'Hero', 'fields' => [ @@ -142,17 +157,17 @@ $heroType = new ObjectType([ 'type' => Type::boolean(), 'args' => [ 'episode' => Type::nonNull($enumType) - ] + ], 'resolve' => function($_value, $args) { return $args['episode'] === 5 ? true : false; } ] ] -]) +]); ``` Then following query: -``` +```graphql fragment on Hero { appearsInNewHope: appearsIn(NEWHOPE) appearsInEmpire: appearsIn(EMPIRE) diff --git a/docs/type-system/index.md b/docs/type-system/index.md index 942ea15..5aea26c 100644 --- a/docs/type-system/index.md +++ b/docs/type-system/index.md @@ -1,9 +1,10 @@ # 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: `ScalarType`, `ObjectType`, `InterfaceType`, -`UnionType`, `InputObjectType` (or one of it's subclasses). +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). @@ -68,16 +69,16 @@ input HelloInput { } ``` -[Read more](type-language.md) about it in a dedicated docs section. +Read more about type language definitions in a [dedicated docs section](type-language.md). # Type Registry -Every type must be presented in Schema by single instance (**graphql-php** -throws when it discovers several instances with the same `name` in schema). +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 schema. +instance of that class is added to the schema. -Typical way to do this is to create registry of your types: +The typical way to do this is to create a registry of your types: ```php '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 -GraphQL receives data from clients via [Field Arguments](object-types.md#field-arguments). - -Both - fields and arguments require **type** option in definition. But expected value of this option -is different for fields and arguments, as in GraphQL argument is conceptually input while field is conceptually -output. - -Consequentially all types in GraphQL are of two categories: **input** and **output**. +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 +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 easily pass complex objects. +[Enum](enum-types.md) types. But you can also pass complex objects. -This is particularly valuable in the case of mutations, where input data might be rather complex. +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` +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 + 'StoryFiltersInput', 'fields' => [ @@ -50,12 +99,12 @@ $filters = new InputObjectType([ Every field may be of other InputObjectType (thus complex hierarchies of inputs are possible) # Configuration options -Constructor of InputObjectType accepts array with only 3 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 `callback` returning `array` | **Required**. Array describing object fields (see below). +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: @@ -63,7 +112,7 @@ 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 `List` modifiers) +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 @@ -71,6 +120,10 @@ defaultValue | `scalar` | Default value of this input field In the example above we defined our InputObjectType. Now let's use it in one of field arguments: ```php + 'Query', 'fields' => [ diff --git a/docs/type-system/interfaces.md b/docs/type-system/interfaces.md index 62a6e26..5335d6d 100644 --- a/docs/type-system/interfaces.md +++ b/docs/type-system/interfaces.md @@ -3,9 +3,10 @@ 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 it subclasses) which accepts configuration array in constructor: +(or one of its subclasses) which accepts configuration array in a constructor: ```php + 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 + 'Human', 'fields' => [ @@ -71,7 +76,7 @@ The only exception is when object's field type is more specific than the type of (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 field type to more specific. +Object types implementing interface may change the field type to more specific. Example: ``` @@ -86,9 +91,13 @@ type B implements A { # Sharing Interface fields Since every Object Type implementing an Interface must have the same set of fields - it often makes -sense to re-use field definitions of Interface in Object Types: +sense to reuse field definitions of Interface in Object Types: ```php + 'Human', 'interfaces' => [ @@ -102,26 +111,26 @@ $humanType = new ObjectType([ ]); ``` -In this case field definitions are created only once (as a part of Interface Type) and then -re-used by all interface implementors. It can save several microseconds and kilobytes + ensures that +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 resolution of such fields. There are two ways how shared fields could +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 from implementor to implementor - you can specify **resolveField** +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 +for given **$value** in **resolveType**. Then resolution of fields is delegated to resolvers of this concrete Object Type. -If **resolveType** option is omitted, **graphql-php** will loop through all interface implementors and +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. diff --git a/docs/type-system/lists-and-nonnulls.md b/docs/type-system/lists-and-nonnulls.md index 451575a..8f3743d 100644 --- a/docs/type-system/lists-and-nonnulls.md +++ b/docs/type-system/lists-and-nonnulls.md @@ -21,17 +21,18 @@ $userType = new ObjectType([ ]); ``` -Resolvers for such fields are expected to return `array` or instance of PHP internal `Traversable` -interface (`null` is allowed by default too). +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 field value to `null` (only if field is nullable, see below for non-null fields). +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 `null` value. To indicate that some field always -returns `non-null` value - use `GraphQL\Type\Definition\Type::nonNull()` modifier: +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 +fieldName`. Good place to define type-specific strategy for field resolution. See section on [Data Fetching](../data-fetching.md) for details. +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)**
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)**
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: @@ -78,10 +78,10 @@ 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.** Instance of internal or custom type. Note: type must be represented by single instance within schema (see also [Type Registry](index.md#type-registry)) -args | `array` | 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($value, $args, $context, GraphQL\Type\Definition\ResolveInfo $info)** Given the `$value` of this type it is expected to return value for current field. See section on [Data Fetching](../data-fetching.md) for details -complexity | `callable` | **function($childrenComplexity, $args)** Used to restrict query complexity. Feature is disabled by default, read section about [Security](../security.md#query-complexity-analysis) to use it. +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($value, $args, $context, [ResolveInfo](../reference.md#graphqltypedefinitionresolveinfo) $info)**
Given the **$value** 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)**
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) @@ -92,7 +92,7 @@ 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) +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 @@ -111,7 +111,7 @@ which is equivalent of: 'fieldName' => ['type' => $fieldName] ] ``` -which is in turn equivalent of full form: +which is in turn equivalent of the full form: ```php 'fields' => [ ['name' => 'id', 'type' => Type::id()], @@ -124,11 +124,15 @@ Same shorthand notation applies to field arguments as well. 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 `callback` in +**graphql-php** allows such types, but you have to use `callable` in option **fields** (and/or **interfaces**). For example: ```php + 'Query', @@ -37,7 +38,7 @@ $queryType = new ObjectType([ 'resolve' => function() { return 'Hello World!'; } - ] + ], 'hero' => [ 'type' => $characterInterface, 'args' => [ @@ -55,8 +56,8 @@ $queryType = new ObjectType([ $mutationType = new ObjectType([ 'name' => 'Mutation', 'fields' => [ - 'createReviewForEpisode' => [ - 'type' => $createReviewForEpisodeMutation, + 'createReview' => [ + 'type' => $createReviewOutput, 'args' => [ 'episode' => $episodeEnum, 'review' => $reviewInputObject @@ -69,13 +70,13 @@ $mutationType = new ObjectType([ ]); ``` -Keep in mind that other than the special meaning of declaring surface area of your API, +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 [Input Types](input-types.md) for details). +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) @@ -86,14 +87,15 @@ 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[]` | Full list of [directives](directives.md) supported by your schema. By default contains built-in `@skip` and `@include` directives.

If you pass your own directives and still want to use built-in directives - add them explicitly. For example: `array_merge(GraphQL::getStandardDirectives(), [$myCustomDirective]` -types | `ObjectType[]` | List of object types which cannot be detected by **graphql-php** during static schema analysis.

Most often it happens when object type is never referenced in fields directly, but is still a part of schema because it implements an interface which resolves to this object type in it's `resolveType` callback.

Note that you are not required to pass all of your types here - it is simply a workaround for concrete use-case. +directives | `Directive[]` | A full list of [directives](directives.md) supported by your schema. By default, contains built-in **@skip** and **@include** directives.

If you pass your own directives and still want to use built-in directives - add them explicitly. For example:

*array_merge(GraphQL::getStandardDirectives(), [$myCustomDirective]);* +types | `ObjectType[]` | List of object types which cannot be detected by **graphql-php** during static schema analysis.

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.

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. # Lazy loading of types -By default a schema will scan all of your type and field definitions to serve GraphQL queries. -It may cause performance overhead when there are many types in a schema. +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 +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 @@ -101,9 +103,13 @@ always return the same instance of a type. Usage example: ```php +assertValid()` which throws `GraphQL\Error\InvariantViolation` -exception when it encounters any error, like: +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 +- Invalid types used for fields/arguments - Missing interface implementations - Invalid interface implementations - Other schema errors... @@ -159,11 +165,11 @@ Don't call it in web requests in production. Usage example: ```php -$schema = new GraphQL\Type\Schema([ - 'query' => $myQueryType -]); - + $myQueryType + ]); $schema->assertValid(); } catch (GraphQL\Error\InvariantViolation $e) { echo $e->getMessage(); diff --git a/docs/type-system/type-language.md b/docs/type-system/type-language.md index 583a43a..094f332 100644 --- a/docs/type-system/type-language.md +++ b/docs/type-system/type-language.md @@ -3,7 +3,7 @@ [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 separate **schema.graphql** file): +Here is a simple schema defined in GraphQL type language (e.g. in a separate **schema.graphql** file): ```graphql schema { @@ -21,7 +21,8 @@ input HelloInput { } ``` -In order to create schema instance out of this file, use `GraphQL\Utils\BuildSchema`: +In order to create schema instance out of this file, use +[`GraphQL\Utils\BuildSchema`](../reference.md#graphqlutilsbuildschema): ```php toArray(), true)); } else { - $document = Node::fromArray(require $cacheFilename); // fromArray() is a lazy operation as well + $document = AST::fromArray(require $cacheFilename); // fromArray() is a lazy operation as well } $typeConfigDecorator = function () {}; diff --git a/docs/type-system/unions.md b/docs/type-system/unions.md index 6b7cae5..9ef4fd3 100644 --- a/docs/type-system/unions.md +++ b/docs/type-system/unions.md @@ -1,17 +1,20 @@ # Union Type Definition A Union is an abstract type that simply enumerates other Object Types. -Value of Union Type is actually a value of one of included 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 it subclasses) which accepts configuration array in constructor: +(or one of its subclasses) which accepts configuration array in a constructor: ```php + 'SearchResult', 'types' => [ MyTypes::story(), MyTypes::user() - ]; + ], 'resolveType' => function($value) { if ($value->type === 'story') { return MyTypes::story(); @@ -26,11 +29,11 @@ This example uses **inline** style for Union definition, but you can also use [inheritance or type language](index.md#type-definition-styles). # Configuration options -Constructor of UnionType accepts an array. Below is a full list of allowed 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` returning instance of `ObjectType` | **function($value, $context, GraphQL\Type\Definition\ResolveInfo $info)** Any `callable` that receives `$value` from resolver of the parent field and returns Object Type for that `$value`. +resolveType | `callback` | **function($value, $context, [ResolveInfo](../reference.md#graphqltypedefinitionresolveinfo) $info)**
Receives **$value** from resolver of the parent field and returns concrete Object Type for this **$value**. diff --git a/mkdocs.yml b/mkdocs.yml index 0a9cd76..474c883 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,7 +11,7 @@ pages: - Lists and Non-Null: type-system/lists-and-nonnulls.md - Interfaces: type-system/interfaces.md - Unions: type-system/unions.md - - Input Types: type-system/input-types.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