silverstripe / graphql-devtools
Tools to help developers building new applications on SilverStripe’s GraphQL API
Installs: 241 457
Dependents: 6
Suggesters: 1
Security: 0
Stars: 14
Watchers: 12
Forks: 13
Open Issues: 4
Type:silverstripe-vendormodule
Requires
- silverstripe/graphql: ^3 || ^4 || ^5
- symfony/filesystem: ^4 || ^5 || ^6
- symfony/finder: ^4 || ^5 || ^6
Requires (Dev)
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3
This package is auto-updated.
Last update: 2024-11-26 20:59:02 UTC
README
Tools to help developers building new applications on SilverStripe’s GraphQL API
Installation
composer require --dev silverstripe/graphql-devtools
What it does
This module adds an implementation of graphiql, an in-browser IDE for GraphQL servers. It provides browseable documentation of your schema, as well as autocomplete and syntax-checking of your queries.
Accessing the IDE
In GraphQL 3.x, it can be accessed at /dev/graphiql/
.
In GraphQL 4.x+, it can be accessed at /dev/graphql/ide
.
This is because GraphQL 4+ has its own DevelopmentAdmin
controller.
The GraphQL v4 version of the module allows you to clear your schema by calling the /dev/graphql/clear
task.
Security
By default, the tool has the same restrictions as other development tools like dev/build
:
- In "dev" mode, it's available without authentication
- In "test" and "live" mode, it requires ADMIN permissions
- It's installed with
composer require --dev
by default. In most deployment contexts that'll mean it's not available on environments in "test" or "live" modes
Configuration
In most installations of SilverStripe, there are at least two GraphQL servers running - one
for the admin (admin/graphql
) and one for the user space (/graphql
). By default, only
the default
schema will show, but this is configurable.
Showing multiple schemas
Important: Due to a limitation in the GraphQL Playground library, showing multiple schemas will disable the persistence of IDE state across page refreshes.
Also important: When changing the available schemas, be sure to clear the local storage in your browser, otherwise, you'll get inconsistent state.
You can configure the visible schemas in the controller.
Show a select list of schemas
SilverStripe\GraphQLDevTools\Controller: # show two schemas schemas: - default - admin # default schema that is selected default_schema: admin
Show all schemas
SilverStripe\GraphQLDevTools\Controller: # show two schemas schemas: '*' default_schema: default
Further, you can override the config in the request, by using ?schema=<schemaName>
,
e.g. http://example.com/dev/graphql/ide?schema=mySchema
.
If you're using a custom controller for your GraphQL endpoint
The IDE finds schemas by checking Director
for routes that map to a SilverStripe\GraphQL\Controller
instance.
If for some reason you're using a custom controller, you might get an error: "Could not find your default schema 'default'. You will need to add one to the SilverStripe\Control\Director.rules
config setting."
To avoid this, you can explicitly map your graphql route to a schema in your Director config:
SilverStripe\Control\Director: rules: graphql: Controller: '%$MyCustomController' Schema: default
GraphQL schema initialise task
This module provides a GraphQLSchemaInitTask
task to initialise a basic GraphQL schema to get you started. It will create configuration files for your schema and a basic resolver. Specifically it will create:
app/_config/graphql.yml
app/_graphql
containing several yml filessrc/GraphQL/Resolvers.php
You must be in CLI mode to use this task
To view help for the task to see what options are available:
vendor/bin/sake dev/tasks/GraphQLSchemaInitTask help=1
To run the task with with minimal options:
vendor/bin/sake dev/tasks/GraphQLSchemaInitTask namespace=App
Upgrading and maintaining the IDE
The library running the IDE is GraphQL Playground. It is served from your local environment as an exposed resource. The setup is based on their "HTML Page" example seen here, which uses remote bundle files served from a CDN. This repository uses a manually created bundle file copied directly from the CDN. This may seem like a convoluted approach, but the main benefits are:
- It allows offline use
- It does not require setting up a build chain or installing NPM dependencies
- There is no need for SRI protection
To upgrade GraphQL Playground, refer to the example linked above and use their
CDN to download the latest distribution and drop it into this repository. Be sure
to update the comment at the top of the bundle.js
file to track the URL it was
downloaded from.