graphql-php/docs/reference.md

Intro

Stable library API. Not all class methods are covered here, only those which are considered stable. Backwards compatibility of these methods is preserved whenever possible.

GraphQL\GraphQL

Facade class (related docs) with following public interface:

namespace GraphQL;

class GraphQL 
{
    /**
     * @return GraphQL\Executor\ExecutionResult
     */
    public static function executeQuery(
        GraphQL\Type\Schema $schema,
        $source,
        $rootValue = null,
        $contextValue = null,
        $variableValues = null,
        $operationName = null,
        callable $fieldResolver = null,
        array $validationRules = null,
        GraphQL\Executor\Promise\PromiseAdapter $promiseAdapter = null
    );
    
    /**
     * Returns directives defined in GraphQL spec
     * 
     * @return Directive[]
     */
    public static function getInternalDirectives();

    /**
     * Returns types defined in GraphQL spec
     * 
     * @return Type[]
     */
    public static function getInternalTypes();
}

GraphQL\Type\Definition\Type

Returns internal GraphQL types (related docs):

namespace GraphQL\Type\Definition;

class Type
{
    /**
     * @return IDType
     */
    public static function id();

    /**
     * @return StringType
     */
    public static function string();

    /**
     * @return BooleanType
     */
    public static function boolean();

    /**
     * @return IntType
     */
    public static function int();

    /**
     * @return FloatType
     */
    public static function float();

    /**
     * @param Type $wrappedType
     * @return ListOfType
     */
    public static function listOf($wrappedType);

    /**
     * @param Type $wrappedType
     * @return NonNull
     */
    public static function nonNull($wrappedType);

    /**
     * @return Type[]
     */
    public static function getInternalTypes();

GraphQL\Type\Definition\*

• GraphQL\Type\Definition\ObjectType
• GraphQL\Type\Definition\ScalarType
• GraphQL\Type\Definition\CustomScalarType
• GraphQL\Type\Definition\EnumType
• GraphQL\Type\Definition\ListType
• GraphQL\Type\Definition\NonNull
• GraphQL\Type\Definition\InterfaceType
• GraphQL\Type\Definition\UnionType
• GraphQL\Type\Definition\InputObjectType
• GraphQL\Type\Definition\Directive

GraphQL\Type\SchemaConfig

Instance accepted by Schema constructor.

namespace GraphQL\Type;

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

class SchemaConfig
{
    /**
     * Converts array of options to instance of SchemaConfig
     *
     * @param array $options
     * @return SchemaConfig
     */
    public static function create(array $options = []);

    /**
     * @return $this
     */
    public function setQuery(ObjectType $query);

    /**
     * @return $this
     */
    public function setMutation(ObjectType $mutation);
    
    /**
     * @return $this
     */
    public function setSubscription(ObjectType $subscription);
    
    /**
     * Pass additional schema types (or callable returning these types)
     * 
     * @param Type[]|callable $types
     * @return $this
     */
    public function setTypes($types);

    /**
     * @param Directive[] $directives
     * @return $this
     */
    public function setDirectives(array $directives);

    /**
     * @return $this
     */
    public function setTypeLoader(callable $typeLoader);

    /**
     * @return ObjectType
     */
    public function getQuery();

    /**
     * @return ObjectType
     */
    public function getMutation();

    /**
     * @return ObjectType
     */
    public function getSubscription();

    /**
     * @return Type[]
     */
    public function getTypes();

    /**
     * @return Directive[]
     */
    public function getDirectives();

    /**
     * @return callable
     */
    public function getTypeLoader();
}

GraphQL\Type\Schema

See related docs.

namespace GraphQL\Type;

class Schema
{
    /**
     * Schema constructor.
     *
     * @param array|SchemaConfig $config
     */
    public function __construct($config);

    /**
     * @return SchemaConfig
     */
    public function getConfig();

    /**
     * Returns schema query type
     *
     * @return ObjectType
     */
    public function getQueryType();

    /**
     * Returns schema mutation type
     *
     * @return ObjectType|null
     */
    public function getMutationType();

    /**
     * Returns schema subscription
     *
     * @return ObjectType|null
     */
    public function getSubscriptionType();
    
    /**
     * Returns a list of directives supported by this schema
     *
     * @return Directive[]
     */
    public function getDirectives();

    /**
     * Returns instance of directive by name
     *
     * @return Directive
     */
    public function getDirective($name);

    /**
     * Returns true if object type is concrete type of given abstract type
     * (implementation for interfaces and members of union type for unions)
     *
     * @return bool
     */
    public function isPossibleType(AbstractType $abstractType, ObjectType $possibleType);

    /**
     * Returns type by it's name
     *
     * @return Type
     */
    public function getType($name);
    
    /**
     * Returns array of all types in this schema. Keys of this array represent type names, 
     * values are instances of corresponding type definitions
     *
     * This operation requires full schema scan. Do not use in production environment.
     *
     * @return Type[]
     */
    public function getTypeMap();

    /**
     * Returns all possible concrete types for given abstract type
     * (implementations for interfaces and members of union type for unions)
     *
     * This operation requires full schema scan. Do not use in production environment.
     *
     * @return ObjectType[]
     */
    public function getPossibleTypes(AbstractType $abstractType);

    /**
     * Validates schema.
     *
     * This operation requires full schema scan. Do not use in production environment.
     *
     * @throws InvariantViolation
     */
    public function assertValid();
}

GraphQL\Language\Parser

Parses query string to AST

class Parser
{
    /**
     * Available options:
     *
     * noLocation: boolean,
     * (By default, the parser creates AST nodes that know the location
     * in the source that they correspond to. This configuration flag
     * disables that behavior for performance or testing.)
     *
     * @return DocumentNode
     */
    public static function parse($source, array $options = []);

    /**
     * Given a string containing a GraphQL value (ex. `[42]`), parse the AST for
     * that value.
     * Throws GraphQL\Error\SyntaxError if a syntax error is encountered.
     *
     * This is useful within tools that operate upon GraphQL Values directly and
     * in isolation of complete GraphQL documents.
     *
     * Consider providing the results to the utility function: GraphQL\Utils\AST::valueFromAST().
     *
     * @return BooleanValueNode|EnumValueNode|FloatValueNode|IntValueNode|ListValueNode|ObjectValueNode|StringValueNode|VariableNode
     */
    public static function parseValue($source, array $options = []);

    /**
     * Given a string containing a GraphQL Type (ex. `[Int!]`), parse the AST for
     * that type.
     * Throws GraphQL\Error\SyntaxError if a syntax error is encountered.
     *
     * This is useful within tools that operate upon GraphQL Types directly and
     * in isolation of complete GraphQL documents.
     *
     * Consider providing the results to the utility function: GraphQL\Utils\AST::typeFromAST().
     *
     * @return ListTypeNode|NameNode|NonNullTypeNode
     */
    public static function parseType($source, array $options = []);
}

GraphQL\Language\Printer

Prints AST to string.

namespace GraphQL\Language;

class Printer
{
    /**
     * Prints AST to string. Capable of printing GraphQL queries and Type definition language.
     *
     * @param GraphQL\Language\AST\Node $ast
     * @return string
     */
    public static function doPrint($ast);
}

GraphQL\Language\Visitor

namespace GraphQL\Language;

class Visitor 
{
    /**
     * visit() will walk through an AST using a depth first traversal, calling
     * the visitor's enter function at each node in the traversal, and calling the
     * leave function after visiting that node and all of it's child nodes.
     *
     * By returning different values from the enter and leave functions, the
     * behavior of the visitor can be altered, including skipping over a sub-tree of
     * the AST (by returning false), editing the AST by returning a value or null
     * to remove the value, or to stop the whole traversal by returning BREAK.
     *
     * When using visit() to edit an AST, the original AST will not be modified, and
     * a new version of the AST with the changes applied will be returned from the
     * visit function.
     *
     *     $editedAST = Visitor::visit($ast, [
     *       'enter' => function ($node, $key, $parent, $path, $ancestors) {
     *         // return
     *         //   null: no action
     *         //   Visitor::skipNode(): skip visiting this node
     *         //   Visitor::stop(): stop visiting altogether
     *         //   Visitor::removeNode(): delete this node
     *         //   any value: replace this node with the returned value
     *       },
     *       'leave' => function ($node, $key, $parent, $path, $ancestors) {
     *         // return
     *         //   null: no action
     *         //   Visitor::stop(): stop visiting altogether
     *         //   Visitor::removeNode(): delete this node
     *         //   any value: replace this node with the returned value
     *       }
     *     ]);
     *
     * Alternatively to providing enter() and leave() functions, a visitor can
     * instead provide functions named the same as the kinds of AST nodes, or
     * enter/leave visitors at a named key, leading to four permutations of
     * visitor API:
     *
     * 1) Named visitors triggered when entering a node a specific kind.
     *
     *     Visitor::visit($ast, [
     *       'Kind' => function ($node) {
     *         // enter the "Kind" node
     *       }
     *     ]);
     *
     * 2) Named visitors that trigger upon entering and leaving a node of
     *    a specific kind.
     *
     *     Visitor::visit($ast, [
     *       'Kind' => [
     *         'enter' => function ($node) {
     *           // enter the "Kind" node
     *         }
     *         'leave' => function ($node) {
     *           // leave the "Kind" node
     *         }
     *       ]
     *     ]);
     *
     * 3) Generic visitors that trigger upon entering and leaving any node.
     *
     *     Visitor::visit($ast, [
     *       'enter' => function ($node) {
     *         // enter any node
     *       },
     *       'leave' => function ($node) {
     *         // leave any node
     *       }
     *     ]);
     *
     * 4) Parallel visitors for entering and leaving nodes of a specific kind.
     *
     *     Visitor::visit($ast, [
     *       'enter' => [
     *         'Kind' => function($node) {
     *           // enter the "Kind" node
     *         }
     *       },
     *       'leave' => [
     *         'Kind' => function ($node) {
     *           // leave the "Kind" node
     *         }
     *       ]
     *     ]);
     *
     * @param Node $root
     * @param array $visitor
     * @param array $keyMap
     * @return Node|mixed
     * @throws \Exception
     */
    public static function visit($root, $visitor, $keyMap = null);
    
    /**
     * Returns marker for visitor break
     *
     * @return VisitorOperation
     */
    public static function stop();

    /**
     * Returns marker for skipping current node
     *
     * @return VisitorOperation
     */
    public static function skipNode();

    /**
     * Returns marker for removing a node
     *
     * @return VisitorOperation
     */
    public static function removeNode();
}

GraphQL\Language\AST\*

Simple structural classes representing AST Nodes. Check out source code.

GraphQL\Executor\Executor

Implements execution phase of whole query execution process.

namespace GraphQL\Executor;

use GraphQL\Executor\Promise\Promise;
use GraphQL\Executor\Promise\PromiseAdapter;

class Executor
{
    /**
     * Executes DocumentNode against given schema.
     * 
     * When $promiseAdapter is passed returns Promise instance produced by this adapter. 
     * By default simply returns ExecutionResult
     * 
     * @return ExecutionResult|Promise
     */
    public static function execute(
        Schema $schema,
        DocumentNode $ast,
        $rootValue = null,
        $contextValue = null,
        $variableValues = null,
        $operationName = null,
        callable $fieldResolver = null,
        PromiseAdapter $promiseAdapter = null
    );
}

GraphQL\Executor\ExecutionResult

Result of query execution process.

namespace GraphQL\Executor;

class ExecutionResult implements \JsonSerializable
{
    /**
     * @var array
     */
    public $data;

    /**
     * @var Error[]
     */
    public $errors;
    
    /**
     * @var array[]
     */
    public $extensions;

    /**
     * Define custom error formatting (must conform to http://facebook.github.io/graphql/#sec-Errors)
     *
     * Expected signature is: function (GraphQL\Error\Error $error): array
     *
     * Default formatter is "GraphQL\Error\FormattedError::createFromException"
     *
     * Expected returned value must be an array:
     * array(
     *    'message' => 'errorMessage',
     *    // ... other keys
     * );
     *
     * @param callable $errorFormatter
     * @return $this
     */
    public function setErrorFormatter(callable $errorFormatter);

    /**
     * Define custom logic for error handling (filtering, logging, etc).
     *
     * Expected handler signature is: function (array $errors, callable $formatter): array
     *
     * Default handler is:
     * function (array $errors, callable $formatter) {
     *     return array_map($formatter, $errors);
     * }
     *
     * @param callable $handler
     * @return $this
     */
    public function setErrorsHandler(callable $handler);

    /**
     * Converts GraphQL result to array using provided errors handler and formatter.
     *
     * Default error formatter is GraphQL\Error\FormattedError::createFromException
     * Default error handler will simply return all errors formatted. No errors are filtered.
     *
     * @param bool|int $debug
     * @return array
     */
    public function toArray($debug = false);

    /**
     * Part of \JsonSerializable interface
     *
     * @return array
     */
    public function jsonSerialize()
    {
        return $this->toArray();
    }

GraphQL\Type\Definition\ResolveInfo

namespace GraphQL\Type\Definition;

use GraphQL\Language\AST\FieldNode;
use GraphQL\Language\AST\FragmentDefinitionNode;
use GraphQL\Language\AST\FragmentSpreadNode;
use GraphQL\Language\AST\InlineFragmentNode;
use GraphQL\Language\AST\OperationDefinitionNode;
use GraphQL\Language\AST\SelectionSetNode;
use GraphQL\Type\Schema;

class ResolveInfo
{
    /**
     * @var string
     */
    public $fieldName;

    /**
     * @var FieldNode[]
     */
    public $fieldNodes;

    /**
     * @var ScalarType|ObjectType|InterfaceType|UnionType|EnumType|ListOfType|NonNull
     */
    public $returnType;

    /**
     * @var ObjectType|InterfaceType|UnionType
     */
    public $parentType;

    /**
     * @var array
     */
    public $path;

    /**
     * @var Schema
     */
    public $schema;

    /**
     * @var FragmentDefinitionNode[]
     */
    public $fragments;

    /**
     * @var mixed
     */
    public $rootValue;

    /**
     * @var OperationDefinitionNode
     */
    public $operation;

    /**
     * @var array<variableName, mixed>
     */
    public $variableValues;

    /**
     * Helper method that returns names of all fields selected in query for 
     * $this->fieldName up to $depth levels
     *
     * Example:
     * query MyQuery{
     * {
     *   root {
     *     id,
     *     nested {
     *      nested1
     *      nested2 {
     *        nested3
     *      }
     *     }
     *   }
     * }
     *
     * Given this ResolveInfo instance is a part of "root" field resolution, and $depth === 1, 
     * method will return:
     * [
     *     'id' => true,
     *     'nested' => [
     *         nested1 => true,
     *         nested2 => true
     *     ]
     * ]
     *
     * @param int $depth How many levels to include in output
     * @return array
     */
    public function getFieldSelection($depth = 0);
}

GraphQL\Validator\DocumentValidator

namespace GraphQL\Validator;

use GraphQL\Error\Error;

class DocumentValidator
{
    /**
     * Returns all validation rules
     *
     * @return callable[]
     */
    public static function allRules();

    /**
     * Returns validation rule
     *
     * @param string $name
     * @return callable|null
     */
    public static function getRule($name);

    /**
     * Implements the "Validation" section of the spec.
     *
     * Validation runs synchronously, returning an array of encountered errors, or
     * an empty array if no errors were encountered and the document is valid.
     *
     * A list of specific validation rules may be provided. If not provided, the
     * default list of rules defined by the GraphQL specification will be used.
     *
     * Each validation rules is a function which returns a visitor
     * (see the GraphQL\Language\Visitor API). Visitor methods are expected to return
     * GraphQL\Error\Error, or arrays of GraphQL\Error\Error when invalid.
     *
     * Optionally a custom TypeInfo instance may be provided. If not provided, one
     * will be created from the provided schema.
     *
     * @return Error[]
     */
    public static function validate(
        Schema $schema,
        DocumentNode $ast,
        array $rules = null,
        TypeInfo $typeInfo = null
    );
}

GraphQL\Error\Error

Class describing an Error found during the parse, validate, or execute phases of performing a GraphQL operation.

In addition to a message and stack trace, it also includes information about the locations in a GraphQL document and/or execution result that correspond to the Error.

namespace GraphQL\Error;

class Error extends \Exception implements \JsonSerializable, ClientAware
{
    const CATEGORY_GRAPHQL = 'graphql';
    const CATEGORY_INTERNAL = 'internal';

    /**
     * Part of ClientAware interface
     *
     * @return boolean
     */
    public function isClientSafe();

    /**
     * Part of ClientAware interface
     *
     * @return string
     */
    public function getCategory();

    /**
     * @return SourceLocation[]
     */
    public function getLocations();

    /**
     * Returns an array describing the JSON-path into the execution response which
     * corresponds to this error. Only included for errors during execution.
     *
     * @return array|null
     */
    public function getPath();

GraphQL\Error\Warning

final class Warning
{
    const NAME_WARNING = 1;
    const ASSIGN_WARNING = 2;
    const CONFIG_WARNING = 4;
    const FULL_SCHEMA_SCAN_WARNING = 8;
    const CONFIG_DEPRECATION_WARNING = 16;
    const NOT_A_TYPE = 32;

    /**
     * Sets warning handler which (when set) will intercept all system warnings.
     * When not set, trigger_error() is used to notify about warnings.
     *
     * @param callable|null $warningHandler
     */
    public static function setWarningHandler(callable $warningHandler = null);

    /**
     * Suppress warning by id (has no effect when custom warning handler is set)
     *
     * Usage example:
     * Warning::suppress(Warning::NOT_A_TYPE)
     *
     * When passing true - suppresses all warnings.
     *
     * @param bool|int $suppress
     */
    static function suppress($suppress = true);

    /**
     * Re-enable previously suppressed warning by id
     *
     * Usage example:
     * Warning::suppress(Warning::NOT_A_TYPE)
     *
     * When passing true - re-enables all warnings.
     *
     * @param bool|int $enable
     */
    public static function enable($enable = true);
}

GraphQL\Error\ClientAware

namespace GraphQL\Error;

interface ClientAware
{
    /**
     * Returns true when exception message is safe to be displayed to client
     *
     * @return bool
     */
    public function isClientSafe();

    /**
     * Returns string describing error category.
     *
     * Value "graphql" is reserved for errors produced by query parsing or validation, do not use it.
     *
     * @return string
     */
    public function getCategory();
}

GraphQL\Error\Debug

namespace GraphQL\Error;

class Debug
{
    const INCLUDE_DEBUG_MESSAGE = 1;
    const INCLUDE_TRACE = 2;
    const RETHROW_INTERNAL_EXCEPTIONS = 4;
}

GraphQL\Error\FormattedError

namespace GraphQL\Error;

class FormattedError
{
    public static function setInternalErrorMessage($msg);

    /**
     * Standard GraphQL error formatter. Converts any exception to array conforming to GraphQL spec
     *
     * @param \Throwable $e
     * @param bool|int $debug
     * @param string $internalErrorMessage
     *
     * @return array
     */
    public static function createFromException($e, $debug = false, $internalErrorMessage = null);
    
    /**
     * Adds "debugMessage", "trace", "file", "line" entries to $formattedError.
     * 
     * @return array
     */
    public static function addDebugEntries(array $formattedError, $e, $debug);
    
    /**
     * Prepares final error formatter taking in account $debug flags.
     * If initial formatter is not set, FormattedError::createFromException is used
     *
     * @return callable|\Closure
     */
    public static function prepareFormatter(callable $formatter = null, $debug);
}