GraphQL Schema

GraphQL schema library.

Install

$ composer require oligus/schema

Contents

Quick start
Types
Type modifiers
Scalar
Built in scalar types
Objects
Interfaces
Enums
Inputs
Fields
Arguments
Argument values
Development

Quick start

$schema = newSchema();
// Add directive$directive = newDirectiveType('upper');
$directive->addLocation(ExecutableDirectiveLocation::FIELD());
$schema->addDirective($directive);
// Add interface$interface = (newInterfaceType('Entity'))
->addField(newField('id', newIDType(), newTypeModifier(false)))
->addField(newField('name', newStringType()));
$schema->addInterface($interface);
// Add scalar$scalar = newScalarType('Url');
$schema->addScalar($scalar);
// Add object$object = (newObjectType('User'))
->addField(newField('id', newIDType(), newTypeModifier(false)))
->addField(newField('name', newStringType()))
->addField(newField('age', newIntegerType()))
->addField(newField('balance', newFloatType()))
->addField(newField('isActive', newBooleanType()));
$object->addField(newField('friends', $object, newTypeModifier(true, true, false)))
->addField(newField('homepage', $scalar))
->implements($interface);
$schema->addObject($object);
// Add query object$query = (newObjectType('Query'))
->addField(newField('me', $object, newTypeModifier(true)));
$field = (newField('friends', $object, newTypeModifier(true, true, false)))
->addArgument(newArgument('limit', newIntegerType(), newTypeModifier(), newValueInteger(10)));
$query->addField($field);
$schema->addObject($query);
// Add input object$input = (newInputType('ListUsersInput'))
->addField(newField('limit', newIntegerType()))
->addField(newField('since_id', newIDType()));
$schema->addInput($input);
// Add mutation object$mutation = newObjectType('Mutation');
$field = (newField('users', $object, newTypeModifier(true, true, false)))
->addArgument(newArgument('params', $input));
$mutation->addField($field);
$schema->addObject($mutation);
// Add union$union = (newUnionType('MyUnion'))
->addObjectType(newObjectType('Dog'))
->addObjectType(newObjectType('Cat'))
->addObjectType(newObjectType('Bird'));
$schema->addUnion($union);
// Set root types$schema->setQuery($query);
$schema->setMutation($mutation);
$serializer = newSchemaSerializer();
$serializer->serialize($schema);

Result:

directive@upperonFIELDinterfaceEntity {
id: ID!name: String
}
scalarUrlunionMyUnion = Dog | Cat | BirdtypeUserimplementsEntity {
id: ID!name: Stringage: Intbalance: FloatisActive: Booleanfriends: [User]!homepage: Url
}
typeQuery {
me: Userfriends(limit: Int = 10): [User]!
}
typeMutation {
users(params: ListUsersInput): [User]!
}
inputListUsersInput {
limit: Intsince_id: ID
}
schema {
query: Querymutation: Mutation
}

Types

The fundamental unit of any GraphQL Schema is the type. There are six kinds of named type definitions in GraphQL, and two wrapping types.

GrapQL Spec

Available types:

ScalarType
BooleanType
FloatType
IDType
IntegerType
StringType
InterfaceType

Type modifiers

Type modifiers are used in conjunction with types, add modifier to a type to modify the type in question.

Definition

TypeModifier(?bool $nullable, ?bool $listable, ?bool $nullableList)

Modifiers

Type	Syntax	Example
Nullable Type	<type>	String
Non-null Type	<type>!	String!
List Type	[<type>]	[String]
List of Non-null Types	[<type>!]	[String!]
Non-null List Type	[<type>]!	[String]!
Non-null List of Non-null Types	[<type>!]!	[String!]!

Examples

$typeModifier = newTypeModifier($nullable = false, $listable = true, $nullableList = false);
$type = newBooleanType($typeModifier);

Result:

[bool!]!

Scalar

Scalar types represent primitive leaf values in a GraphQL type system. GraphQL responses take the form of a hierarchical tree; the leaves on these trees are GraphQL scalars.

GrapQL Spec

Definition

Scalar(string $name, ?string $description)

Examples

$scalar = newScalarType('Url', 'Url description');

Result:

"""Url description"""scalarUrl

Built in scalar types

GraphQL provides a basic set of well‐defined Scalar types. A GraphQL server should support all of these types.

Built in types:Boolean, Float, ID, Integer, String

GrapQL Spec

Definition

<TYPE>Type(?TypeModifier $modifier)

Where <TYPE> is Boolean, Float, ID, Integer or String

Examples

$type = newBooleanType();

Result:

Boolean

Objects

GraphQL queries are hierarchical and composed, describing a tree of information. While Scalar types describe the leaf values of these hierarchical queries, Objects describe the intermediate levels.

GrapQL Spec

Definition

ObjectType(string $name, ?string $description = null)

Examples

$object = newObjectType('Wine');
$object->addField(newField('name', newStringType()));
$object->addField(newField('age', newIntegerType()));
$object->addField(newField('size', newIntegerType()));

Result:

typeWine {
name: Stringage: Intsize: Int
}

Implement interface

$interface = newInterfaceType('Wine');
$interface->addField(newField('name', newStringType()));
$object->implements($interface);

Result:

typeWineimplementsName {
name: Stringage: Intsize: Int
}

Interfaces

GraphQL interfaces represent a list of named fields and their arguments. GraphQL objects can then implement these interfaces which requires that the object type will define all fields defined by those interfaces.

GrapQL Spec

Definition

InterfaceType(string $name, ?string $description = null)

Examples

$interface = newInterfaceType('Wine');
$interface->addField(newField('name', newStringType()));
$interface->addField(newField('age', newIntegerType()));
$interface->addField(newField('size', newIntegerType()));

Result:

interfaceWine {
name: Stringage: Intsize: Int
}

Unions

GraphQL Unions represent an object that could be one of a list of GraphQL Object types, but provides for no guaranteed fields between those types. They also differ from interfaces in that Object types declare what interfaces they implement, but are not aware of what unions contain them.

GrapQL Spec

Definitions

UnionType(string $name, ?string $description = null)

Add object:

addObjectType(ObjectType $objectType): void

Examples

$union = newUnionType('Animals');
$union->addObjectType(newObjectType('Dog'));
$union->addObjectType(newObjectType('Cat'));

Result:

unionAnimals = Dog | Cat

Enums

GraphQL Enum types, like scalar types, also represent leaf values in a GraphQL type system. However Enum types describe the set of possible values.

GrapQL Spec

Definitions

EnumType(string $name, ?string $description = null, array $enums = [])

Add enum:

add(string $enum)

Examples

$enum = newEnumType('Direction', 'Different directions', ['SOUTH', 'NORTH']);
$enum->addEnum('EAST');
$enum->addEnum('WEST');

Result:

"""Different directions"""enumDirection {
 SOUTH NORTH EAST WEST
}

Directives

A GraphQL schema describes directives which are used to annotate various parts of a GraphQL document as an indicator that they should be evaluated differently by a validator, executor, or client tool such as a code generator.

GrapQL Spec

Definitions

EnumType(string $name, ?string $description = null, array $enums = [])

Add locations:

add(ExecutableDirectiveLocation $location)

Examples

$directive = newDirectiveType('example', 'Example directive');
$directive->addLocation(ExecutableDirectiveLocation::FIELD());
$directive->addLocation(ExecutableDirectiveLocation::INLINE_FRAGMENT());

Result:

"""Example directive"""directive@exampleonFIELD | FRAGMENT_SPREAD

Inputs

Fields may accept arguments to configure their behavior. These inputs are often scalars or enums, but they sometimes need to represent more complex values.

GrapQL Spec

Definition

InputType(string $name, ?string $description = null)

Add field:

addField(Field $field): void

Examples

$object = newInputType('Animal');
$object->addField(newField('name', newStringType()));
$object->addField(newField('age', newIntegerType()));
$object->addField(newField('weight', newIntegerType()));

Result:

inputAnimal {
name: Stringage: Intweight: Int
}

Fields

A selection set is primarily composed of fields. A field describes one discrete piece of information available to request within a selection set.

GrapQL Spec

Definition

Field(string $name, Type $type, ?TypeModifier $typeModifier, ?string $description)

Examples

$field = newField('simpleField', newIntegerType());

Result:

simpleField: Int

With type modifier:

$field = newField('simpleField', newIntegerType(), newTypeModifier($nullable = false));

Result:

simpleField: Int!

With type argument:

$field = newField('booleanListArgField', newBooleanType(), newTypeModifier(true, true));
$argument = newArgument('booleanListArg', newBooleanType(), newTypeModifier(true, true, false));
$field->addArgument($argument);

Arguments

Fields are conceptually functions which return values, and occasionally accept arguments which alter their behavior. These arguments often map directly to function arguments within a GraphQL server’s implementation.

GrapQL Spec

Definition

Argument(string $name, Type $type, ?TypeModifier $typeModifier, ?Value $defaultVale)

Examples

$argument = newArgument('booleanArg', newBooleanType());

Result:

booleanArg: Boolean

With type modifier:

$argument = newArgument('intArg', newIntegerType(), newTypeModifier(false));
// intArg: Int! = 0

With type default value:

$argument = newArgument('intArg', newIntegerType(), null, newValueInteger(0));
// intArg: Int = 0

Argument values

Set simple scalar values for default values in arguments.

Definition

Value(mixed $value)

Available values:ValueBoolean, ValueFloat, ValueInteger, ValueNull, ValueString

Examples

$bool = newValueBoolean(true);
$bool->getValue(); // trueecho$bool; // 'true'

Development

Download and build docker container

$ make

Access docker image

$ make bash