mirror of
https://github.com/retailcrm/graphql-php.git
synced 2024-11-21 20:36:05 +03:00
Work in progress on better docs (added docs for field arguments and input types)
This commit is contained in:
vladar
parent
3514b5ac83
commit
ca01900e9d
@ -5,7 +5,7 @@ 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).
|
||||
|
||||
But most of the types in your schema will be [object types](object-types/).
|
||||
But most of the types in your schema will be [object types](/type-system/object-types/).
|
||||
|
||||
# Type Definition Styles
|
||||
Several styles of type definitions are supported depending on your preferences.
|
||||
@ -155,4 +155,4 @@ Obviously you can automate this registry as you wish to reduce boilerplate or ev
|
||||
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 `MyTypes::myAType()` in your type definitions.
|
||||
to pass it in constructor - instead just use use `TypeRegistry::myAType()` in your type definitions.
|
||||
|
||||
119
docs/type-system/input-types.md
Normal file
119
docs/type-system/input-types.md
Normal file
@ -0,0 +1,119 @@
|
||||
# About Input and Output Types
|
||||
GraphQL receives data from clients via [Field Arguments](object-types/#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**.
|
||||
|
||||
* **Output** types (or field types) are: [Scalar](scalar-types/), [Enum](enum-types/), [Object](object-types/),
|
||||
[Interface](interfaces/), [Union](unions/)
|
||||
|
||||
* **Input** types (or argument types) are: [Scalar](scalar-types/), [Enum](enum-types/), InputObject
|
||||
|
||||
Obviously [NonNull and List](lists-and-nonnulls/) 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/) or
|
||||
[Enum](enum-types/) types. But you can also easily pass complex objects.
|
||||
|
||||
This is particularly valuable in the 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
|
||||
$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
|
||||
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).
|
||||
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/) (`Scalar`, `Enum`, `InputObjectType` + any combination of those with `NonNull` and `List` 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
|
||||
|
||||
# Using Input Object Type
|
||||
In the example above we defined our InputObjectType. Now let's use it in one of field arguments:
|
||||
|
||||
```php
|
||||
$queryType = new ObjectType([
|
||||
'name' => 'Query',
|
||||
'fields' => [
|
||||
'stories' => [
|
||||
'type' => Type::listOf($storyType),
|
||||
'args' => [
|
||||
'filters' => [
|
||||
'type' => Type::nonNull($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']`
|
||||
@ -77,16 +77,26 @@ 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 array key (read about [shorthand field definition](#) below)
|
||||
name | `string` | **Required.** Name of the field. When not set - inferred from **fields** array key (read about [shorthand field definition](#) below)
|
||||
type | `Type` | **Required.** Instance of internal or custom type. Note: type must be represented by single instance within schema (see also [Type Registry](#))
|
||||
args | `array` | Array of possible type arguments. Each entry is expected to be an array with keys: **name**, **type**, **description**, **defaultValue**
|
||||
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 | `callback` | **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](#) for details
|
||||
description | `string` | Plain-text description of this field description for clients (e.g. used by [GraphiQL](https://github.com/graphql/graphiql) for auto-generated documentation)
|
||||
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/) (`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
|
||||
|
||||
# Shorthand field definitions
|
||||
Fields can be also defined in **shorthand** notation (without `description`, `args` and `defaultValue`):
|
||||
Fields can be also defined in **shorthand** notation (with only **name** and **type** options):
|
||||
```php
|
||||
'fields' => [
|
||||
'id' => Type::id(),
|
||||
|
||||
@ -2,7 +2,7 @@ site_name: graphql-php
|
||||
pages:
|
||||
- About: index.md
|
||||
- Getting Started: getting-started.md
|
||||
- Schema Definition:
|
||||
- Type System:
|
||||
- Introduction: type-system/index.md
|
||||
- Object Types: type-system/object-types.md
|
||||
- Scalar Types: type-system/scalar-types.md
|
||||
@ -10,6 +10,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
|
||||
- Defining Schema: type-system/schema.md
|
||||
- Custom Metadata: type-system/metadata.md
|
||||
- Data Fetching: data-fetching.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user