# Installing on WordPress

# Via the "Gato GraphQL" plugin

Gato GraphQL is the implementation for WordPress of GraphQL by PoP.

# Requirements

WordPress 5.4 or above, PHP 7.1 or above.

# Install

Download the plugin.

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

After installed, there will be a new "GraphQL API" section on the menu:

The interactive schema visualizer

# Via Composer

Installing via Composer enables to select exactly the required packages.

Please make sure to have Composer installed, and file composer.json in the root of your project. If you do not have this file, run this command to create it:

composer init -n

Then complete the following steps.

Make sure your composer.json file has the entries below to accept minimum stability "dev":

{
    "minimum-stability": "dev",
    "prefer-stable": true
}

Add the required packages entry the require section of your composer.json file:

{
    "require": {
        "pop-schema/custompostmeta-wp": "dev-master",
        "pop-schema/posts-wp": "dev-master",
        "pop-schema/pages-wp": "dev-master",
        "pop-schema/usermeta-wp": "dev-master",
        "pop-schema/commentmeta-wp": "dev-master",
        "pop-schema/taxonomyquery-wp": "dev-master",
        "pop-schema/custompostmedia-wp": "dev-master",
        "graphql-by-pop/graphql-server": "dev-master",
        "graphql-by-pop/graphql-endpoint-for-wp": "dev-master",
        "getpop/engine-wp-bootloader": "dev-master",
        "composer/installers": "~1.0"
    }
}

What are these packages?

From owner "getpop", only packages "getpop/graphql" and "getpop/engine-wp-bootloader" are mandatory. The other ones are required to load data from posts, pages, users, comments, taxonomies and media, and to set-up the API endpoint permalink.

Package "composer/installers" is required to set-up some required must-use plugins.

Add the following "installer-paths" under the extra section of your composer.json file:

{
    "extra": {
        "installer-paths": {
            "wp-content/mu-plugins/{$name}": [
                "type:wordpress-muplugin"
            ]
        }
    }
}

WARNING

If your mu-plugins are installed under a different folder, please change this configuration accordingly.

Download and install the packages in your project:

composer update

WARNING

After this step, there should be file a mu-require.php under the wp-content/mu-plugins folder. If for some reason it is not there, run composer update again.

Load Composer and initialize the Component class for all the required packages, by adding code like this one at the beginning of file wp-config.php:

// Load Composer’s autoloader
require_once (__DIR__.'/vendor/autoload.php');

// Initialize all PoP components
\PoP\Engine\ComponentLoader::initializeComponents([
    \PoPSchema\CommentMetaWP\Component::class,
    \PoPSchema\PostsWP\Component::class,
    \PoPSchema\PagesWP\Component::class,
    \PoPSchema\CustomPostMetaWP\Component::class,
    \PoPSchema\CustomPostMediaWP\Component::class,
    \PoPSchema\TaxonomyQueryWP\Component::class,
    \PoPSchema\UserMetaWP\Component::class,
    \GraphQLByPoP\GraphQLServer\Component::class,
    \GraphQLByPoP\GraphQLEndpointForWP\Component::class,
]);

In the WordPress admin, flush the re-write rules to enable the API endpoint:

Go to Settings => Permalinks
Click on the "Save Changes" button (no need to modify any input)

Check that the GraphQL API works by executing a query against endpoint /api/graphql. Assuming that your site is installed under http://localhost, execute in terminal:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{ "query": "{ posts { title } }" }' \
  http://localhost/api/graphql/

The (formatted) response should be something like this:

{
    "data": {
        "posts": [
            {
                "title":"Hello world!"
            }
        ]
    }
}

Celebrate! 🥳🕺🏻💃🏼🙌

# Optionals

To accept external API queries, add the snippet below in file .htaccess:

<IfModule mod_rewrite.c>
# Enable the server to accept external API queries
Header set Access-Control-Allow-Methods "OPTIONS, GET, POST"
Header set Access-Control-Allow-Headers "origin, content-type"
Header set Access-Control-Allow-Origin "*"
</IfModule>

Set-up the API endpoint through the .htaccess file

Instead of defining the API endpoint by code through dependency "getpop/graphql-endpoint-for-wp" (and having to flush the rewrite rules), it can also be set-up with a rewrite rule in the .htaccess file. For this, remove that dependency from composer, and add the code below before the WordPress rewrite section (which starts with # BEGIN WordPress):

<IfModule mod_rewrite.c>
# Rewrite from api/graphql/ to /?scheme=api&datastructure=graphql
RewriteEngine On
RewriteBase /
RewriteCond %{SCRIPT_FILENAME} !-d
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteRule ^api/graphql/?$ /?scheme=api&datastructure=graphql [L,P,QSA]
</IfModule>

# Scaffold a new WordPress site with the API installed, via Composer and WP-CLI

Follow the instructions under project Bootstrap a PoP API for WordPress.

← Intro Novel GraphQL features →