About GraphQL

GraphQL for ProcessWire

Category Other Modules
Modules that have a unique purpose not covered by existing categories.
Release StateBeta
Close to stable, but users are advised to be cautious and test thoroughly.*
Module Version0.23.4
Class NameProcessGraphQL
Date AddedFebruary 28, 2018
Last UpdatedMarch 28, 2018
Recommended ByNew recommendations may take up to 1 day to appear.


This module's files should be placed in /site/modules/ProcessGraphQL/
How to install or uninstall modules



Travis-CI Status

GraphQL for ProcessWire.

Table of Contents

  1. About
  2. Requirements
  3. Installation
  4. Configuration
  5. Access Control
  6. API
  7. Features
  8. Development

About ProcessGraphQL

ProcessGraphQL is a module for ProcessWire. The module seamlessly integrates to your ProcessWireweb app and allows you to serve the GraphQL api of your existing content. You don't need to applychanges to your content or it's structure. Just choose what you want to serve via GraphQL and your API is ready.

Here is an example of ProcessGraphQL in action after installing it to skyscrapers profile.

ProcessGraphQL Simple Query

See more demo here.


  • ProcessWire version >= 3.0.62
  • PHP version >= 5.6.0

It would be very helpful if you open an issue when encounter errors regardingenvironment incompatibilities.


To install the module, go to Modules -> Install -> Add New. Scroll down to get to the section Add Module from URL. Paste the URL of the latest release into the Module ZIP fileURL field and press Download.

ProcessWire will download this module and place it at /site/modules/ directory for you. After youdid that, you should see GraphQL module among others. Go ahead and press Install button nextto it.

After you installed the ProcessGraphQL, you will be taken to the module configuration page. Where youwill have many options to setup the module the way you want. More on that in the section below.


The ProcessGraphQL module will serve only the parts of your content which you explicitly ask for.The module configuration page provides you with exactly that. Here you should choose what parts of your website should be available via GraphQL API. The options are grouped into four sections.

Legal Templates

In this section you choose the templates that you want ProcessGraphQL to handle. The pages associatedwith the templates you choose here will be available to the superuser immediately. You will see laterhow you can grant access to these template to other user roles as well.

If some of your templates are disabled and you can't choose them. That means that their names are notcompatible with GraphQL api naming rules. You will have to change the names of the template and/orfield so that it conforms those rules if you want ProcessGraphQL module to handle for you.

Legal Fields

Here you should choose the fields that you want to be available via GraphQL API. These fields alsowill immediately be available to the superuser.

Beware when you choose system templates & fields as legal for ProcessGraphQL module. This couldpotentially expose very sensitive information and undermine security of your website.

Legal Page Fields

These are the built-in fields of the ProcessWire Page. You should choose only the ones you willcertainly need in your API. E.g. created, id, name, url, path, createdUser, parent, siblings and so on.

Legal PageFile Fields

Built-in fields of the FieldtypeFile and FieldtypeImage. E.g. filesize, url, ext, basename and so on.

Don't mind the Advanced section for now. We will come to that later. After you chose all partsyou need, submit the module configuration. Now you can go to Setup -> GraphQL and you will seethe GraphiQL GUI where you can query your GraphQL api. Go ahead and play with it.

Access Control

As mentioned above, the GraphQL API will be accessible only by superuser. To grant access to userswith different roles, you need to use Access settings in your templates and fields. Say you want auser with role skyscraper-editor to be able to view pages with template skyscraper. Go to Setup ->Templates -> skyscraper -> Access, enable access settings, and make sure that skyscraper-editor role has View Page rule.

The ProcessWire'a Access Control system is very flexible and allows you to fine tune your access rulesthe way you want. You will use it to control your GraphQL API as well. Learn more about ProcessWire's Access Control system here.

The above configuration will allow the skyscraper-editor to view skyscraper pages' built-in fieldsthat you have enabled, but that's not the end of it. If you want the skyscraper-editor user to viewthe template fields like title, headline, body, you will need to make those fields viewable intheir respective Access settings.

You might say that this much restriction is too much. It is true, but no worries we got you covered.This is just the default behavior and set that way to ensure maximum security. If you don't want to go over fields' Access settings and setup rules for each of them manually, you can change the module's behavior in the Advanced section of the module configuration page. There are two options that changethe module's behavior regarding security.

Grant Template Access

If you check this field, all the legal templates that do not have their Access settings enabled, willbe available to everyone. But they will still conform to Access settings when they are enabled.So you can restrict each template via their Access settings.

Grant Field Access

This works the same as the above. Grants access to all fields that do not have Access settingsenabled. This option could be useful in cases where you have 20 or something fields and you want all of them be accessible and add restrictions to only few via field's Access settings. Remember that you can also configure field Access rules in template context. That means you can make images fieldviewable in skyscraper template and closed in others.


GraphQL endpoint

If you wish to expose your GraphQL api, you can do so by calling a single method on ProcessGraphQL modulein your template file. Here is what it might look like

// /site/templates/graphql.php
echo $modules->get('ProcessGraphQL')->executeGraphQL();

This will automatically capture the GraphQL request from your client and respond to it. If you needsome manual control on this, executeGraphQL accepts $query & $variables arguments and it willrespond to them instead of trying to guess query from the client. This allows you to modify the request from the client before passing it to ProcessGraphQL. Here how it might look like.

// /site/templates/graphql.php
$query = $input->post->query;
$variables = $input->post->variables;
// modify your $query and $variables here...
$result = $modules->get('ProcessGraphQL')->executeGraphQL($query, $variables);
echo $result;

GraphiQL endpoint

You can also expose the GraphiQL from within your template. Here is how you can do that.

// /site/templates/graphiql.php
echo $modules->get('ProcessGraphQL')->executeGraphiQL();

Please note that GraphiQL is a full web page. Meaning it includes <header>, <title> and so on.Depending on your site configuration you might want to disable $config->prependTemplateFile and/or $config->appendTemplateFile for the template that exposes GraphiQL.

By default the GraphiQL is pointed to your admin GraphQL server, which is /processwire/setup/graphql/.You might want to change that because ProcessWire will not allow guest users to access that url. You can point GraphiQL to whatever adress you want by a property GraphQLServerUrl. ProcessGraphQLwill respect that property when exposing GraphiQL. Here is how you might do this in your template file.

// /site/templates/graphiql.php
$ProcessGraphQL = $modules->get('ProcessGraphQL');
$ProcessGraphQL->GraphQLServerUrl = '/graphql/';
echo $ProcessGraphQL->executeGraphiQL();

Make sure the url is exactly where your GraphQL api is. E.g. it ends with slash.See here why it is important.

Modifying Query and Mutation

There could be cases when you want to include some custom fields into your GraphQL query and mutationoperation. There are two ProcessWire hooks that allows you to do that.

getQuery() hook

You can hook into getQuery method of the ProcessGraphQL class to add some custom fields into yourGraphQL query operation. Here how it could look like in your graphql.php template file.

<?php namespace ProcessWire;
use Youshido\GraphQL\Type\Scalar\StringType;
$processGraphQL = $modules->get('ProcessGraphQL');
wire()->addHookAfter('ProcessGraphQL::getQuery', function ($event) {
    $query = $event->return;
    $query->addField('hello', [
        'type' => new StringType(),
        'resolve' => function () {
            return 'world!';
echo $processGraphQL->executeGraphQL();

The above code will add a hello field into your GraphQL api that reponds with the string world.You should notice that we use third party library Youshido\GraphQL to modify our query. It's thelibrary used by ProcessGraphQL internally. We recommend you to checkout the library documentation to learn more about how you can modify your GraphQL api.

getMutation() hook

You can also hook into getMutation method of ProcessGraphQL class to add custom fields into yourGraphQL mutation operation. It works exactly like the getQuery hook method.


GraphQL Operations

The module will eventually support all operations you need to build fully functioning SPA. For nowyou can perform most common operations.

  • Fetch pages, page fields, subfields. Including file and image fields.
  • Authenticate. You can login and logout with your GraphQL API.
  • Page creation. You can create pages via GraphQL API.
  • Language support. If your site uses ProcessWire's core LanguageSupport module, you can fetch datain your desired language.
  • me field. Allows the user to query her credentials.
  • pages field. Experimental. Allows you to fetch any page in your website, just like $pages->find()

Compatible Fields

At this moment ProcessGraphQL handles most of the ProcessWire's core fieldtypes. Those are:

  • FieldtypeCheckbox
  • FieldtypeDatetime
  • FieldtypeEmail
  • FieldtypeFile
  • FieldtypeFloat
  • FieldtypeImage
  • FieldtypeInteger
  • FieldtypeOptions
  • FieldtypePage
  • FieldtypePageTitle
  • FieldtypePageTitleLanguage
  • FieldtypeSelector
  • FieldtypeText
  • FieldtypeTextLanguage
  • FieldtypeTextarea
  • FieldtypeTextareaLanguage
  • FieldtypeURL
  • FieldtypeMapMarker (via GraphQLFieldtypeMapMarker)

Third-party Fieldtypes Support

You can add support for any third-party fieldtype by creating a module for it. The example modulethat you can refer to is GraphQLFieldtypeMapMarker that adds support for FieldtypeMapMarkerfieldtype. Below are the basic requirements that this kind of modules should fulfill.

Naming of the Module

Name your module exactly as the Fieldtype module you are adding support for with GraphQL prefix.So for example GraphQLFieldtypeMapMarker adds support for FieldtypeMapMarker.

Required methods

There are three required methods.

public static function getType(Field $field)

The value type that the fieldtype returns. Could be string, number, boolean or an abject with bunchof subfields.

public static function getInputType(Field $field)

The value type that the fieldtype accepts. Could be different value type than it returns. Forinstance FieldtypePage returns a Page object with lots of subfields, but can accept a simple integer (id of the page) as a value.

public static function setValue(Page $page, Field $field, $value)

Given the $page, $field and a $value, the method sets the value to the page's given field.

Note: The GraphQL api is built upon Youshido/GraphQL library. So the methods above shouldbe built using that library. Please see GraphQLFieldtypeMapMarker module for reference.

When your module is ready, just install it and it should be automatically used by ProcessGraphQL andyour fieldtype should be available via your GraphQL api.




No comments yet. Be the first to post!

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.