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.

Writing Object Types¶

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

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' => fn (Story $blogStory): ?User => 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' => fn (Story $blogStory, array $args): array => DataSource::findLikes($blogStory->id, $args['limit']),
        ]
    ]
]);

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

Configuration 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 field configuration options 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): bool Expected to return true if $value qualifies for this type (see section about Abstract Type Resolution for explanation).
resolveField	`callable`	function ($value, array $args, $context, ResolveInfo $info): mixed 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.
argsMapper	`callable`	function (array $args, FieldDefinition, FieldNode): mixed Called once, when Executor resolves arguments for given field. Could be used to validate args and/or to map them to DTO/Object.
visible	`bool` or `callable`	Defaults to `true`. The given callable receives no arguments and is expected to return a `bool`, it is called once when the field may be accessed. The field is treated as if it were not defined at all when this is `false`.

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 lazy loading of types)
args	`array`	An array describing any number of possible field arguments, each element being an array. See field argument configuration options.
resolve	`callable`	function ($objectValue, array $args, $context, ResolveInfo $info): mixed Given the $objectValue of this type, it is expected to return actual value of the current field. See section on Data Fetching for details
complexity	`callable`	function (int $childrenComplexity, array $args): int 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 argument configuration 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. Use the internal value if specifying a default for an enum type

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:

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

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

Same example for inheritance style of type definitions using a type registry (see lazy loading of types):

use GraphQL\Type\Definition\ListOfType;
use GraphQL\Type\Definition\ScalarType;
use GraphQL\Type\Definition\Type;
use GraphQL\Type\Definition\ObjectType;

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

class MyTypes
{
    private static UserType $user;

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

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

    public static function listOf($type): ListOfType
    {
        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.