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
allPermissionsarray
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

allPermissions

Type
array
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.
getAllPermissions()Returns all of the known GraphQL permissions, sorted by category.
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.
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

  • $schema

Returns

boolean

deleteSchemaById()

Since
3.4.0

Deletes a GraphQL schema by its ID.

View source

Arguments

Returns

boolean – Whether the schema was deleted.

deleteTokenById()

Since
3.4.0

Deletes a GraphQL token by its ID.

View source

Arguments

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

getAllPermissions()

DEPRECATED

Deprecated in 3.5.0. Use \craft\services\Gql::get() instead.

Returns all of the known GraphQL permissions, sorted by category.

View source

Returns

array

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

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

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
CONFIG_GQL_KEY
CONFIG_GQL_PUBLIC_TOKEN_KEY
CONFIG_GQL_SCHEMAS_KEY
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_PERMISSIONS

DEPRECATED

Deprecated in 3.5.0. Use the EVENT_REGISTER_GQL_SCHEMA_COMPONENTS event instead.

Type
craft\events\RegisterGqlPermissionsEvent
Since
3.4.0

The event that is triggered when registering user permissions.


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;
});