GraphQL API for WordPress

Transform your WordPress site into a modern GraphQL server: graphql-api.com.

This plugin is the implementation for WordPress of GraphQL by PoP, a CMS-agnostic GraphQL server in PHP.

Requirements

• WordPress 5.4 or above
• PHP 8.0+ for development
• PHP 7.1+ for production

Install

Ready for production?

This plugin requires 3rd party dependencies, but they have not been scoped yet (see issue #9). So please install this plugin in a development environment first, to make sure there are no conflicts with the other plugins installed in the site.

Upload

Download the latest release of the plugin as a .zip file.

Then, in the WordPress admin:

• Go to Plugins => Add New
• Click on Upload Plugin
• Select the .zip file
• Click on Install Now (it may take a few minutes)
• Once installed, click on Activate

Timeout in Nginx?

Nginx has a time limit to process the response from the PHP backend, and installing large WordPress plugins may exceed the default time limit.

If when installing the plugin you get a "504 Gateway Timeout" error, or an entry "upstream timed out (110: Connection timed out) while reading upstream" in the log, increase the timeout to 300 seconds in the Nginx config, as explained here.

Composer

Add the following configuration to your composer.json:

{
    "require": {
        "graphql-api/graphql-api-for-wp": "^0.7.13"
    },
    "minimum-stability": "dev",
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "graphql-api/graphql-api-for-wp",
                "type": "wordpress-plugin",
                "version": "0.7.13",
                "dist": {
                    "url": "https://github.com/leoloso/PoP/releases/latest/download/graphql-api.zip",
                    "type": "zip"
                },
                "require": {
                    "composer/installers": "^1"
                }
            }
        }
    ],
    "extra": {
        "installer-paths": {
            "wp-content/plugins/{$name}/": [
                "type:wordpress-plugin"
            ]
        }
    }
}

WP-CLI

To install via WP-CLI, execute this command:

wp plugin install --activate https://github.com/leoloso/PoP/releases/latest/download/graphql-api.zip

GitHub Updater

This plugin support automatic updating via the GitHub Updater.

Development

The source code is hosted on the PoP monorepo, under GraphQLAPIForWP/plugins/graphql-api-for-wp.

To set it up:

1. Clone the monorepo:

git clone https://github.com/leoloso/PoP.git && cd PoP

2. Install Composer dependencies:

cd layers/GraphQLAPIForWP/plugins/graphql-api-for-wp && composer install

Using Lando

Launch a development server, with WordPress installed and the GraphQL API plugin activated, through Lando.

Please make sure you have Lando installed, with version 3.0.26 or upwards (or install it from here).

The first time, to install the server, execute:

composer build-server

From then on, to start the server, execute:

composer start-server

The site will be available under http://graphql-api-dev.lndo.site.

To access the wp-admin:

• User: admin
• Password: admin

Enable XDebug

To enable debugging, create Lando config file .lando.local.yml with this content:

config:
  xdebug: true

And then rebuild the server:

composer rebuild-server

Gutenberg JS builds

Compiled JavaScript code (such as all files under a block's build/ folder) is added to the repo, but only as compiled for production, i.e. after running npm run build.

Code compiled for development, i.e. after running npm start, cannot be commited/pushed to the repo.

PHP versions

Requirements:

• PHP 8.0+ for development
• PHP 7.1+ for production (through release graphql-api.zip)

Supported PHP features

Check the list of Supported PHP features in leoloso/PoP

Modules

GraphQL API is extensible, and ships with the following modules (organized by category):

Resources

Videos

The following videos demonstrate several features:

• Persisted queries
• Custom endpoints
• Access control
• Public/private API
• HTTP caching
• Field deprecation
• Query inheritance

WordPress Philosophy

Detailed explanation of the plugin goals, and how it renders the WordPress philosophy:

1. Rendering the WordPress philosophy in GraphQL

PHP Architecture

Articles explaining how the plugin is coded using PHP 8.0 but can run on PHP 7.1:

1. Transpiling PHP code from 8.0 to 7.x via Rector
2. Coding in PHP 7.4 and deploying to 7.1 via Rector and GitHub Actions

GraphQL by PoP documentation

GraphQL API for WordPress is powered by the CMS-agnostic GraphQL server GraphQL by PoP.

For technical information on how it works, check out its documentation.

These articles explain the concepts, design and implementation of GraphQL by PoP:

1. Designing a GraphQL server for optimal performance
2. Simplifying the GraphQL data model
3. Schema-first vs code-first development in GraphQL
4. Speeding-up changes to the GraphQL schema
5. Versioning fields in GraphQL
6. GraphQL directives are underrated
7. Treating GraphQL directives as middleware
8. Creating an @export GraphQL directive
9. Adding directives to the schema in code-first GraphQL servers
10. Coding a GraphQL server in JavaScript vs. WordPress
11. Supporting opt-in nested mutations in GraphQL

Gutenberg

These articles explain the integration with Gutenberg (the WordPress editor).

1. Adding a Custom Welcome Guide to the WordPress Block Editor
2. Using Markdown and Localization in the WordPress Block Editor

Feature Roadmap

• Baseline features
• Sponsored features

Sponsorship

Ongoing development for this project is funded via Leonardo Losoviz's GitHub sponsors:

Become a sponsor to Leonardo Losoviz ❤️

Standards

PSR-1, PSR-4 and PSR-12.

To check the coding standards via PHP CodeSniffer, run:

composer check-style

To automatically fix issues, run:

composer fix-style

Release notes

• 0.8 (upcoming)
• 0.7
• 0.6

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

To execute PHPUnit, run:

composer test

Static Analysis

To execute PHPStan, run:

composer analyse

Downgrading code

To visualize how Rector will downgrade the code to PHP 7.1:

composer preview-code-downgrade

Report issues

To report a bug or request a new feature please do it on the PoP monorepo issue tracker.

Contributing

We welcome contributions for this package on the PoP monorepo (where the source code for this package is hosted).

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Leonardo Losoviz

License

GPLv2 or later. Please see License File for more information.