webonyx/graphql-php
PHP implementation of the GraphQL specification, based on graphql-js. Build schemas, types, and execute queries/mutations in your PHP apps. Widely used, well-tested, and documented with examples and class reference.
This is the primary facade for fulfilling GraphQL operations. See related documentation.
[@phpstan-import-type](https://github.com/phpstan-import-type) ArgsMapper from Executor
[@phpstan-import-type](https://github.com/phpstan-import-type) FieldResolver from Executor
@see \GraphQL\Tests\GraphQLTest
/**
* Executes graphql query.
*
* More sophisticated GraphQL servers, such as those which persist queries,
* may wish to separate the validation and execution phases to a static time
* tooling step, and a server runtime step.
*
* Available options:
*
* schema:
* The GraphQL type system to use when validating and executing a query.
* source:
* A GraphQL language formatted string representing the requested operation.
* rootValue:
* The value provided as the first argument to resolver functions on the top
* level type (e.g. the query object type).
* contextValue:
* The context value is provided as an argument to resolver functions after
* field arguments. It is used to pass shared information useful at any point
* during executing this query, for example the currently logged in user and
* connections to databases or other services.
* If the passed object implements the `ScopedContext` interface,
* its `clone()` method will be called before passing the context down to a field.
* This allows passing information to child fields in the query tree without affecting sibling or parent fields.
* variableValues:
* A mapping of variable name to runtime value to use for all variables
* defined in the requestString.
* operationName:
* The name of the operation to use if requestString contains multiple
* possible operations. Can be omitted if requestString contains only
* one operation.
* fieldResolver:
* A resolver function to use when one is not provided by the schema.
* If not provided, the default field resolver is used (which looks for a
* value on the source value with the field's name).
* validationRules:
* A set of rules for query validation step. Default value is all available rules.
* Empty array would allow to skip query validation (may be convenient for persisted
* queries which are validated before persisting and assumed valid during execution)
*
* [@param](https://github.com/param) string|DocumentNode $source
* [@param](https://github.com/param) mixed $rootValue
* [@param](https://github.com/param) mixed $contextValue
* [@param](https://github.com/param) array<string, mixed>|null $variableValues
* [@param](https://github.com/param) array<ValidationRule>|null $validationRules
*
* [@api](https://github.com/api)
*
* [@throws](https://github.com/throws) \Exception
* [@throws](https://github.com/throws) InvariantViolation
*/
static function executeQuery(
GraphQL\Type\Schema $schema,
$source,
$rootValue = null,
$contextValue = null,
?array $variableValues = null,
?string $operationName = null,
?callable $fieldResolver = null,
?array $validationRules = null
): GraphQL\Executor\ExecutionResult
/**
* Same as executeQuery(), but requires PromiseAdapter and always returns a Promise.
* Useful for Async PHP platforms.
*
* [@param](https://github.com/param) string|DocumentNode $source
* [@param](https://github.com/param) mixed $rootValue
* [@param](https://github.com/param) mixed $context
* [@param](https://github.com/param) array<string, mixed>|null $variableValues
* [@param](https://github.com/param) array<ValidationRule>|null $validationRules Defaults to using all available rules
*
* [@api](https://github.com/api)
*
* [@throws](https://github.com/throws) \Exception
*/
static function promiseToExecute(
GraphQL\Executor\Promise\PromiseAdapter $promiseAdapter,
GraphQL\Type\Schema $schema,
$source,
$rootValue = null,
$context = null,
?array $variableValues = null,
?string $operationName = null,
?callable $fieldResolver = null,
?array $validationRules = null
): GraphQL\Executor\Promise\Promise
/**
* Returns directives defined in GraphQL spec.
*
* [@deprecated](https://github.com/deprecated) use {[@see](https://github.com/see) Directive::builtInDirectives()}
*
* [@throws](https://github.com/throws) InvariantViolation
*
* [@return](https://github.com/return) array<string, Directive>
*
* [@api](https://github.com/api)
*/
static function getStandardDirectives(): array
/**
* Returns built-in scalar types defined in GraphQL spec.
*
* [@deprecated](https://github.com/deprecated) use {[@see](https://github.com/see) Type::builtInScalars()}
*
* [@throws](https://github.com/throws) InvariantViolation
*
* [@return](https://github.com/return) array<string, ScalarType>
*
* [@api](https://github.com/api)
*/
static function getStandardTypes(): array
/**
* Replaces standard types with types from this list (matching by name).
*
* Standard types not listed here remain untouched.
*
* [@deprecated](https://github.com/deprecated) prefer per-schema scalar overrides via {[@see](https://github.com/see) \GraphQL\Type\SchemaConfig::$types} or {[@see](https://github.com/see) \GraphQL\Type\SchemaConfig::$typeLoader}
*
* [@param](https://github.com/param) array<string, ScalarType> $types
*
* [@api](https://github.com/api)
*
* [@throws](https://github.com/throws) InvariantViolation
*/
static function overrideStandardTypes(array $types): void
/**
* Returns standard validation rules implementing GraphQL spec.
*
* [@return](https://github.com/return) array<class-string<ValidationRule>, ValidationRule>
*
* [@api](https://github.com/api)
*/
static function getStandardValidationRules(): array
/**
* Set default resolver implementation.
*
* [@phpstan-param](https://github.com/phpstan-param) FieldResolver $fn
*
* [@api](https://github.com/api)
*/
static function setDefaultFieldResolver(callable $fn): void
/**
* Set default args mapper implementation.
*
* [@phpstan-param](https://github.com/phpstan-param) ArgsMapper $fn
*
* [@api](https://github.com/api)
*/
static function setDefaultArgsMapper(callable $fn): void
Registry of built-in GraphQL types and base class for all other types.
const INT = 'Int';
const FLOAT = 'Float';
const STRING = 'String';
const BOOLEAN = 'Boolean';
const ID = 'ID';
const BUILT_IN_SCALAR_NAMES = [
'Int',
'Float',
'String',
'Boolean',
'ID',
];
const STANDARD_TYPE_NAMES = [
'Int',
'Float',
'String',
'Boolean',
'ID',
];
const BUILT_IN_TYPE_NAMES = [
'Int',
'Float',
'String',
'Boolean',
'ID',
'__Schema',
'__Type',
'__Directive',
'__Field',
'__InputValue',
'__EnumValue',
'__TypeKind',
'__DirectiveLocation',
];
/**
* Returns the built-in Int scalar type.
*
* [@api](https://github.com/api)
*/
static function int(): GraphQL\Type\Definition\ScalarType
/**
* Returns the built-in Float scalar type.
*
* [@api](https://github.com/api)
*/
static function float(): GraphQL\Type\Definition\ScalarType
/**
* Returns the built-in String scalar type.
*
* [@api](https://github.com/api)
*/
static function string(): GraphQL\Type\Definition\ScalarType
/**
* Returns the built-in Boolean scalar type.
*
* [@api](https://github.com/api)
*/
static function boolean(): GraphQL\Type\Definition\ScalarType
/**
* Returns the built-in ID scalar type.
*
* [@api](https://github.com/api)
*/
static function id(): GraphQL\Type\Definition\ScalarType
/**
* Wraps the given type in a list type.
*
* [@template](https://github.com/template) T of Type
*
* [@param](https://github.com/param) T|callable():T $type
*
* [@return](https://github.com/return) ListOfType<T>
*
* [@api](https://github.com/api)
*/
static function listOf($type): GraphQL\Type\Definition\ListOfType
/**
* Wraps the given type in a non-null type.
*
* [@param](https://github.com/param) NonNull|(NullableType&Type)|callable():(NullableType&Type) $type
*
* [@api](https://github.com/api)
*/
static function nonNull($type): GraphQL\Type\Definition\NonNull
/**
* Returns all built-in types: built-in scalars and introspection types.
*
* [@api](https://github.com/api)
*
* [@return](https://github.com/return) array<string, Type&NamedType>
*/
static function builtInTypes(): array
/**
* Returns all built-in scalar types.
*
* [@api](https://github.com/api)
*
* [@return](https://github.com/return) array<string, ScalarType>
*/
static function builtInScalars(): array
/**
* Determines if the given type is a built-in scalar (Int, Float, String, Boolean, ID).
*
* Does not unwrap NonNull/List wrappers — checks the type instance directly.
* ScalarType is a NamedType, so {[@see](https://github.com/see) Type::getNamedType()} is unnecessary.
*
* [@param](https://github.com/param) mixed $type
*
* [@phpstan-assert-if-true](https://github.com/phpstan-assert-if-true) ScalarType $type
*
* [@api](https://github.com/api)
*/
static function isBuiltInScalar($type): bool
/**
* Determines if the given type is an input type.
*
* [@param](https://github.com/param) mixed $type
*
* [@api](https://github.com/api)
*/
static function isInputType($type): bool
/**
* Returns the underlying named type of the given type.
*
* [@return](https://github.com/return) (Type&NamedType)|null
*
* [@phpstan-return](https://github.com/phpstan-return) ($type is null ? null : Type&NamedType)
*
* [@api](https://github.com/api)
*/
static function getNamedType(?GraphQL\Type\Definition\Type $type): ?GraphQL\Type\Definition\Type
/**
* Determines if the given type is an output type.
*
* [@param](https://github.com/param) mixed $type
*
* [@api](https://github.com/api)
*/
static function isOutputType($type): bool
/**
* Determines if the given type is a leaf type.
*
* [@param](https://github.com/param) mixed $type
*
* [@api](https://github.com/api)
*/
static function isLeafType($type): bool
/**
* Determines if the given type is a composite type.
*
* [@param](https://github.com/param) mixed $type
*
* [@api](https://github.com/api)
*/
static function isCompositeType($type): bool
/**
* Determines if the given type is an abstract type.
*
* [@param](https://github.com/param) mixed $type
*
* [@api](https://github.com/api)
*/
static function isAbstractType($type): bool
/**
* Unwraps a potentially non-null type to return the underlying nullable type.
*
* [@return](https://github.com/return) Type&NullableType
*
* [@api](https://github.com/api)
*/
static function getNullableType(GraphQL\Type\Definition\Type $type): GraphQL\Type\Definition\Type
Structure containing information useful for field resolution process.
Passed as 4th argument to every field resolver. See docs on field resolving (data fetching).
[@phpstan-import-type](https://github.com/phpstan-import-type) QueryPlanOptions from QueryPlan
[@phpstan-type](https://github.com/phpstan-type) Path list<string|int>
/**
* The definition of the field being resolved.
*
* [@api](https://github.com/api)
*/
public $fieldDefinition;
/**
* The name of the field being resolved.
*
* [@api](https://github.com/api)
*/
public $fieldName;
/**
* Expected return type of the field being resolved.
*
* [@api](https://github.com/api)
*/
public $returnType;
/**
* AST of all nodes referencing this field in the query.
*
* [@api](https://github.com/api)
*
* [@var](https://github.com/var) \ArrayObject<int, FieldNode>
*/
public $fieldNodes;
/**
* Parent type of the field being resolved.
*
* [@api](https://github.com/api)
*/
public $parentType;
/**
* Path to this field from the very root value. When fields are aliased, the path includes aliases.
*
* [@api](https://github.com/api)
*
* [@var](https://github.com/var) list<string|int>
*
* [@phpstan-var](https://github.com/phpstan-var) Path
*/
public $path;
/**
* Path to this field from the very root value. This will never include aliases.
*
* [@api](https://github.com/api)
*
* [@var](https://github.com/var) list<string|int>
*
* [@phpstan-var](https://github.com/phpstan-var) Path
*/
public $unaliasedPath;
/**
* Instance of a schema used for execution.
*
* [@api](https://github.com/api)
*/
public $schema;
/**
* AST of all fragments defined in query.
*
* [@api](https://github.com/api)
*
* [@var](https://github.com/var) array<string, FragmentDefinitionNode>
*/
public $fragments;
/**
* Root value passed to query execution.
*
* [@api](https://github.com/api)
*
* [@var](https://github.com/var) mixed
*/
public $rootValue;
/**
* AST of operation definition node (query, mutation).
*
* [@api](https://github.com/api)
*/
public $operation;
/**
* Array of variables passed to query execution.
*
* [@api](https://github.com/api)
*
* [@var](https://github.com/var) array<string, mixed>
*/
public $variableValues;
/**
* Returns names of all fields selected in query for `$this->fieldName` up to `$depth` levels.
*
* Example:
* {
* root {
* id
* nested {
* nested1
* nested2 {
* nested3
* }
* }
* }
* }
*
* Given this ResolveInfo instance is a part of root field resolution, and $depth === 1,
* this method will return:
* [
* 'id' => true,
* 'nested' => [
* 'nested1' => true,
* 'nested2' => true,
* ],
* ]
*
* This method does not consider conditional typed fragments.
* Use it with care for fields of interface and union types.
*
* [@param](https://github.com/param) int $depth How many levels to include in the output beyond the first
*
* [@return](https://github.com/return) array<string, mixed>
*
* [@api](https://github.com/api)
*/
function getFieldSelection(int $depth = 0): array
/**
* Returns names and args of all fields selected in query for `$this->fieldName` up to `$depth` levels, including aliases.
*
* The result maps original field names to a map of selections for that field, including aliases.
* For each of those selections, you can find the following keys:
* - "args" contains the passed arguments for this field/alias (not on an union inline fragment)
* - "type" contains the related Type instance found (will be the same for all aliases of a field)
* - "selectionSet" contains potential nested fields of this field/alias (only on ObjectType). The structure is recursive from here.
* - "unions" contains potential object types contained in an UnionType (only on UnionType). The structure is recursive from here and will go through the selectionSet of the object types.
*
* Example:
* {
* root {
* id
* nested {
* nested1(myArg: 1)
* nested1Bis: nested1
* }
* alias1: nested {
* nested1(myArg: 2, mySecondAg: "test")
* }
* myUnion(myArg: 3) {
* ...on Nested {
* nested1(myArg: 4)
* }
* ...on MyCustomObject {
* nested3
* }
* }
* }
* }
*
* Given this ResolveInfo instance is a part of root field resolution,
* $depth === 1,
* and fields "nested" represents an ObjectType named "Nested",
* this method will return:
* [
* 'id' => [
* 'id' => [
* 'args' => [],
* 'type' => GraphQL\Type\Definition\IntType Object ( ... )),
* ],
* ],
* 'nested' => [
* 'nested' => [
* 'args' => [],
* 'type' => GraphQL\Type\Definition\ObjectType Object ( ... )),
* 'selectionSet' => [
* 'nested1' => [
* 'nested1' => [
* 'args' => [
* 'myArg' => 1,
* ],
* 'type' => GraphQL\Type\Definition\StringType Object ( ... )),
* ],
* 'nested1Bis' => [
* 'args' => [],
* 'type' => GraphQL\Type\Definition\StringType Object ( ... )),
* ],
* ],
* ],
* ],
* ],
* 'alias1' => [
* 'alias1' => [
* 'args' => [],
* 'type' => GraphQL\Type\Definition\ObjectType Object ( ... )),
* 'selectionSet' => [
* 'nested1' => [
* 'nested1' => [
* 'args' => [
* 'myArg' => 2,
* 'mySecondAg' => "test",
* ],
* 'type' => GraphQL\Type\Definition\StringType Object ( ... )),
* ],
* ],
* ],
* ],
* ],
* 'myUnion' => [
* 'myUnion' => [
* 'args' => [
* 'myArg' => 3,
* ],
* 'type' => GraphQL\Type\Definition\UnionType Object ( ... )),
* 'unions' => [
* 'Nested' => [
* 'type' => GraphQL\Type\Definition\ObjectType Object ( ... )),
* 'selectionSet' => [
* 'nested1' => [
* 'nested1' => [
* 'args' => [
* 'myArg' => 4,
* ],
* 'type' => GraphQL\Type\Definition\StringType Object ( ... )),
* ],
* ],
* ],
* ],
* 'MyCustomObject' => [
* 'type' => GraphQL\Tests\Type\TestClasses\MyCustomType Object ( ... )),
* 'selectionSet' => [
* 'nested3' => [
* 'nested3' => [
* 'args' => [],
* 'type' => GraphQL\Type\Definition\StringType Object ( ... )),
* ],
* ],
* ],
* ],
* ],
* ],
* ],
* ]
*
* [@param](https://github.com/param) int $depth How many levels to include in the output beyond the first
*
* [@throws](https://github.com/throws) \Exception
* [@throws](https://github.com/throws) Error
* [@throws](https://github.com/throws) InvariantViolation
*
* [@return](https://github.com/return) array<string, mixed>
*
* [@api](https://github.com/api)
*/
function getFieldSelectionWithAliases(int $depth = 0): array
Enumeration of available directive locations.
const QUERY = 'QUERY';
const MUTATION = 'MUTATION';
const SUBSCRIPTION = 'SUBSCRIPTION';
const FIELD = 'FIELD';
const FRAGMENT_DEFINITION = 'FRAGMENT_DEFINITION';
const FRAGMENT_SPREAD = 'FRAGMENT_SPREAD';
const INLINE_FRAGMENT = 'INLINE_FRAGMENT';
const VARIABLE_DEFINITION = 'VARIABLE_DEFINITION';
const EXECUTABLE_LOCATIONS = [
'QUERY' => 'QUERY',
'MUTATION' => 'MUTATION',
'SUBSCRIPTION' => 'SUBSCRIPTION',
'FIELD' => 'FIELD',
'FRAGMENT_DEFINITION' => 'FRAGMENT_DEFINITION',
'FRAGMENT_SPREAD' => 'FRAGMENT_SPREAD',
'INLINE_FRAGMENT' => 'INLINE_FRAGMENT',
'VARIABLE_DEFINITION' => 'VARIABLE_DEFINITION',
];
const SCHEMA = 'SCHEMA';
const SCALAR = 'SCALAR';
const OBJECT = 'OBJECT';
const FIELD_DEFINITION = 'FIELD_DEFINITION';
const ARGUMENT_DEFINITION = 'ARGUMENT_DEFINITION';
const IFACE = 'INTERFACE';
const UNION = 'UNION';
const ENUM = 'ENUM';
const ENUM_VALUE = 'ENUM_VALUE';
const INPUT_OBJECT = 'INPUT_OBJECT';
const INPUT_FIELD_DEFINITION = 'INPUT_FIELD_DEFINITION';
const TYPE_SYSTEM_LOCATIONS = [
'SCHEMA' => 'SCHEMA',
'SCALAR' => 'SCALAR',
'OBJECT' => 'OBJECT',
'FIELD_DEFINITION' => 'FIELD_DEFINITION',
'ARGUMENT_DEFINITION' => 'ARGUMENT_DEFINITION',
'INTERFACE' => 'INTERFACE',
'UNION' => 'UNION',
'ENUM' => 'ENUM',
'ENUM_VALUE' => 'ENUM_VALUE',
'INPUT_OBJECT' => 'INPUT_OBJECT',
'INPUT_FIELD_DEFINITION' => 'INPUT_FIELD_DEFINITION',
];
const LOCATIONS = [
'QUERY' => 'QUERY',
'MUTATION' => 'MUTATION',
'SUBSCRIPTION' => 'SUBSCRIPTION',
'FIELD' => 'FIELD',
'FRAGMENT_DEFINITION' => 'FRAGMENT_DEFINITION',
'FRAGMENT_SPREAD' => 'FRAGMENT_SPREAD',
'INLINE_FRAGMENT' => 'INLINE_FRAGMENT',
'VARIABLE_DEFINITION' => 'VARIABLE_DEFINITION',
'SCHEMA' => 'SCHEMA',
'SCALAR' => 'SCALAR',
'OBJECT' => 'OBJECT',
'FIELD_DEFINITION' => 'FIELD_DEFINITION',
'ARGUMENT_DEFINITION' => 'ARGUMENT_DEFINITION',
'INTERFACE' => 'INTERFACE',
'UNION' => 'UNION',
'ENUM' => 'ENUM',
'ENUM_VALUE' => 'ENUM_VALUE',
'INPUT_OBJECT' => 'INPUT_OBJECT',
'INPUT_FIELD_DEFINITION' => 'INPUT_FIELD_DEFINITION',
];
Configuration options for schema construction.
The options accepted by the create method are described in the schema definition docs.
Usage example:
$config = SchemaConfig::create()
->setQuery($myQueryType)
->setTypeLoader($myTypeLoader);
$schema = new Schema($config);
@see Type, NamedType
[@phpstan-type](https://github.com/phpstan-type) MaybeLazyObjectType ObjectType|(callable(): (ObjectType|null))|null
[@phpstan-type](https://github.com/phpstan-type) TypeLoader callable(string $typeName): ((Type&NamedType)|null)
[@phpstan-type](https://github.com/phpstan-type) Types iterable<Type&NamedType>|(callable(): iterable<Type&NamedType>)|iterable<(callable(): Type&NamedType)>|(callable(): iterable<(callable(): Type&NamedType)>)
[@phpstan-type](https://github.com/phpstan-type) SchemaConfigOptions array{
description?: string|null,
query?: MaybeLazyObjectType,
mutation?: MaybeLazyObjectType,
subscription?: MaybeLazyObjectType,
types?: Types|null,
directives?: array<Directive>|null,
typeLoader?: TypeLoader|null,
assumeValid?: bool|null,
astNode?: SchemaDefinitionNode|null,
extensionASTNodes?: array<SchemaExtensionNode>|null,
}
/**
* Converts an array of options to instance of SchemaConfig
* (or just returns empty config when array is not passed).
*
* [@phpstan-param](https://github.com/phpstan-param) SchemaConfigOptions $options
*
* [@throws](https://github.com/throws) InvariantViolation
*
* [@api](https://github.com/api)
*/
static function create(array $options = []): self
/**
* [@return](https://github.com/return) MaybeLazyObjectType
*
* [@api](https://github.com/api)
*/
function getQuery()
/**
* [@param](https://github.com/param) MaybeLazyObjectType $query
*
* [@throws](https://github.com/throws) InvariantViolation
*
* [@api](https://github.com/api)
*/
function setQuery($query): self
/**
* [@return](https://github.com/return) MaybeLazyObjectType
*
* [@api](https://github.com/api)
*/
function getMutation()
/**
* [@param](https://github.com/param) MaybeLazyObjectType $mutation
*
* [@throws](https://github.com/throws) InvariantViolation
*
* [@api](https://github.com/api)
*/
function setMutation($mutation): self
/**
* [@return](https://github.com/return) MaybeLazyObjectType
*
* [@api](https://github.com/api)
*/
function getSubscription()
/**
* [@param](https://github.com/param) MaybeLazyObjectType $subscription
*
* [@throws](https://github.com/throws) InvariantViolation
*
* [@api](https://github.com/api)
*/
function setSubscription($subscription): self
/**
* [@return](https://github.com/return) array|callable
*
* [@phpstan-return](https://github.com/phpstan-return) Types
*
* [@api](https://github.com/api)
*/
function getTypes()
/**
* [@param](https://github.com/param) array|callable $types
*
* [@phpstan-param](https://github.com/phpstan-param) Types $types
*
* [@api](https://github.com/api)
*/
function setTypes($types): self
/**
* [@return](https://github.com/return) array<Directive>|null
*
* [@api](https://github.com/api)
*/
function getDirectives(): ?array
/**
* [@param](https://github.com/param) array<Directive>|null $directives
*
* [@api](https://github.com/api)
*/
function setDirectives(?array $directives): self
/**
* [@return](https://github.com/return) callable|null $typeLoader
*
* [@phpstan-return](https://github.com/phpstan-return) TypeLoader|null $typeLoader
*
* [@api](https://github.com/api)
*/
function getTypeLoader(): ?callable
/**
* [@phpstan-param](https://github.com/phpstan-param) TypeLoader|null $typeLoader
*
* [@api](https://github.com/api)
*/
function setTypeLoader(?callable $typeLoader): self
Schema Definition (see schema definition docs).
A Schema is created by supplying the root types of each type of operation: query, mutation (optional) and subscription (optional). A schema definition is then supplied to the validator and executor. Usage Example:
$schema = new GraphQL\Type\Schema([
'query' => $MyAppQueryRootType,
'mutation' => $MyAppMutationRootType,
]);
Or using Schema Config instance:
$config = GraphQL\Type\SchemaConfig::create()
->setQuery($MyAppQueryRo...
How can I help you explore Laravel packages today?