Skip to content

Gql ​

Type
Class
Namespace
craft\services
Inherits
craft\services\Gql » yii\base\Component » yii\base\BaseObject
Implements
yii\base\Configurable
Since
3.3.0

GraphQL service.

An instance of the service is available via Craft::$app->gql.

View source

Public Properties ​

PropertyDescription
activeSchemacraft\models\GqlSchema
allSchemaComponentsarray
behaviorsyii\base\Behavior – List of behaviors attached to this component.
publicSchemacraft\models\GqlSchema, null
publicTokencraft\models\GqlToken, null
schemaDef\GraphQL\Type\Schema
schemascraft\models\GqlSchema[]
tokenscraft\models\GqlToken[]
validationRulesarray

activeSchema ​

Type
craft\models\GqlSchema
Default value
null
Access
Read-only

View source

allSchemaComponents ​

Type
array
Default value
null
Access
Read-only
Since
3.5.0

View source

publicSchema ​

Type
craft\models\GqlSchema, null
Default value
null
Access
Read-only

View source

publicToken ​

Type
craft\models\GqlToken, null
Default value
null
Access
Read-only
Since
3.5.0

View source

schemaDef ​

Type
\GraphQL\Type\Schema
Default value
null
Access
Read-only

View source

schemas ​

Type
craft\models\GqlSchema[]
Default value
null
Access
Read-only
Since
3.4.0

View source

tokens ​

Type
craft\models\GqlToken[]
Default value
null
Access
Read-only
Since
3.4.0

View source

validationRules ​

Type
array
Default value
null
Access
Read-only

View source

Public Methods ​

MethodDescription
__call()Calls the named method which is not a class method.
__clone()This method is called after the object is created by cloning an existing one.
__construct()Constructor.
__get()Returns the value of a component property.
__isset()Checks if a property is set, i.e. defined and not null.
__set()Sets the value of a component property.
__unset()Sets a component property to be null.
attachBehavior()Attaches a behavior to this component.
attachBehaviors()Attaches a list of behaviors to the component.
behaviors()Returns a list of behaviors that this component should behave as.
canGetProperty()Returns a value indicating whether a property can be read.
canSetProperty()Returns a value indicating whether a property can be set.
className()Returns the fully qualified name of this class.
deleteSchema()Deletes a GraphQL schema.
deleteSchemaById()Deletes a GraphQL schema by its ID.
deleteTokenById()Deletes a GraphQL token by its ID.
detachBehavior()Detaches a behavior from the component.
detachBehaviors()Detaches all behaviors from the component.
ensureBehaviors()Makes sure that the behaviors declared in behaviors() are attached to this component.
executeQuery()Execute a GraphQL query for a given schema.
flushCaches()Flush all GraphQL caches, registries and loaders.
getActiveSchema()Returns the active GraphQL schema.
getAllSchemaComponents()Returns all of the known GraphQL schema components.
getBehavior()Returns the named behavior object.
getBehaviors()Returns all behaviors attached to this component.
getCachedResult()Returns the cached result for a key.
getContentArguments()Return the content arguments based on an element class and contexts for it.
getPublicSchema()Returns the public schema. If it does not exist and admin changes are allowed, it will be created.
getPublicToken()Returns the public token. If it does not exist and admin changes are allowed, it will be created.
getSchemaById()Get a schema by its ID.
getSchemaByUid()Get a schema by its UID.
getSchemaDef()Returns the GraphQL schema.
getSchemas()Get all schemas.
getTokenByAccessToken()Returns a GraphQL token by its access token.
getTokenById()Returns a GraphQL token by its ID.
getTokenByName()Returns a GraphQL token by its name.
getTokenByUid()Returns a GraphQL token by its UID.
getTokens()Returns all GraphQL tokens.
getValidationRules()Return a set of validation rules to use.
handleChangedPublicToken()Handle public token settings being updated.
handleChangedSchema()Handle schema change
handleDeletedSchema()Handle schema getting deleted
handleQueryErrors()Custom error handler for GraphQL query errors
hasEventHandlers()Returns a value indicating whether there is any handler attached to the named event.
hasMethod()Returns a value indicating whether a method is defined.
hasProperty()Returns a value indicating whether a property is defined for this component.
init()Initializes the object.
invalidateCaches()Invalidates all GraphQL result caches.
off()Detaches an existing event handler from this component.
on()Attaches an event handler to an event.
prepareFieldDefinitions()Prepare field definitions for a given GraphQL type by giving plugins a chance to modify them.
saveSchema()Saves a GraphQL schema.
saveToken()Saves a GraphQL token.
setActiveSchema()Sets the active GraphQL schema.
setCachedResult()Cache a result for the key and tag it.
trigger()Triggers an event.

deleteSchema() ​

Since
3.4.0

Deletes a GraphQL schema.

View source

Arguments ​

Returns ​

boolean

deleteSchemaById() ​

Since
3.4.0

Deletes a GraphQL schema by its ID.

View source

Arguments ​

  • $id (integer) – The schema's ID

Returns ​

boolean – Whether the schema was deleted.

deleteTokenById() ​

Since
3.4.0

Deletes a GraphQL token by its ID.

View source

Arguments ​

  • $id (integer) – The schemas's ID

Returns ​

boolean – Whether the schema was deleted.

executeQuery() ​

Since
3.3.11

Execute a GraphQL query for a given schema.

View source

Arguments ​

  • $schema (craft\models\GqlSchema) – The schema definition to use.
  • $query (string) – The query string to execute.
  • $variables (array, null) – The variables to use.
  • $operationName (string, null) – The operation name.
  • $debugMode (boolean) – Whether debug mode validations rules should be used for GraphQL.

Returns ​

array

flushCaches() ​

Flush all GraphQL caches, registries and loaders.

View source

getActiveSchema() ​

Returns the active GraphQL schema.

View source

Returns ​

craft\models\GqlSchema

Throws ​

getAllSchemaComponents() ​

Since
3.5.0

Returns all of the known GraphQL schema components.

View source

Returns ​

array

getCachedResult() ​

Since
3.3.12

Returns the cached result for a key.

View source

Arguments ​

Returns ​

array, null

getContentArguments() ​

Return the content arguments based on an element class and contexts for it.

View source

Arguments ​

Returns ​

array

getPublicSchema() ​

Returns the public schema. If it does not exist and admin changes are allowed, it will be created.

View source

Returns ​

craft\models\GqlSchema, null

Throws ​

getPublicToken() ​

Since
3.5.0

Returns the public token. If it does not exist and admin changes are allowed, it will be created.

View source

Returns ​

craft\models\GqlToken, null

getSchemaById() ​

Get a schema by its ID.

View source

Arguments ​

  • $id (integer) – The schema's ID

Returns ​

craft\models\GqlSchema, null

getSchemaByUid() ​

Since
3.4.0

Get a schema by its UID.

View source

Arguments ​

  • $uid (string) – The schema's UID

Returns ​

craft\models\GqlSchema, null

getSchemaDef() ​

Returns the GraphQL schema.

View source

Arguments ​

Returns ​

\GraphQL\Type\Schema

Throws ​

getSchemas() ​

Since
3.4.0

Get all schemas.

View source

Returns ​

craft\models\GqlSchema[]

getTokenByAccessToken() ​

Since
3.4.0

Returns a GraphQL token by its access token.

View source

Arguments ​

Returns ​

craft\models\GqlToken

Throws ​

getTokenById() ​

Since
3.4.0

Returns a GraphQL token by its ID.

View source

Arguments ​

Returns ​

craft\models\GqlToken, null

getTokenByName() ​

Since
3.4.0

Returns a GraphQL token by its name.

View source

Arguments ​

Returns ​

craft\models\GqlToken, null

getTokenByUid() ​

Since
3.4.0

Returns a GraphQL token by its UID.

View source

Arguments ​

Returns ​

craft\models\GqlToken

Throws ​

getTokens() ​

Since
3.4.0

Returns all GraphQL tokens.

View source

Returns ​

craft\models\GqlToken[]

getValidationRules() ​

Return a set of validation rules to use.

View source

Arguments ​

  • $debug (boolean) – Whether debugging validation rules should be allowed.
  • $isIntrospectionQuery (boolean) – Whether this is an introspection query

Returns ​

array

handleChangedPublicToken() ​

Since
3.5.0

Handle public token settings being updated.

View source

Arguments ​

handleChangedSchema() ​

Since
3.4.0

Handle schema change

View source

Arguments ​

handleDeletedSchema() ​

Since
3.4.0

Handle schema getting deleted

View source

Arguments ​

handleQueryErrors() ​

Since
3.6.2

Custom error handler for GraphQL query errors

View source

Arguments ​

  • $errors (\GraphQL\Error\Error[])
  • $formatter (callable)

Returns ​

\GraphQL\Error\Error[]

invalidateCaches() ​

Since
3.3.12

Invalidates all GraphQL result caches.

View source

prepareFieldDefinitions() ​

Prepare field definitions for a given GraphQL type by giving plugins a chance to modify them.

View source

Arguments ​

Returns ​

array

saveSchema() ​

Since
3.4.0

Saves a GraphQL schema.

View source

Arguments ​

Returns ​

boolean – Whether the schema was saved successfully

Throws ​

saveToken() ​

Since
3.4.0

Saves a GraphQL token.

View source

Arguments ​

Returns ​

boolean – Whether the schema was saved successfully

Throws ​

setActiveSchema() ​

Sets the active GraphQL schema.

View source

Arguments ​

Throws ​

setCachedResult() ​

Since
3.3.12

Cache a result for the key and tag it.

View source

Arguments ​

Constants ​

ConstantDescription
CACHE_TAG
GRAPHQL_COMPLEXITY_CPU_HEAVYComplexity value for accessing a field that will likely trigger a CPU heavy operation.
GRAPHQL_COMPLEXITY_EAGER_LOADComplexity value for accessing a field that will add an instance of eager-loading for the request.
GRAPHQL_COMPLEXITY_NPLUS1Complexity value for accessing a field that will trigger a query for every parent returned.
GRAPHQL_COMPLEXITY_QUERYComplexity value for accessing a field that will trigger a single query for the request.
GRAPHQL_COMPLEXITY_SIMPLE_FIELDComplexity value for accessing a simple field.
GRAPHQL_COUNT_FIELDThe field name to use when fetching count of related elements

Events ​

EVENT_AFTER_EXECUTE_GQL_QUERY ​

Type
craft\events\ExecuteGqlQueryEvent
Since
3.3.11

The event that is triggered after executing the GraphQL query.

Plugins get a chance to do something after a performed GraphQL query.


Example ​

php
use craft\events\ExecuteGqlQueryEvent;
use craft\services\Gql;
use yii\base\Event;

Event::on(Gql::class,
    Gql::EVENT_AFTER_EXECUTE_GQL_QUERY,
    function(ExecuteGqlQueryEvent $event) {
        // Cache the results from $event->result or just tweak them
    }
);

EVENT_BEFORE_EXECUTE_GQL_QUERY ​

Type
craft\events\ExecuteGqlQueryEvent
Since
3.3.11

The event that is triggered before executing the GraphQL query.

Plugins get a chance to modify the query or return a cached response.


Example ​

php
use craft\events\ExecuteGqlQueryEvent;
use craft\services\Gql;
use yii\base\Event;

Event::on(Gql::class,
    Gql::EVENT_BEFORE_EXECUTE_GQL_QUERY,
    function(ExecuteGqlQueryEvent $event) {
        // Set the result from cache
        $event->result = ...;
    }
);

EVENT_DEFINE_GQL_VALIDATION_RULES ​

Type
craft\events\DefineGqlValidationRulesEvent

The event that is triggered when defining validation rules to be used.

Plugins get a chance to alter the GraphQL validation rule list.


Example ​

php
use craft\events\DefineGqlValidationRulesEvent;
use craft\services\Gql;
use yii\base\Event;
use GraphQL\Type\Definition\Type;
use GraphQL\Validator\Rules\DisableIntrospection;

Event::on(Gql::class, Gql::::EVENT_DEFINE_GQL_VALIDATION_RULES, function (DefineGqlValidationRulesEvent $event) {
    // Disable introspection permanently.
    $event->validationRules[DisableIntrospection::class] = new DisableIntrospection();
});

EVENT_REGISTER_GQL_DIRECTIVES ​

Type
craft\events\RegisterGqlDirectivesEvent

The event that is triggered when registering GraphQL directives.

Plugins get a chance to add their own GraphQL directives. See GraphQL API for documentation on adding GraphQL support.


Example ​

php
use craft\events\RegisterGqlDirectivesEvent;
use craft\services\Gql;
use yii\base\Event;

Event::on(Gql::class,
    Gql::EVENT_REGISTER_GQL_DIRECTIVES,
    function(RegisterGqlDirectivesEvent $event) {
        $event->directives[] = MyDirective::class;
    }
);

EVENT_REGISTER_GQL_MUTATIONS ​

Type
craft\events\RegisterGqlMutationsEvent

The event that is triggered when registering GraphQL mutations.

Plugins get a chance to add their own GraphQL mutations. See GraphQL API for documentation on adding GraphQL support.


Example ​

php
use craft\events\RegisterGqlMutationsEvent;
use craft\services\Gql;
use yii\base\Event;
use GraphQL\Type\Definition\Type;

Event::on(Gql::class, Gql::EVENT_REGISTER_GQL_MUTATIONS, function(RegisterGqlMutationsEvent $event) {
    // Add my GraphQL mutations
    $event->mutations['mutationPluginData'] =
    [
        'type' => Type::listOf(MyType::getType()),
        'args' => MyArguments::getArguments(),
    ];
});

EVENT_REGISTER_GQL_QUERIES ​

Type
craft\events\RegisterGqlQueriesEvent

The event that is triggered when registering GraphQL queries.

Plugins get a chance to add their own GraphQL queries. See GraphQL API for documentation on adding GraphQL support.


Example ​

php
use craft\events\RegisterGqlQueriesEvent;
use craft\services\Gql;
use yii\base\Event;
use GraphQL\Type\Definition\Type;

Event::on(Gql::class, Gql::EVENT_REGISTER_GQL_QUERIES, function(RegisterGqlQueriesEvent $event) {
    // Add my GraphQL queries
    $event->queries['queryPluginData'] =
    [
        'type' => Type::listOf(MyType::getType()),
        'args' => MyArguments::getArguments(),
        'resolve' => MyResolver::class . '::resolve'
    ];
});

EVENT_REGISTER_GQL_SCHEMA_COMPONENTS ​

Type
craft\events\RegisterGqlSchemaComponentsEvent
Since
3.5.0

The event that is triggered when registering GraphQL schema components.


EVENT_REGISTER_GQL_TYPES ​

Type
craft\events\RegisterGqlTypesEvent

The event that is triggered when registering GraphQL types.

Plugins get a chance to add their own GraphQL types. See GraphQL API for documentation on adding GraphQL support.


Example ​

php
use craft\events\RegisterGqlTypesEvent;
use craft\services\Gql;
use yii\base\Event;

Event::on(Gql::class, Gql::EVENT_REGISTER_GQL_TYPES, function(RegisterGqlTypesEvent $event) {
    // Add my GraphQL types
    $event->types[] = MyType::class;
});