Settings

Core Settings

WPGraphQL respects the WP core Settings API and exposes all core settings in the WPGraphQL Schema for querying and mutating. Any settings that are registered through register_settings() can be added to the schema.

Registering Custom Settings

WordPress has a register_settings() API that allows developers to register settings for their site. Check here for more information on how these settings are registered by group and name. In WordPress you could register a custom setting like so:

/**
 * Registers a text field setting for Wordpress 4.7 and higher.
 **/
function register_my_setting() {
    $args = [
      'type' => 'string',
      'sanitize_callback' => 'sanitize_text_field',
      'default' => NULL,
      'show_in_graphql' => true,
    ];
    register_setting( 'my_options_group', 'my_option_name', $args );
}

add_action( 'admin_init', 'register_my_setting' );

Since we set the show_in_graphql parameter to true the setting will now appear in the GraphQL schema under it's group name. If the setting was registered without one it will appear under generalSettings.

Queries

All Settings

Site settings can be queried in two different ways. As mentioned before, you register your own setting group, say catGifSettings, and you would see your setting group and fields appear in the GraphQL schema. You can query this data in two different ways. First, by accessing all of the site setting groups at once using the allSettings root query field which will return all of the settings fields with the setting group name prepended.

GraphiQL Loading...

Site Settings by Settings Group

Site settings can also be queried by setting group name. Field names will be the camel case version of the setting, no longer prepended by the group name since you are using it to query with.

General Settings

GraphiQL Loading...

Reading Settings

GraphiQL Loading...

Discussion Settings

GraphiQL Loading...

Writing Settings

GraphiQL Loading...

Mutations

Settings can be updated using GraphQL through a mutation. Custom settings would follow the allSettings naming conventions where the group name is prepended before the setting field name.

WP Core Settings Mutation

A mutation for core WP settings would look like:

mutation updateSettings($input: UpdateSettingsInput!) {
  updateSettings(input: $input) {
    clientMutationId
    allSettings {
      generalSettingsDateFormat
      generalSettingsDescription
      generalSettingsEmail
      generalSettingsLanguage
      generalSettingsStartOfWeek
      generalSettingsTimeFormat
      generalSettingsTimezone
      generalSettingsTitle
      generalSettingsUrl
      readingSettingsPostsPerPage
      discussionSettingsDefaultCommentStatus
      discussionSettingsDefaultPingStatus
      writingSettingsDefaultCategory
      writingSettingsDefaultPostFormat
      writingSettingsUseSmilies
    }
  }
}

Along with the following input variables, this mutation would update all of the core WP settings to match:

{
  input: {
    "clientMutationId": "UpdateSettingsTest",
    "discussionSettingsDefaultCommentStatus": "closed",
    "discussionSettingsDefaultPingStatus": "open",
    "generalSettingsDateFormat": "F j Y",
    "generalSettingsDescription": "Super Sweet Custom Site",
    "generalSettingsEmail": "hughie@wpgraphql.com",
    "generalSettingsLanguage": "English",
    "generalSettingsStartOfWeek": 1,
    "generalSettingsTimeFormat": "g:i a",
    "generalSettingsTimezone": "America/Denver",
    "generalSettingsTitle": "WPGraphQL",
    "readingSettingsPostsPerPage": 10,
    "writingSettingsDefaultCategory": 1,
    "writingSettingsDefaultPostFormat": "",
    "writingSettingsUseSmilies": true
  }
}

Custom Setting Groups and fields

Mutating your custom settings is very similar to mutating the core WP settings. The custom setting will appear with the field name prepended by the group name:

mutation updateSettings($input: UpdateSettingsInput!) {
  updateSettings(input: $input) {
    clientMutationId
    allSettings {
      clientMutationId
      catGifSettingsCatUrl
      catGifSettingsCatName
      catGifSettingsCatEmoji
    }
  }
}

{
  input: {
    "clientMutationId": "UpdateSettingsCustomSettingsTest",
    "catGifSettingsCatUrl": "http://gph.is/1oXJHnO",
    "catGifSettingsCatName": "Whiskers",
    "catGifSettingsCatEmoji": ":joy_cat:"
  }
}