Build your First WPGraphQL Extension
This tutorial should be helpful for developers of any experience level, but it will be most useful for developers that have some previous experience building WordPress plugins.
In this guide we will build a plugin that extends the WPGraphQL Schema adding a custom Type and a Root Query Field that returns that type.
By the end of this tutorial we should be able to:
- Use GraphiQL to search and find
- Write a GraphQL Query to query for
customFieldand get data returned
The first step to building a WordPress plugin is to create a directory and a PHP file to put the code in.
In your WordPress site, navigate in the file system to the
The below screenshot shows the plugins directory with a few plugins already there.
Create a new folder. Let's call it
my-first-wpgraphql-extension. It is considered best practice to name WordPress plugin directories will all lowercase letters and hyphens to separate words.
Within that directory create a PHP file with the same name as the directory:
Open the PHP file in a text editor or IDE.
Add an opening php tag as the first line of the file, then immediately below, add the following snippet and save it:
Navigate to your WordPress Admin's Plugins page, and you should see "My First WPGraphQL Extension" plugin as a plugin available for activating.
Click "Activate" to activate the plugin. With the plugin active, any code we write will now be executed by WordPress. Without activating the plugin, any code we write would not be executed by WordPress.
Now that we have an active plugin, let's extend the WPGraphQL Schema by registering a new field to the Schema.
Add the following snippet below the previous snippet that defined the plugin name:
The first line of this code is telling WordPress that when the action
graphql_register_types is fired, execute the function named
graphql_register_types is fired by WPGraphQL when the GraphQL Schema is being built. This gives us access to hook in and modify the Schema before it's returned. This is the action you must hook into to modify the WPGraphQL Schema with new types or fields.
Below is the function
add_custom_field_to_graphql_root_query, which will execute as the Schema is being built.
Here, we call another function "register_graphql_field", which accepts 3 paramaters:
- Type Name: The name of the existing GraphQL Type to register a field to
- Field Name: The name the registered field should have
- Config: An array to configure the field
RootQuery as the Type Name to register the field to and
customField as the name of the field.
This means that the
RootQuery type in the Schema will now have a field named
customField and the field will follow the contract defined in the config.
The config array includes
type key of the config array is used to declare what GraphQL Type the field will return. In our case, we defined the
String. This means that we are making a contract with the API that when this field is asked for, a String will be returned.
description key of the config array is set to a translated string that will be used in Schema documentation for use in tools like GraphiQL.
resolve key of the config array is set to an anonymous function which will be executed whenever the field is asked for in a Query. Since we defined the
type as String, we need to make sure this function returns a string. In our case we have it return the string
At this point, we can open up GraphiQL in the WordPress Dashboard and search the word "custom" and we should see our new "customField" field in the Schema.
And since the field is on the RootQuery type, we can test querying for it like so:
Executing this query returns the
"value..." value that we defined in our resolve function for the field.
Let's take it a step further and say that we have more complex data than we can return with a String. We can define a new Object Type to use in the Schema.
For example sake, let's say we needed to return a custom object type that we will call
CustomType which has a
testField field that will return a string, and a
count field that will return an integer.
We can register this type to the WPGraphQL schema with the following code. This can be placed within the
This snippet registers a new Object Type to the WPGraphQL Schema. The first argument passed is the name of the type. Type names must be unique, meaning there can only be one type in the entire Schema with that name. We used the name
The next argument passed is a config array to configure the Type.
description key of the config array is a translated string that will be used in Schema documentation for use in tools like GraphiQL.
fields key of the config array is an array of fields, following the same pattern as the
register_graphql_field function, each with a
type and optional
In our case, we passed an array of 2 fields:
count, defining them as a
Now we have a type
CustomType in our Schema and we can verify this by searching in GraphiQL.
Note: Anytime you change the Schema on the server, you will need to refresh GraphiQL to re-fetch the Schema and pick up your changes.
We just registered a CustomType to the Schema, but it's not in use at all. In order to query data in the shape of the CustomType, it needs to be defined as the Type of a field.
Let's change the
type of our
customField to be
CustomType instead of
String. And let's change the resolver to return something that matches the shape of
CustomType so we can fulfill the contract we have with the Schema.
Here we change the
type to be
CustomType and we change the resolve function to return an array with a key of "count" and a value of "5", and a key of "testField" with a value of "test value…".
Since the field
customField no longer returns a string, but instead returns the type
CustomType we would need to adjust our query to reflect.
Executing the query now should return results like so:
This tutorial covered some of the basic ways to extend the WPGraphQL Schema for your needs, including registering fields to the Schema and registering new Types to the Schema.
Now that you have a basic understanding of building a WPGraphQL Extension, consider taking it to the next level and learning more about the APIs available to extend the Schema, and learn more about GraphQL and WPGraphQL Concepts