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->getGql().

View source

Public Properties

Property	Description
activeSchema	craft\models\GqlSchema
allSchemaComponents	array
behaviors	\yii\base\Behavior<static>[] – List of behaviors attached to this component.
oAuthResource	craft\oauth\Resource
publicSchema	craft\models\GqlSchema, null
publicToken	craft\models\GqlToken, null
schemaDef	\GraphQL\Type\Schema
schemas	craft\models\GqlSchema[]
tokens	craft\models\GqlToken[]
validationRules	array

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

oAuthResource

Type

craft\oauth\Resource

Default value

null

Access

Read-only

Since

5.12.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

Method	Description
__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.
defineContentArgumentsForFieldLayouts()	Returns the content arguments for a given element type and field layouts.
defineContentArgumentsForFields()	Returns the content arguments for a given element type and custom fields.
defineContentArgumentsForGeneratedFields()	Returns the content arguments for a given element type and generated fields.
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()	Returns the content arguments for an element class based on the given contexts.
getFieldLayoutArguments()	Returns arguments for fields in the given field layout.
getOAuthResource()	Returns the GraphQL API’s protected OAuth resource definition.
getOrSetContentArguments()	Returns the content arguments
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.
getSchemaForUser()	Returns a schema for authenticated requests made on behalf of a user, made up of the schema components that support authenticated requests and are available to that user.
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.

defineContentArgumentsForFieldLayouts()

Since

5.0.0

Returns the content arguments for a given element type and field layouts.

View source

Arguments

• $elementType (class-string<\craft\base\ElementInterface>)
• $fieldLayouts (craft\models\FieldLayout[])

Returns

array

defineContentArgumentsForFields()

Since

5.0.0

Returns the content arguments for a given element type and custom fields.

View source

Arguments

• $elementType (class-string<\craft\base\ElementInterface>)
• $fields (craft\base\FieldInterface[])

Returns

array

defineContentArgumentsForGeneratedFields()

Since

5.8.0

Returns the content arguments for a given element type and generated fields.

View source

Arguments

• $elementType (class-string<\craft\base\ElementInterface>)
• $fields (array)

Returns

array

deleteSchema()

Since

3.4.0

Deletes a GraphQL schema.

View source

Arguments

• $schema (craft\models\GqlSchema)

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

• craft\errors\GqlException
  if no schema is currently active.

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

• $cacheKey (string)

Returns

array, null

getContentArguments()

Returns the content arguments for an element class based on the given contexts.

View source

Arguments

• $contexts (array)
• $elementType (class-string<\craft\base\ElementInterface>)

Returns

array

getFieldLayoutArguments()

Since

5.6.0

Returns arguments for fields in the given field layout.

View source

Arguments

• $fieldLayout (craft\models\FieldLayout)

Returns

array

getOAuthResource()

Since

5.12.0

Returns the GraphQL API’s protected OAuth resource definition.

View source

Returns

craft\oauth\Resource

getOrSetContentArguments()

Since

5.0.0

Returns the content arguments

View source

Arguments

• $elementType (class-string<\craft\base\ElementInterface>)
• $setter (callable)

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

• yii\base\Exception

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

• $schema (craft\models\GqlSchema, null)
• $prebuildSchema (boolean) – Should the schema be deep-scanned and pre-built instead of lazy-loaded

Returns

\GraphQL\Type\Schema

Throws

• craft\errors\GqlException
  in case of invalid schema

getSchemaForUser()

Since

5.12.0

Returns a schema for authenticated requests made on behalf of a user, made up of the schema components that support authenticated requests and are available to that user.

The schema’s scope is cached per user, and varies by the project config version and the user’s permissions. Components whose authenticated callbacks depend on anything else should be available whenever the user might need them, and limit their results instead.

View source

Arguments

• $user (craft\elements\User) – The user the request is authenticated as
• $includeMutations (boolean) – Whether mutation components should be included

Returns

craft\models\GqlSchema

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

• $token (string)

Returns

craft\models\GqlToken

Throws

• yii\base\InvalidArgumentException
  if $token is invalid

getTokenById()

Since

3.4.0

Returns a GraphQL token by its ID.

View source

Arguments

• $id (integer)

Returns

craft\models\GqlToken, null

getTokenByName()

Since

3.4.0

Returns a GraphQL token by its name.

View source

Arguments

• $tokenName (string)

Returns

craft\models\GqlToken, null

getTokenByUid()

Since

3.4.0

Returns a GraphQL token by its UID.

View source

Arguments

• $uid (string)

Returns

craft\models\GqlToken

Throws

• yii\base\InvalidArgumentException
  if $uid is invalid

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

• $event (craft\events\ConfigEvent)

handleChangedSchema()

Since

3.4.0

Handle schema change

View source

Arguments

• $event (craft\events\ConfigEvent)

handleDeletedSchema()

Since

3.4.0

Handle schema getting deleted

View source

Arguments

• $event (craft\events\ConfigEvent)

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

• $fields (array)
• $typeName (string)

Returns

array

saveSchema()

Since

3.4.0

Saves a GraphQL schema.

View source

Arguments

• $schema (craft\models\GqlSchema) – The schema to save
• $runValidation (boolean) – Whether the schema should be validated

Returns

boolean – Whether the schema was saved successfully

Throws

• yii\base\Exception

saveToken()

Since

3.4.0

Saves a GraphQL token.

View source

Arguments

• $token (craft\models\GqlToken) – The schema to save
• $runValidation (boolean) – Whether the schema should be validated

Returns

boolean – Whether the schema was saved successfully

Throws

• yii\base\Exception

setActiveSchema()

Sets the active GraphQL schema.

View source

Arguments

• $schema (craft\models\GqlSchema, null) – The schema, or null to unset the active schema

setCachedResult()

Since

3.3.12

Cache a result for the key and tag it.

View source

Arguments

• $cacheKey (string)
• $result (array)
• $dependency (yii\caching\TagDependency, null)
• $duration (integer, null)

Constants

Constant	Description
CACHE_TAG
GRAPHQL_COMPLEXITY_CPU_HEAVY	Complexity value for accessing a field that will likely trigger a CPU heavy operation.
GRAPHQL_COMPLEXITY_EAGER_LOAD	Complexity value for accessing a field that will add an instance of eager-loading for the request.
GRAPHQL_COMPLEXITY_NPLUS1	Complexity value for accessing a field that will trigger a query for every parent returned.
GRAPHQL_COMPLEXITY_QUERY	Complexity value for accessing a field that will trigger a single query for the request.
GRAPHQL_COMPLEXITY_SIMPLE_FIELD	Complexity value for accessing a simple field.
GRAPHQL_COUNT_FIELD	The field name to use when fetching count of related elements
SCOPE_READ
SCOPE_WRITE

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.

Components can support authenticated (OAuth) requests by setting an authenticated key on their config, set to true if the component should be available to all authenticated users, or a callable that is passed a craft\elements\User and returns whether the component should be available to them. Components that support authenticated requests are responsible for limiting their results to what craft\models\GqlSchema::$user may access.

---

Example

php

use craft\elements\User;
use craft\events\RegisterGqlSchemaComponentsEvent;
use craft\services\Gql;
use yii\base\Event;

Event::on(Gql::class, Gql::EVENT_REGISTER_GQL_SCHEMA_COMPONENTS, function(RegisterGqlSchemaComponentsEvent $event) {
    $event->queries['My Plugin'] = [
        'widgets:read' => [
            'label' => 'Query for widgets',
            'authenticated' => fn(User $user) => $user->can('myPlugin:viewWidgets'),
        ],
    ];
});

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