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 is true
  • @skip(if: Boolean) Skip this field or fragment if the argument is true

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