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 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 istrue
@skip(if: Boolean)
Skip this field or fragment if the argument istrue
For example:
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 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.
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:
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' => [
Directive::LOCATION_FIELD,
],
'args' => [
new FieldArgument([
'name' => 'details',
'type' => Type::string(),
'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