Date

New Post Type and Taxonomy Registration options

WPGraphQL makes it easy to expose Custom Post Types and Taxonomies to the GraphQL Schema.

WPGraphQL v1.12.0 introduces new options for how your post types and taxonomies are added to the WPGraphQL Schema.

If you’re already familiar with how registering post types and taxonomies to GraphQL works, go ahead and skip to the new options or read the tutorial. But if you are new to it or want a refresher, keep reading.

Registering Post Types and Taxonomies to show in the WPGraphQL Schema

When registering a custom post type or taxonomy to WPGraphQL, there are 3 required arguments to add:

  • show_in_graphql | boolean | (required) : Whether to expose this post type or taxonomy to the GraphQL API.
  • graphql_single_name | string | (required): The GraphQL Type name that will represent nodes of this post type or taxonomy.
  • graphql_plural_name | string | (required) : The plural name of the GraphQL Type for use in connection field names.

With these 3 properties defined in the registration of a post type or taxonomy, a lot of things are added to the GraphQL Schema.

Let’s dive in!

For this example, we will start with a “testimonial” post type.

We could register the post type like so:

add_action( 'init', function() { 

  register_post_type( 'testimonial', [
    'public' => true,
    'label' => __( 'Testimonials', 'wp-graphql' ),
    'show_in_graphql' => true, # tells the post type to show in the GraphQL Schema
    'graphql_single_name' => 'Testimonial', # determines the GraphQL Type name for nodes of this post type
    'graphql_plural_name' => 'Testimonials', # determines the field name for connections to nodes of this post type
  ] );

} );

By adding these 3 lines of code (show_in_graphql, graphql_single_name, graphql_plural_name) to our post type registration, we are now able to query and mutate posts of the “testimonial” post type using GraphQL.

Let’s take a look at how these 3 lines affected the WPGraphQL API.

Schema

If we were to open the GraphiQL IDE documentation explorer and search our GraphQL Schema for “testimonial” (before setting the post type to show_in_graphql) we would see no results, like so:

Screenshot of GraphiQL Schema Docs with no results for “testimonial” search

If we search for “testimonial” (after setting the post type to “show_in_graphql”) we will see many different Types and Fields in the Schema.

Screenshot of GraphiQL Schema Docs with default results for “testimonial” search

Let’s break down exactly what was added to the GraphQL Schema.

Types & Fields

In the screenshot above, the gold-colored words represent GraphQL Types, and the blue-colored words represent fields.

By registering the post type to show_in_graphql, the schema now has 12 new GraphQL Types and 10 new fields, all for interacting with posts of the “testimonial” post type. (these numbers might differ in your system based on different conditions, but the point is, you should have a lot of new Types and Fields with minimal effort).

The GraphQL Types define the shape of objects in the graph, and the fields are the entry points into the graph for accessing data.

Let’s take a look more specifically at the Queries and Mutations provided by exposing this post type to the GraphQL Schema.

I’m not going to break down every single Type and Field that was added to the schema, but we’ll take a look at some of the main ones.

Queries

If we take a look at the fields that were added to the RootQuery type, we can see a few different ways we can now query for content in our “testimonial” post type.

  • RootQuery.testimonial: This allows for individual Testimonial nodes to be queried by id.
  • RootQuery.testimonialBy (deprecated): This is a deprecated version of the previous field.
  • RootQuery.testimonials: This allows for lists (called connections in GraphQL) of testimonials to be queried.

Mutations

If we look at the fields added to the RootMutation, we will see the following mutations:

  • RootMutation.createTestimonial
  • RootMutation.updateTestimonial
  • RootMutation.deleteTestimonial

These mutations allow for content of the testimonial post type to be created, updated and deleted via GraphQL mutations.

GraphQL Mutations respect the read and write privileges defined for each post type, so only authenticated users with proper capabilities can successfully execute these mutations.

New post type and taxonomy registration options

Now that we understand how registering post types and taxonomies to WPGraphQL works, we’ll take a look at the new options introduced in WPGraphQL v1.12.0 and see how they work.

Below are the new arguments that can be passed to register_post_type and register_taxonomy to provide further customization of how it will be represented in the GraphQL Schema:

  • graphql_kind: Allows the type representing the post type to be added to the graph as an object type, interface type or union type. Possible values are ‘object’, ‘interface’ or ‘union’. Default is ‘object’.
  • graphql_resolve_type: The callback used to resolve the type. Only used if “graphql_kind” is set to “union” or “interface”.
  • graphql_interfaces: List of Interface names the type should implement. These will be applied in addition to default interfaces such as “Node”.
  • graphql_exclude_interfaces: List of Interface names the type should not implement. This is applied after default and custom interfaces are added, so this can remove default interfaces.
    • Note: Interfaces applied by other interfaces will not be excluded unless that interface is also excluded. For example a post type that supports “thumbnail” will have NodeWithFeaturedImage interface applied, which also applies the Node interface. Excluding “Node” interface will not work unless “NodeWithFeaturedImage” was also excluded.
  • graphql_fields: Array of fields to add to the Type. Applied if “graphql_kind” is “interface” or “object”.
  • graphql_exclude_fields: Array of fields names to exclude from the type. Applies if “graphql_kind” is “interface” or “object”.
    • Note: any fields added by an interface will not be excluded with this option.
  • graphql_connections: Array of connection configs to register to the type. Only applies if the “graphql_kind” is “object” or “interface”.
  • graphql_exclude_connections: Array of connection field names to exclude from the type. Only connections defined on the type will be excluded. Connections defined on an Interface that is applied to the Type remain even if “excluded” in this list.
  • graphql_union_types: Array of possible types the union can resolve to. Only used if “graphql_kind” is set to “union”.
  • graphql_register_root_field: Whether to register a field to the RootQuery to query a single node of this type. Default true.
  • graphql_register_root_connection: Whether to register a connection to the RootQuery to query multiple nodes of this type. Default true.
  • graphql_exclude_mutations: Array of mutations to prevent from being registered. Possible values are “create”, “update”, “delete”.

For more information, check out the official documentation for adding Custom Post Types and Custom Taxonomies to the WPGraphQL Schema.

And for a more in-depth look at these options, check out the tutorial where we walk through multiple scenarios for managing “food” in the CMS and querying via WPGraphQL.