Object Type Definition

Object Type is the most frequently used primitive in a typical GraphQL application.

Conceptually Object Type is a collection of Fields. Each field, in turn, has its own type which allows building complex hierarchies.

In graphql-php object type is an instance of GraphQL\Type\Definition\ObjectType (or one of it subclasses) which accepts configuration array in constructor:

<?php
namespace MyApp;

use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;
use GraphQL\Examples\Blog\Data\DataSource;
use GraphQL\Examples\Blog\Data\Story;

$userType = new ObjectType([
    'name' => 'User',
    'description' => 'Our blog visitor',
    'fields' => [
        'firstName' => [
            'type' => Type::string(),
            'description' => 'User first name'
        ],
        'email' => Type::string()
    ]
]);

$blogStory = new ObjectType([
    'name' => 'Story',
    'fields' => [
        'body' => Type::string(),
        'author' => [
            'type' => $userType,
            'description' => 'Story author',
            'resolve' => function(Story $blogStory) {
                return DataSource::findUser($blogStory->authorId);
            }
        ],
        'likes' => [
            'type' => Type::listOf($userType),
            'description' => 'List of users who liked the story',
            'args' => [
                'limit' => [
                    'type' => Type::int(),
                    'description' => 'Limit the number of recent likes returned',
                    'defaultValue' => 10
                ]
            ],
            'resolve' => function(Story $blogStory, $args) {
                return DataSource::findLikes($blogStory->id, $args['limit']);
            }
        ]
    ]
]);

This example uses inline style for Object Type definitions, but you can also use
inheritance or type language.

Configuration options

Object type constructor expects configuration array. Below is a full list of available options:

Option Type Notes
name string Required. Unique name of this object type within Schema
fields array or callable Required. An array describing object fields or callable returning such an array. See Fields section below for expected structure of each array entry. See also the section on Circular types for an explanation of when to use callable for this option.
description string Plain-text description of this type for clients (e.g. used by GraphiQL for auto-generated documentation)
interfaces array or callable List of interfaces implemented by this type or callable returning such a list. See Interface Types for details. See also the section on Circular types for an explanation of when to use callable for this option.
isTypeOf callable function($value, $context, ResolveInfo $info)
Expected to return true if $value qualifies for this type (see section about Abstract Type Resolution for explanation).
resolveField callable function($value, $args, $context, ResolveInfo $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 for details.

Field configuration options

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 below)
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)
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 section below.
resolve callable function($value, $args, $context, ResolveInfo $info)
Given the $value of this type, it is expected to return actual value of the current field. See section on Data Fetching for details
complexity callable function($childrenComplexity, $args)
Used to restrict query complexity. The feature is disabled by default, read about Security to use it.
description string Plain-text description of this field for clients (e.g. used by 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 (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 for auto-generated documentation)
defaultValue scalar Default value for this argument

Shorthand field definitions

Fields can be also defined in shorthand notation (with only name and type options):

'fields' => [
    'id' => Type::id(),
    'fieldName' => $fieldType
]

which is equivalent of:

'fields' => [
    'id' => ['type' => Type::id()],
    'fieldName' => ['type' => $fieldName]
]

which is in turn equivalent of the full form:

'fields' => [
    ['name' => 'id', 'type' => Type::id()],
    ['name' => 'fieldName', 'type' => $fieldName]
]

Same shorthand notation applies to field arguments as well.

Recurring and circular types

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 callable in option fields (and/or interfaces).

For example:

<?php
use GraphQL\Type\Definition\Type;
use GraphQL\Type\Definition\ObjectType;

$userType = null;

$userType = new ObjectType([
    'name' => 'User',
    'fields' => function() use (&$userType) {
        return [
            'email' => [
                'type' => Type::string()
            ],
            'friends' => [
                'type' => Type::listOf($userType)
            ]
        ];
    }
]);

Same example for inheritance style of type definitions using TypeRegistry:

<?php
namespace MyApp;

use GraphQL\Type\Definition\Type;
use GraphQL\Type\Definition\ObjectType;

class UserType extends ObjectType
{
    public function __construct()
    {
        $config = [
            'fields' => function() {
                return [
                    'email' => MyTypes::string(),
                    'friends' => MyTypes::listOf(MyTypes::user())
                ];
            }
        ];
        parent::__construct($config);
    }
}

class MyTypes 
{
    private static $user;

    public static function user()
    {
        return self::$user ?: (self::$user = new UserType());
    }

    public static function string()
    {
        return Type::string();
    }

    public static function listOf($type)
    {
        return Type::listOf($type);
    }
}

Field Resolution

Field resolution is the primary mechanism in graphql-php for returning actual data for your fields. It is implemented using resolveField callable in type definition or resolve callable in field definition (which has precedence).

Read the section on Data Fetching for a 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.