[GraphQLSettings]
Available since Exponential 6.0.15 (in development, not in a release yet).
Summary
The group [GraphQLSettings] of settings/graphql.ini.
File
settings/graphql.ini; override it in settings/override/graphql.ini.append.php, in a siteaccess or in an extension.
Settings
| Setting | Default | Description |
|---|---|---|
| Enabled | disabled | enabled or disabled (the default). Off until it is switched on, for every siteaccess or in the settings of one (settings/siteaccess/<siteaccess>/graphql.ini.append.php). Disabled: /api/graphql answers 404, the session end point graphql/query answers 404, nothing else changes. |
| SiteAccessList[] | (empty array) | The siteaccesses that answer when Enabled=enabled; empty: every siteaccess. A request is answered by the siteaccess it matches (host, path or the X-Siteaccess header, as every REST request). |
| LibraryPath | (empty) | Where webonyx/graphql-php 15 is loaded from when the installation's Composer autoload has no GraphQL\GraphQL: a directory with vendor/autoload.php (a Composer directory that requires webonyx/graphql-php), or the package itself (the directory holding src/GraphQL.php). Relative to the installation root, or absolute. The environment variable GRAPHQL_LIBRARY_PATH is read the same way when this is empty. |
| NamingStyle | identifier | How content classes and their attributes are named in the schema: identifier (the default) as in the administration: the class ng_article is the type ng_article, its attribute short_title the field short_title pascal types in PascalCase (NgArticle), fields in camelCase (shortTitle) map as identifier, but the names of [GraphQLNaming] TypeNames[] and FieldNames[] win A name that is not a valid GraphQL name (a digit first, a dash) has every other character replaced by _ and a _ in front when it starts with a digit. An attribute named like a field every content has (id, name, children ...) gets the suffix _field (name_field). |
| ClassList[] | (empty array) | The classes the schema shows. Empty: every class except those of ExcludedClassList[]. Policies always apply: a class in the schema is still read only by who may read its objects. |
| ExcludedClassList[] | user; user_group; common_ini_settings; template_look | Never in the schema (unless ClassList[] names them): the user accounts, the user groups and the classes of settings. |
| HiddenFieldList[] | (empty array) | Attributes never in the schema, <class>/<attribute> or */<attribute> for every class. |
| HiddenDatatypeList[] | ezuser; ezpassword | Datatypes never in the schema: the user account (login, e-mail, password hash) and the password field. |
| Introspection | signed-in | Introspection (the schema read by a client, as the playground does): signed-in (the default) for a request signed in by a token, a personal API key or a session; refused for anonymous requests enabled for every request disabled for none (the console commands still print the schema) |
| MaxDepth | 12 | The deepest nesting of fields a query may have, and the highest complexity (every field counts 1, a list field counts its limit or first argument times the fields below it). A query over the limit is refused before it runs (extensions.code DEPTH_LIMIT or COMPLEXITY_LIMIT). |
| MaxComplexity | 1000 | |
| MaxListLimit | 100 | The most items one list field returns (limit, first); a bigger value is lowered to it. |
| DefaultListLimit | 25 | The items a list field returns when the query does not say. |
| PersistedQueries | enabled | Persisted queries: queries stored on the server (var/<site>/graphql/persisted/) and called by a name (GET /api/graphql?id=articles) or by their SHA-256 (Apollo's extensions.persistedQuery.sha256Hash). Stored with ./console exp:graphql:persist <file or directory> --apply. enabled (the default) or disabled. |
| AutomaticPersistedQueries | signed-in | Who may store a query by sending its text with its SHA-256 (Apollo's automatic persisted queries): signed-in (the default) a request signed in by a token, a personal API key or a session enabled every request, the anonymous one too (at most MaxPersistedQueries are stored) disabled nobody; queries are stored with exp:graphql:persist only A query that may not be stored still runs, as an ad-hoc query. |
| MaxPersistedQueries | 1000 | The most queries the store holds before an automatic persisted query is no longer stored (exp:graphql:persist stores regardless). |
| PersistedQueriesOnly | disabled | Only persisted queries are run at /api/graphql (an ad-hoc query is refused with PERSISTED_QUERY_REQUIRED): disabled (the default) any query anonymous anonymous requests may run persisted queries only, signed-in ones any query enabled every request to /api/graphql runs persisted queries only The session end point (the playground of Setup > GraphQL) and the console always run any query. |
| PersistedQueryDirectoryList[] | (empty array) | Directories of persisted queries shipped with the code: every <name>.graphql file is the persisted query <name>, read only (exp:graphql:persist --list shows them). Relative to the installation root, or absolute; an extension adds its own directory in its settings/graphql.ini.append.php. PersistedQueryDirectoryList[]=extension/myfrontend/graphql |
| MaxQueryLength | 100000 | The longest query text accepted, in bytes. |
| ResponseCache | enabled | The response cache: the answers of persisted queries, kept per siteaccess, schema, user rights (roles and their limitations, as the view cache), variables and address, in var/cache/graphql/responses/. An anonymous GET of a persisted query is answered from it at the start of index_rest.php, before the settings and the database. Every answer is expired when content is published (whenever view caches are cleared), when a class changes, when persisted queries are stored or removed, and by ezcache --clear-id=graphql (also --clear-tag=ini and content). Ad-hoc queries are never kept. enabled (the default) or disabled. |
| ResponseCacheTtl | 86400 | Seconds an answer is kept at most, also without a publish; 0: until it is expired. |
| CredentialCacheTtl | 60 | A signed-in GET of a persisted query is answered at the start of index_rest.php too, once the kernel has checked its token or key: the rights of the credentials (their user's roles) are remembered this many seconds (var/cache/graphql/credentials/), and forgotten at once when an API key, a role or a user's rights change. A token revoked otherwise still reads the answers cached for its rights until then. 0: signed-in requests always go through the kernel. |
| RateLimit | 600 | Rate limits: the requests one signed-in user or one personal API key (RateLimit), or one IP address of anonymous requests (RateLimitAnonymous), may send in RateLimitWindow seconds; 0: no limit. A request over its limit is answered 429 with RATE_LIMITED and Retry-After; every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Counted in var/cache/graphql/rate/ by every web server worker alike. The console is not limited. |
| RateLimitAnonymous | 120 | |
| RateLimitWindow | 60 | |
| SchemaExtensionList[] | expGraphQLTagsExtension; expGraphQLLayoutsExtension; expMigrationGraphQLExtension | Schema extensions: classes implementing expGraphQLSchemaExtension that add root queries, fields of Location and the types of their datatypes; each answers only where it is available (its extension active). The kernel ships the one of eztags (the root queries tag and tags, the eztags fields as [Tag]), the one of explayouts (the root query layout, Location.layout) and the one of the migrations (the read-only root queries migrationStatus, migrations, migrationRuns and migrationRun, for users with migration/read). An extension adds its own in its settings/graphql.ini.append.php. |
| ImageAliasList[] | small; medium; large | Image aliases (settings/image.ini) the field variations lists when the query names none; url(alias:) takes any alias of image.ini. |
| MutationsEnabled | enabled | Mutations (createContent, updateContent, translateContent, publishDraft, deleteContent, moveContent, hideContent, revealContent, addLocation, uploadImage, uploadFromUrl, createPreviewToken): enabled (the default) or disabled. They come on together with the end point (Enabled above). Enabled: each mutation checks the policies of the user on the content it changes, runs the kernel's operations (the workflows of content/publish, content/move ... included), is recorded in the audit (content.graphql.mutation) and expires the response cache. A mutation is sent with POST only, by a signed-in user (AnonymousMutations below); with a personal API key it needs the scope graphql:write; with the session of the web interface it needs the form token (header X-CSRF-Token). Disabled: the schema has no type Mutation and a mutation is refused with DISABLED. For a read-only API, disable it per siteaccess (./console exp:graphql:disable --siteaccess=<name> --mutations). |
| AnonymousMutations | disabled | Mutations of anonymous requests (they run with the Anonymous role's policies): disabled (the default) refuses them with FORBIDDEN; enabled lets them through to the policy checks (a guest book, a form that creates content). |
| MaxUploadSize | 32M | The largest file a mutation accepts (uploadImage, a FieldInput upload, uploadFromUrl), in bytes or with k, M, G. PHP's own upload_max_filesize and post_max_size limit a request before it gets here. |
| UploadCheckList[] | (empty array) | Checks every uploaded file passes before it is stored: classes implementing expGraphQLUploadCheck (a virus scanner, a type filter). The first that gives a reason refuses the file; a class that is missing refuses every file. UploadCheckList[]=myClamAvUploadCheck |
| FileDatatypeList[] | (empty array) | Datatypes whose value is a file, besides ezimage, ezbinaryfile and ezmedia: a FieldInput writes them with an upload only, never with a value (a path in a value could import any file of the server). |
| UploadFromUrlHostList[] | (empty array) | The hosts uploadFromUrl may fetch files from (https only, no redirects, at most MaxUploadSize). Empty (the default): uploadFromUrl is switched off. UploadFromUrlHostList[]=images.example.com |
| PreviewTokenTtl | 3600 | Preview tokens (createPreviewToken, the query preview(token:)): the seconds a token is valid when the mutation does not say, and the longest it may ask for. The tokens are signed with the installation's secret key (EXP_SECRET_KEY or var/secrets/exp_secret.key); rotating it ends every token. |
| MaxPreviewTokenTtl | 86400 | |
| Subscriptions | enabled | Subscriptions (subscription { contentPublished(classes: ["article"]) { objectId content { name } } }): enabled (the default) or disabled. They come on with the end point, at /api/graphql/subscribe: an event stream (SSE, the protocol graphql-sse) with PHP-FPM and with Velocity, and a WebSocket (graphql-transport-ws) through Velocity. Every event is sent only when the subscriber may read its content (the rights of that moment). A stream holds one PHP process (or Velocity worker) while it is open, but never a database connection: it follows the event journal ([GraphQLEvents]) and opens a connection for each event it sends. Disabled: the schema has no type Subscription and /subscribe answers 404 with DISABLED. |
| AnonymousSubscriptions | disabled | Subscriptions of anonymous requests: disabled (the default) refuses them with FORBIDDEN; enabled lets a visitor subscribe (a live page), within MaxSubscriptionsPerAddress and the Anonymous role's rights. |
| MaxSubscriptions | 200 | The most subscriptions open at once on the installation, for one signed-in user, and from one IP address; past a limit a subscription is refused with SUBSCRIPTION_LIMIT (HTTP 429). 0: no limit. Each open stream holds a process: keep MaxSubscriptions below what PHP-FPM's pool (pm.max_children) or Velocity's StreamShare leaves for pages. |
| MaxSubscriptionsPerUser | 5 | |
| MaxSubscriptionsPerAddress | 10 | |
| SubscriptionHeartbeat | 15 | Seconds between two keep-alive comments of a stream; they keep proxies from closing it and find clients that left. |
| SubscriptionMaxDuration | 280 | Seconds a stream stays open; then it ends and the client opens it again with Last-Event-ID, missing no event the journal still has (EventSource and graphql-sse clients do so by themselves; Velocity's WebSocket bridge too). Keep it below Velocity's StreamTimeout (300 by default) and PHP's max_execution_time is raised to it. |
| SubscriptionIdleTimeout | 0 | Seconds a stream may go without sending an event before it ends the same way; 0 (the default): only SubscriptionMaxDuration ends it. |
| SubscriptionPollInterval | 500 | Milliseconds between two looks at the journal while nothing happens. |
| Debug | disabled | enabled or disabled (the default). Enabled: an error carries the PHP exception and its trace in extensions.debug. Only for a development siteaccess: a trace tells paths and code to whoever asks. |
See also
Generated example: graphql.ini [GraphQLSettings]
Added to the reference for Exponential 6.0.15: the 4.x reference had no page for this group. The descriptions are the comment lines of settings/graphql.ini.
Contributors
- Graham Brookins Updated
Comments
Add a comment