diff --git a/docs/executing-queries.md b/docs/executing-queries.md index 718290d..015539f 100644 --- a/docs/executing-queries.md +++ b/docs/executing-queries.md @@ -1,6 +1,6 @@ # Overview Query execution is a complex process involving multiple steps, including query **parsing**, -**validating** and finally **executing** against your schema. +**validating** and finally **executing** against your [schema](type-system/schema/). **graphql-php** provides convenient facade for this process in class `GraphQL\GraphQL`: @@ -34,12 +34,11 @@ contextValue | `mixed` | Any value that holds information shared between all fi 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. +# Parsing Following reading describes implementation details of query execution process. It may clarify some internals of GraphQL but is not required in order to use it. Feel free to skip to next section on [Error Handling](error-handling/) for essentials. - -# Parsing TODOC # Validating diff --git a/docs/type-system/index.md b/docs/type-system/index.md index 7ea1a17..e4a41f1 100644 --- a/docs/type-system/index.md +++ b/docs/type-system/index.md @@ -1,5 +1,5 @@ # Type System -To start using GraphQL you are expected to implement a Type system. +To start using GraphQL you are expected to implement a type hierarchy and expose it as [Schema](type-system/schema/). In **graphql-php** `type` is an instance of internal class from `GraphQL\Type\Definition` namespace: `ScalarType`, `ObjectType`, `InterfaceType`, @@ -156,10 +156,3 @@ introduce Dependency Injection Container if your types have other dependencies. Alternatively all methods of registry could be static if you prefer - then there is no need to pass it in constructor - instead just use use `TypeRegistry::myAType()` in your type definitions. - -# 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. diff --git a/docs/type-system/object-types.md b/docs/type-system/object-types.md index 1727b4c..f8f5226 100644 --- a/docs/type-system/object-types.md +++ b/docs/type-system/object-types.md @@ -195,4 +195,11 @@ Field resolution is the primary mechanism in **graphql-php** for returning actua It is implemented using `resolveField` callback in type definition or `resolve` callback in field definition (which has precedence). -Read section on [Data Fetching]() for complete description of this process. \ No newline at end of file +Read section on [Data Fetching]() for 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. diff --git a/docs/type-system/schema.md b/docs/type-system/schema.md index 14a701d..c795394 100644 --- a/docs/type-system/schema.md +++ b/docs/type-system/schema.md @@ -1,7 +1,6 @@ # Schema Definition - -After all of your types are defined, you must define schema. Schema is a container for your type -hierarchy, which expects root type in constructor. +Schema is a container of your type hierarchy, which accepts root types in constructor and provides +methods for receiving information about your types to internal GrahpQL tools. In **graphql-php** schema is an instance of `GraphQL\Schema` which accepts configuration array in constructor: @@ -12,25 +11,16 @@ $schema = new Schema([ 'mutation' => $mutationType, ]); ``` - -# Configuration 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[]` | Full list of [directives](directives/) 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::getInternalDirectives(), [$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. - +See possible constructor options [below](#configuration-options) # Query and Mutation types -Schema consists of two special root types: +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 containing root-level fields of your API: +Query and Mutation types are regular [object types](object-types/) containing root-level fields +of your API: ```php use GraphQL\Type\Definition\ObjectType; @@ -64,13 +54,13 @@ $mutationType = new ObjectType([ 'name' => 'Mutation', 'fields' => [ 'createReviewForEpisode' => [ - 'type' => $createReviewForEpisode, + 'type' => $createReviewForEpisodeMutation, 'args' => [ 'episode' => $episodeEnum, 'review' => $reviewInputObject ], - 'resolve' => function() { - + 'resolve' => function($val, $args) { + // TODOC } ] ] @@ -78,11 +68,20 @@ $mutationType = new ObjectType([ ``` Keep in mind that other than the special meaning of declaring surface area of your API, -those types are the same as any other object type, and their fields work exactly the same way. +those types are the same as any other [object type](object-types/), and their fields work +exactly the same way. -Resolvers of those fields receive `$rootValue` which you pass into execute call: -`GraphQL::execute($schema, $query, $rootValue)` - -`Mutation` type is also just a regular object type. The difference is in semantics. +**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/) for details). + +# Configuration Options +Schema constructor expects 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[]` | Full list of [directives](directives/) 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::getInternalDirectives(), [$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. diff --git a/mkdocs.yml b/mkdocs.yml index a916917..394c8b1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,7 +12,7 @@ pages: - Unions: type-system/unions.md - Input Types: type-system/input-types.md - Directives: type-system/directives.md - - Defining Schema: type-system/schema.md + - Schema: type-system/schema.md - Executing Queries: executing-queries.md - Handling Errors: error-handling.md - Fetching Data: data-fetching.md