Gql

Type

Class

Namespace

craft\services

Inherits

craft\services\Gql » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)

Implements

yii\base\Configurable (opens new window)

Since

3.3.0

GraphQL service.

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

View source (opens new window)

Public Properties

Property	Description
activeSchema	craft\models\GqlSchema
allPermissions	array (opens new window)
allSchemaComponents	array (opens new window)
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
publicSchema	craft\models\GqlSchema, null (opens new window)
publicToken	craft\models\GqlToken, null (opens new window)
schemaDef	\GraphQL\Type\Schema
schemas	craft\models\GqlSchema[]
tokens	craft\models\GqlToken[]
validationRules	array (opens new window)

activeSchema

Type

craft\models\GqlSchema

Default value

null

Access

Read-only

View source (opens new window)

allPermissions

Type

array (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

allSchemaComponents

Type

array (opens new window)

Default value

null

Access

Read-only

Since

3.5.0

View source (opens new window)

publicSchema

Type

craft\models\GqlSchema, null (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

publicToken

Type

craft\models\GqlToken, null (opens new window)

Default value

null

Access

Read-only

Since

3.5.0

View source (opens new window)

schemaDef

Type

\GraphQL\Type\Schema

Default value

null

Access

Read-only

View source (opens new window)

schemas

Type

craft\models\GqlSchema[]

Default value

null

Access

Read-only

Since

3.4.0

View source (opens new window)

tokens

Type

craft\models\GqlToken[]

Default value

null

Access

Read-only

Since

3.4.0

View source (opens new window)

validationRules

Type

array (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__clone() (opens new window)	This method is called after the object is created by cloning an existing one.
__construct() (opens new window)	Constructor.
__get() (opens new window)	Returns the value of a component property.
__isset() (opens new window)	Checks if a property is set, i.e. defined and not null.
__set() (opens new window)	Sets the value of a component property.
__unset() (opens new window)	Sets a component property to be null.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
behaviors() (opens new window)	Returns a list of behaviors that this component should behave as.
canGetProperty() (opens new window)	Returns a value indicating whether a property can be read.
canSetProperty() (opens new window)	Returns a value indicating whether a property can be set.
className() (opens new window)	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() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	Detaches all behaviors from the component.
ensureBehaviors() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) 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() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	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() (opens new window)	Returns a value indicating whether there is any handler attached to the named event.
hasMethod() (opens new window)	Returns a value indicating whether a method is defined.
hasProperty() (opens new window)	Returns a value indicating whether a property is defined for this component.
init() (opens new window)	Initializes the object.
invalidateCaches()	Invalidates all GraphQL result caches.
off() (opens new window)	Detaches an existing event handler from this component.
on() (opens new window)	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() (opens new window)	Triggers an event.

deleteSchema()

Since

3.4.0

Deletes a GraphQL schema.

View source (opens new window)

Arguments

• $schema

Returns

boolean (opens new window)

deleteSchemaById()

Since

3.4.0

Deletes a GraphQL schema by its ID.

View source (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the schema was deleted.

deleteTokenById()

Since

3.4.0

Deletes a GraphQL token by its ID.

View source (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the schema was deleted.

executeQuery()

Since

3.3.11

Execute a GraphQL query for a given schema.

View source (opens new window)

Arguments

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

Returns

array (opens new window)

flushCaches()

Flush all GraphQL caches, registries and loaders.

View source (opens new window)

getActiveSchema()

Returns the active GraphQL schema.

View source (opens new window)

Returns

craft\models\GqlSchema

Throws

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

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 (opens new window)

Returns

array (opens new window)

getAllSchemaComponents()

Since

3.5.0

Returns all of the known GraphQL schema components.

View source (opens new window)

Returns

array (opens new window)

getCachedResult()

Since

3.3.12

Returns the cached result for a key.

View source (opens new window)

Arguments

• $cacheKey (string (opens new window))

Returns

array (opens new window), null (opens new window)

getContentArguments()

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

View source (opens new window)

Arguments

• $contexts (craft\behaviors\FieldLayoutBehavior[])
• $elementType (string (opens new window))

Returns

array (opens new window)

getPublicSchema()

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

View source (opens new window)

Returns

craft\models\GqlSchema, null (opens new window)

Throws

• yii\base\Exception (opens new window)

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 (opens new window)

Returns

craft\models\GqlToken, null (opens new window)

getSchemaById()

Get a schema by its ID.

View source (opens new window)

Arguments

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

Returns

craft\models\GqlSchema, null (opens new window)

getSchemaByUid()

Since

3.4.0

Get a schema by its UID.

View source (opens new window)

Arguments

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

Returns

craft\models\GqlSchema, null (opens new window)

getSchemaDef()

Returns the GraphQL schema.

View source (opens new window)

Arguments

• $schema (craft\models\GqlSchema)
• $prebuildSchema (boolean (opens new window)) – 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

getSchemas()

Since

3.4.0

Get all schemas.

View source (opens new window)

Returns

craft\models\GqlSchema[]

getTokenByAccessToken()

Since

3.4.0

Returns a GraphQL token by its access token.

View source (opens new window)

Arguments

• $token (string (opens new window))

Returns

craft\models\GqlToken

Throws

• yii\base\InvalidArgumentException (opens new window)
  if $token is invalid

getTokenById()

Since

3.4.0

Returns a GraphQL token by its ID.

View source (opens new window)

Arguments

• $id (integer (opens new window))

Returns

craft\models\GqlToken, null (opens new window)

getTokenByName()

Since

3.4.0

Returns a GraphQL token by its name.

View source (opens new window)

Arguments

• $tokenName (string (opens new window))

Returns

craft\models\GqlToken, null (opens new window)

getTokenByUid()

Since

3.4.0

Returns a GraphQL token by its UID.

View source (opens new window)

Arguments

• $uid (string (opens new window))

Returns

craft\models\GqlToken

Throws

• yii\base\InvalidArgumentException (opens new window)
  if $uid is invalid

getTokens()

Since

3.4.0

Returns all GraphQL tokens.

View source (opens new window)

Returns

craft\models\GqlToken[]

getValidationRules()

Return a set of validation rules to use.

View source (opens new window)

Arguments

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

Returns

array (opens new window)

handleChangedPublicToken()

Since

3.5.0

Handle public token settings being updated.

View source (opens new window)

Arguments

• $event (craft\events\ConfigEvent)

handleChangedSchema()

Since

3.4.0

Handle schema change

View source (opens new window)

Arguments

• $event (craft\events\ConfigEvent)

handleDeletedSchema()

Since

3.4.0

Handle schema getting deleted

View source (opens new window)

Arguments

• $event (craft\events\ConfigEvent)

handleQueryErrors()

Since

3.6.2

Custom error handler for GraphQL query errors

View source (opens new window)

Arguments

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

Returns

\GraphQL\Error\Error[]

invalidateCaches()

Since

3.3.12

Invalidates all GraphQL result caches.

View source (opens new window)

saveSchema()

Since

3.4.0

Saves a GraphQL schema.

View source (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the schema was saved successfully

Throws

• yii\base\Exception (opens new window)

saveToken()

Since

3.4.0

Saves a GraphQL token.

View source (opens new window)

Arguments

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

Returns

boolean (opens new window) – Whether the schema was saved successfully

Throws

• yii\base\Exception (opens new window)

setActiveSchema()

Sets the active GraphQL schema.

View source (opens new window)

Arguments

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

Throws

• yii\base\Exception (opens new window)

setCachedResult()

Since

3.3.12

Cache a result for the key and tag it.

View source (opens new window)

Arguments

• $cacheKey (string (opens new window))
• $result (array (opens new window))
• $dependency (yii\caching\TagDependency (opens new window), null (opens new window))

Constants

Constant	Description
CACHE_TAG
CONFIG_GQL_KEY
CONFIG_GQL_PUBLIC_TOKEN_KEY
CONFIG_GQL_SCHEMAS_KEY
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

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 (opens new window) 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 (opens new window) 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 (opens new window) 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 (opens new window) 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;
});