How do I configure GraphQL settings in Statamic's Control Panel

Enabling GraphQL in Statamic

To use GraphQL in Statamic, it must be first enabled. This can be done by adding or modifying configuration in either the `.env` file or the Statamic config file:

- In the `.env` file, add the line:

  STATAMIC_GRAPHQL_ENABLED=true
  

php
  'enabled' => true,
  

Once enabled, the GraphQL interface called GraphiQL becomes available inside the Control Panel, allowing exploration and testing of GraphQL queries directly from the UI.

Configuring Resources for GraphQL

GraphQL resources in Statamic represent different content types that can be queried. For security reasons, all resources are disabled by default, so it is important to enable the specific resources you want exposed. This configuration is managed through the `resources` array in `config/statamic/graphql.php`.

You can enable entire resource types such as collections or taxonomies like this:

php
'resources' => [
    'collections' => true,
    'taxonomies' => true,
    // other resources...
],

For more granular control, you can enable specific sub-resources within a resource type. For example, enable only certain collections:

php
'resources' => [
    'collections' => [
        'articles' => true,
        'pages' => true,
        // 'events' => false // This collection disabled
    ],
    'taxonomies' => true,
],

Enabling Filters on GraphQL Queries

By default, filtering of query results is disabled to ensure security out of the box. Filtering must be explicitly enabled per resource or sub-resource. You do this by specifying the allowed filters in the `allowed_filters` key for collections or taxonomies:

php
'resources' => [
    'collections' => [
        'articles' => [
            'allowed_filters' => ['title', 'status'],
        ],
        'pages' => [
            'allowed_filters' => ['title'],
        ],
        'events' => true, // enabled without filters
    ],
    'taxonomies' => [
        'topics' => [
            'allowed_filters' => ['slug'],
        ],
        'tags' => true,
    ],
],

Filters allow you to constrain the results in your GraphQL queries by fields with conditions such as `contains`, `ends_with`, or simple equality matches.

Using Filters in Queries

GraphQL supports filtering arguments that accept conditions in JSON-like syntax. For example, to filter entries where the title contains "rad" and ends with "!", a query would look like:

graphql
entries(filter: {
  title: { contains: "rad", ends_with: "!" }
}) {
  data {
    title
  }
}

If only a simple equality check is needed, you can directly assign the value:

graphql
entries(filter: {
  rating: 5
}) {
  # ...
}

You can combine multiple conditions on the same field by using an array of filter conditions.

Accessing Global Sets and Other Data Types

GraphQL also exposes global sets, assets, users, and taxonomies. For global sets, each set is represented as an interface implementing specific blueprints. You query for blueprint-specific fields by using fragments to extend the interface.

Example querying a global set called "Social":

graphql
globalSets {
  handle
  ... on GlobalSet_Social {
    twitter
  }
}

Custom Field Types and GraphQL Types

Custom field types in Statamic can define how they map to GraphQL types. By default, all fields return strings, but fieldtypes can specify more complex GraphQL return types using PHP code in their definitions.

For instance:
- A text field returns a `String`.
- A grid field can expose a list of `GridItem` types.
- Code editors can return structured data specifying code content and language mode.

Fieldtypes can register GraphQL types and arguments using specific methods allowing developers to extend the GraphQL schema.

Schema and Package Details

Statamic uses the `rebing/graphql-laravel` package under the hood to implement GraphQL. Statamic automatically integrates and configures this package. If a user publishes the schema config file, Statamic defers manual control to the developer.

The primary schema for Statamic's content is configured and set as the default for GraphQL requests. Developers can override default behaviors and extend schemas if needed.

GraphiQL Interface in Control Panel

With GraphQL enabled, Statamic provides an embedded GraphiQL playground inside the Control Panel where site administrators and developers can explore the schema, build, and test queries.

This interface makes it easier to learn what queries are possible, check the structure of responses, and experiment with filtering, sorting, and nested content fetching.

Setting Up Authentication and Security

Security with GraphQL endpoints involves controlling which resources are accessible and what filters are allowed. Additionally, you can set authentication to protect GraphQL endpoints based on your Statamic user roles and API security policies.

It is recommended to only enable necessary resources and restrict filters to minimum needed fields to mitigate potential data exposures.

Cache and Performance Tuning

Statamic allows some configuration around caching GraphQL query results and query complexity. This can improve performance for frequently accessed data and prevent overly complex queries from causing performance issues.

Cache settings and complexity limits can be configured in Statamic's GraphQL config files or environment settings depending on project needs.

Integrating GraphQL with Frontend Applications

Statamic's GraphQL API is especially powerful in headless CMS scenarios where frontend frameworks like Vue, React, or Angular consume the API.

Popular client libraries like Apollo Client can be used to fetch data at runtime, enabling dynamic, single-page applications and decoupled frontends. The control over queries ensures efficient data fetching without over-fetching or under-fetching.

GraphQL queries can be crafted to precisely fetch the content structure required by frontend components, including nested relationships and filters.

Summary of Steps to Configure GraphQL in Statamic Control Panel

1. Enable GraphQL via `.env` or `config/statamic/graphql.php`.
2. Enable required resources in `resources` array (collections, taxonomies, globals).
3. Configure allowed filters for those resources if filtering is needed.
4. Use GraphiQL inside Control Panel to explore and test queries.
5. Secure GraphQL endpoint access based on roles and exposure.
6. Optionally customize schemas, add custom field types, or extend queries.
7. Optimize caching and query performance based on usage.
8. Connect frontend applications using modern GraphQL client libraries.