Gato GraphQL is a tool for interacting with data in your WordPress site. You can think of it as a Swiss Army knife for dealing with data, as it allows to retrieve, manipulate and store again any piece of data, in any desired way, using the GraphQL language.

With Gato GraphQL, you can:

• Query data to create headless sites
• Expose public and private APIs
• Map JS components to Gutenberg blocks
• Synchronize content across sites
• Automate tasks
• Complement WP-CLI to execute admin tasks
• Search/replace content for site migrations
• Send notifications when something happens (new post published, new comment added, etc)
• Interact with cloud services
• Convert the data from a 3rd-party API into the required format
• Translate content in the site
• Update thousands of posts with a single action
• Insert or remove Gutenberg blocks in bulk
• Validate that a new post contains a mandatory block
• And much more...

Check out the Tutorial section in gatographql.com which demonstrates how to implement these use cases using the plugin.

• PHP 8.1
• Lando
• Composer

• XDebug (integrated out of the box when using VSCode and the PHP Debug addon for VSCode)

Follow these steps:

Clone the repo in your local drive:

git clone https://github.com/GatoGraphQL/GatoGraphQL

Run:

$ cd {project folder}
$ cd submodules/GatoGraphQL && composer install && cd ../.. && composer install

A Lando webserver for development is already set-up:

• Runs on PHP 8.1
• It directly uses the source code on the repo
• XDebug is enabled

Follow these steps:

Run (only the first time):

composer build-server

After a few minutes, the website will be available under https://gatographql.lndo.site.

To print the server information, including the port to connect to the MySql database (so you can visualize and edit the data in the DB using an external client, such as MySQLWorkbench), run:

composer server-info

Credentials for https://gatographql.lndo.site/wp-admin/:

• Username: admin
• Password: admin

Click on the Gato GraphQL link on the menu to open the GraphiQL client, and execute the following GraphQL query:

{
  posts {
    id
    title
  }
}

If the installation of the webserver was successful, you will receive a response:

Run:

composer integration-test

Building the webserver (above) is needed only the first time.

From then on, run:

composer init-server

A Lando webserver is set-up and configured to test the released plugins, generated by GitHub Actions.

• Runs on PHP 7.2
• You must download the generated plugins for PROD (from GitHub Actions) and install them on the webserver
• XDebug is not enabled

Follow these steps:

Run (only the first time):

composer build-server-prod

After a few minutes, the website will be available under https://gatographql-for-prod.lndo.site.

(The URL is the same one as for DEV above, plus appending -for-prod to the domain name.)

To print the server information, run:

composer server-info-prod

The wp-admin login credentials are the same ones as for DEV.

Building the webserver (above) is needed only the first time.

From then on, run:

composer init-server-prod

You can at any moment re-install the WordPress site (and import the initial dataset).

On the DEV webserver:

composer reset-db

On PROD:

composer reset-db-prod

This is useful when:

• The installation when doing build-server was halted midway (or failed for some reason)
• Running the integration tests was not completed (modifying the DB data to a different state, so that running the tests again will fail)

When a plugin or package folder has been renamed, you need to update the path in the overrides section of the .lando.upstream.yml Lando config file, and then rebuild the Lando webserver to reflect these changes.

Run:

composer rebuild-server

When a new plugin is added to the monorepo, it must have its Composer autoload file generated, and the plugin must be symlinked to the Lando webserver.

Run:

composer rebuild-app-and-server

(This is done by the admin of the repo.)

The monorepo includes scripts that completely automate the process of releasing the plugins in the monorepo.

Follow these steps:

Choose which version you will be releasing. The same version will be applied to all plugins in the monorepo.

(Given that the current version is 0.0.0...)

To release version 0.0.1, run:

composer release-patch

To release version 0.1.0, run:

composer release-minor

To release version 1.0.0, run:

composer release-major

To preview running the command without actually executing it, append -- --dry-run:

composer release-patch -- --dry-run

After tagging the repo on the step above, we must create a release from the tag to generate the extension plugins for production.

To create the release, we must head over to the tags page in the GitHub repo, and click on the new tag (eg: 0.1.0).

Then, on the tag page, click on Create release from tag.

This will trigger the generate_plugins.yml workflow, which will generate the extension plugins and attach them as assets to the tag page.

For instance, after tagging Gato GraphQL with 1.0.9, the tag page GatoGraphQL/GatoGraphQL/releases/tag/1.0.9 had the following assets attached to it:

• gatographql-1.0.9.zip
• gatographql-testing-1.0.9.zip
• gatographql-testing-schema-1.0.9.zip

Once the extension plugin has been generated, install it on the PROD webserver to test it, whether manually or using WP-CLI.

Using WP-CLI, to test the released version 0.1.0, run:

$ cd webservers/gatographql-for-prod
$ lando wp plugin install https://github.com/GatoGraphQL/GatoGraphQL/releases/latest/download/gatographql-0.1.0.zip --force --activate
$ cd ../..

Once you've installed the release on the Lando webserver for PROD, log-in to the wp-admin, access the GraphiQL client, and execute the following GraphQL query:

{
  posts {
    id
    title
  }
}

If the installation of the webserver was successful, you will receive a response:

Run:

composer integration-test-prod

When developing the plugin and testing it in the DEV webserver, whenever we create a new PHP service or modify the signature of an existing one (such as the PHP classname), we need to purge the container cache.

Run:

composer purge-cache

After adding a plugin or package to the monorepo, the configuration (containing all the packages) must be regenerated.

Run:

composer update-monorepo-config

Access the error logs from the Lando webserver:

composer log-server-errors

For PROD:

composer log-server-errors-prod

SSH into the Lando webserver:

composer ssh-server

For PROD:

composer ssh-server-prod

XDebug is already integrated when using VSCode.

Add a breakpoint in the source code and then, in the Run and Debug tab, press on Start Debugging with the corresponding configuration (defined in .vscode/launch.json):

• [Lando webserver] Listen for Xdebug: For debugging the source code while running the Lando webserver for DEV
• [PHPUnit] Listen for Xdebug: For debugging PHPUnit tests

XDebug is enabled but inactive; it must be activated when requesting the webpage (see below).

Activate XDebug for a request by appending parameter ?XDEBUG_TRIGGER=1 to the URL (for any page on the Gato GraphQL plugin, including any page in the wp-admin, the GraphiQL or Interactive Schema public clients, or other).

For instance:

• https://gatographql.lndo.site/wp-admin/edit.php?page=gatographql&action=execute_query&XDEBUG_TRIGGER=1
• https://gatographql.lndo.site/graphiql/?XDEBUG_TRIGGER=1

Activate XDebug by prepending XDEBUG_TRIGGER=1 before the phpunit command to run the unit tests.

For instance:

XDEBUG_TRIGGER=1 vendor/bin/phpunit layers/GatoGraphQLForWP/phpunit-packages/gatographql/tests/Unit/Faker/WPFakerFixtureQueryExecutionGraphQLServerTest.php

Retrieve the list of all Composer commands available in the monorepo:

composer list

Create an extension for Gato GraphQL using GatoGraphQL/ExtensionStarter.

Check the list of Supported PHP features.

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.

GatoGraphQL/GatoGraphQL is a monorepo containing the several layers required for Gato GraphQL. Check Monorepo_README.md for documentation of the different projects.

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

• 2.2 (current)
• 2.1
• 2.0
• 1.5
• 1.4
• 1.3
• 1.2
• 1.1
• 1.0
• 0.10
• 0.9
• 0.8
• 0.7
• 0.6

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

To execute PHPUnit, run:

composer test

To execute PHPStan, run:

composer analyse

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

composer preview-code-downgrade

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

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

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

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

• Leonardo Losoviz

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