wp-graphql / wp-graphql/wp-graphql

Bring the WPGraphQL settings screens together: one settings data layer, a React Settings page, and Site Health checks

Open
#4,344 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

effort: high impact: med object type: settings plugin: core plugin: ide scope: api type: enhancement
Dominant language
PHP
Stars
3.8k
Forks
472
Avg merge
1d 7h
Merged PRs (30d)
85

Description

#4342 adds a settings review that walks admins through the settings for access, request limits and debugging, with the tradeoffs of each. It uses WordPress components and reads settings from the settings registry, so extensions can add their own.

That makes three screens that edit the same WPGraphQL settings, and they don't feel like one product yet:

Settings page Settings review IDE Settings tab
UI classic PHP form with nav tabs React, @wordpress/components React
Saves through options.php form post REST wp-graphql/v1/settings-review updateGraphqlSetting mutation, registered by the IDE plugin
Validation each field's sanitize_callback type checks + sanitize_callback its own coercion + sanitize_callback

Here's what I'd like to work toward. Each step can ship on its own.

1. Site Health recommendations. Add WPGraphQL checks to Tools > Site Health, reported as "Recommended", never "Critical". Some of these depend on how the site is used, so they flag something to look at rather than say the site is unhealthy. For example, when the environment type is production:

  • public introspection is on
  • debug mode is on
  • query depth limiting is off
  • tracing or query logs are visible to any user

Each one explains the tradeoff and links to the setting.

For public introspection, the recommendation should also explain how decoupled clients can get the schema without it:

  • send introspection queries with credentials, since logged-in users can always introspect (for example application passwords)
  • or generate the schema at build time with wp graphql generate-static-schema and point codegen at that file

The docs should cover the same thing, so turning public introspection off never means breaking a build.

2. One settings data layer in core, used through REST and GraphQL. A single place that describes the settings registry (fields, types, choices, dependencies) and validates and saves values the same way every time. Two ways in:

  • a GraphQL mutation in core, based on the IDE's updateGraphqlSetting, so decoupled apps can manage WPGraphQL settings through GraphQL and we dogfood that ourselves
  • REST, which stays as the way to fix things when the GraphQL endpoint itself is misconfigured or blocked. That matters for settings like "only allow logged-in users", limits and debug mode.

The Settings page, the settings review and the IDE Settings tab would all use it.

3. Rebuild the Settings page with WordPress components. Sections as cards, the same controls and labels as the settings review, the "what you gain / what it costs" text shown next to each setting, search, and depends_on handled natively. DataForm from @wordpress/dataviews is worth evaluating, since that's the direction WordPress's own screens are going. Constraints:

  • register_graphql_settings_field() and its config keys stay the same, so extensions don't have to change anything.
  • Fields rendered by a custom PHP callback (Smart Cache has three) and types like html and wysiwyg need a fallback that shows the server-rendered markup.
  • The remaining Title Case labels ("Enable GraphiQL IDE" and others) move to sentence case to match.

4. Make the settings review a guided mode of the Settings page, using the same components, so the two can't drift apart.

Also worth doing along the way:

  • retake the screenshots in docs/debugging.md, which still show the old labels
  • update the "Enable GraphQL Tracing" wording in the Smart Cache README and the IDE's tracing tab
  • add a CLI docs page to the Smart Cache docs for wp graphql smart-cache documents

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

This is a multi-step umbrella proposal rather than a single newcomer-sized change. Start by selecting one independently shippable step, then read the settings registry, the REST settings-review endpoint, and the IDE's updateGraphqlSetting mutation. The separately named follow-ups include docs/debugging.md, the Smart Cache README and IDE tracing tab, and a CLI docs page for wp graphql smart-cache documents; done means completing one defined step without changing the extension-facing settings registration API.

Written by the indexing model from the issue text.

Assessment

Tech stack
graphql, php, react, wordpress
Domain
backend-api-design, cli, documentation, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.