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 |
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)
# 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. |
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. |
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() (opens new window) | Triggers an event. |
# deleteSchema()
- Since
- 3.4.0
Deletes a GraphQL schema.
View source (opens new window)
Arguments
$schema
(craft\models\GqlSchema)
Returns
# 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
# 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
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 (opens new window)
Returns
# 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
(array (opens new window))$elementType
(string (opens new window))
Returns
# 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
# 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, null (opens new window))$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
# 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
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
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
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
# 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
# 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)
# prepareFieldDefinitions()
Prepare field definitions for a given GraphQL type by giving plugins a chance to modify them.
View source (opens new window)
Arguments
$fields
(array (opens new window))$typeName
(string (opens new window))
Returns
# 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
# 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
# setActiveSchema()
Sets the active GraphQL schema.
View source (opens new window)
Arguments
$schema
(craft\models\GqlSchema, null (opens new window)) – The schema, ornull
to unset the active schema
Throws
# 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))$duration
(integer (opens new window), null (opens new window))
# 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 |
# 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
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
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
The event that is triggered when defining validation rules to be used.
Plugins get a chance to alter the GraphQL validation rule list.
Example
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
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
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
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
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
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
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
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
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;
});