Gato GraphQL - Extension Starter

Gato GraphQL extensions add functionality and expand the GraphQL schema provided by Gato GraphQL.

This template repository helps you kickstart a GitHub repo, to develop, test and release your own extensions for Gato GraphQL.

Trivia fact 🤔

All extensions from gatographql.com/extensions are hosted on a monorepo created from GatoGraphQL/ExtensionStarter 🚀

Requirements

• PHP 8.1
• Lando
• Composer

Recommended to use

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

Create your Extension Project

Follow these steps:

Create your repo from this GitHub template

• Click on Use this template → Create a new repository
• Select the GitHub owner, and choose a proper name for your repository (eg: my-account/GatoGraphQLExtensionsForMyCompany)
• Choose if to make it Public or Private
• Click on Create repository

As a result, a copy of this template will have been created under your GitHub repo:

Clone your repo locally

Clone your repository in your local drive using the --recursive option (needed to clone Git submodule GatoGraphQL/GatoGraphQL):

git clone --recursive https://github.com/my-account/GatoGraphQLExtensionsForMyCompany

Install Composer dependencies

Step on the project's folder:

cd {project folder}

And then run:

cd submodules/GatoGraphQL && composer install && cd ../.. && composer install

Initialize the Project

This step will replace all the initial placeholder strings in the extension starter with the values corresponding to your project.

Input your values in the command below and run:

composer initialize-project -- \
  --php-namespace-owner=MyCompanyName \
  --my-company-name="My Company Name" \
  [email protected] \
  --my-company-website=https://www.mycompany.com

These arguments (and additional ones, see below) are optional. If any of them is not provided, a default value is computed from the configuration in Git and the GitHub repo.

Print arguments and default values for initialize-project

To see the default values for the arguments, run:

composer initialize-project -- --dry-run

To print all the arguments for the initialize-project command, run:

composer initialize-project -- --help

View all initialize-project command arguments

Option	Description
--git-base-branch	Base branch of the GitHub repository where this project is hosted. If not provided, this value is retrieved using git
--git-user-name	Git user name, to "split" code and push it to a different repo when merging a PR. If not provided, this value is retrieved from the global git config
--git-user-email	Git user email, to "split" code and push it to a different repo when merging a PR. If not provided, this value is retrieved from the global git config
--github-repo-owner	Owner of the GitHub repository where this project is hosted (eg: "GatoGraphQL" in "https://github.com/GatoGraphQL/ExtensionStarter"). If not provided, this value is retrieved using git
--github-repo-name	Name of the GitHub repository where this project is hosted (eg: "ExtensionStarter" in "https://github.com/GatoGraphQL/ExtensionStarter"). If not provided, this value is retrieved using git
--docs-git-base-branch	Base branch of the (public) GitHub repository hosting the documentation for the extension, to access the images in PROD. If not provided, the value for option git-base-branch is used
--docs-github-repo-owner	Owner of the (public) GitHub repository hosting the documentation for the extension, to access the images in PROD. If not provided, the value for option github-repo-owner is used
--docs-github-repo-name	Name of the (public) GitHub repository hosting the documentation for the extension, to access the images in PROD. If not provided, the value for option github-repo-name is used
--php-namespace-owner	PHP namespace owner to use in the codebase (eg: "MyCompanyName"). If not provided, the value from the "github-repo-owner" option is used
--composer-vendor	Composer vendor to distribute the packages in the repo. If not provided, it is generated from the "php-namespace-owner" option
--my-company-name	Name of the person or company owning the extension. If not provided, the value for option git-user-name is used
--my-company-email	Email of the person or company owning the extension. If not provided, the value for option git-user-email is used
--my-company-website	Website of the person or company owning the extension. If not provided, the GitHub repo for this project is used

Browse documentation within the codebase

The codebase contains snippets of documentation, to explain some feature or configuration.

Search for the following PHPDoc tags in the codebase:

• @gatographql-project-info: Information on some aspect of the monorepo setup
• @gatographql-project-action-maybe-required: Indicates if some feature can be enabled/disabled and how
• @gatographql-extension-info: Information on some aspect of the extension setup
• @gatographql-example: Provides an example from the upstream monorepo
• @gatographql-readonly-code: Indicates that the code must not be changed, as it is automatically modified via some script

Review the License

The license in the monorepo is GPL v2.

If this this not your license, remove/replace this file.

Commit, Push and Tag the Initial Project

Run:

git add . && git commit -m "Initialized project" && git push origin && git tag 0.0.0 && git push --tags

This will commit the codebase to your GitHub repo, and tag it with version 0.0.0. (This tag is needed to start incrementing the version automatically from now on.)

Run the webserver for DEV

(Instructions for running the webserver for PROD will be given further below.)

A Lando webserver is set-up and configured to develop the extensions in the monorepo.

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

Follow these steps:

Build the Lando webserver for DEV

Run (only the first time):

composer build-server

After a few minutes, the website will be available under https://gatographql-{composer-vendor}-extensions.lndo.site.

(Or, if you have Lando's proxy disabled, it will be available under https://localhost:{randomPort}.)

The URL is printed on the console under APPSERVER URLS (you will need to scroll up):

To print the URL again, run:

composer server-info

(This command also prints other useful data, 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.)

What plugins are installed in the webserver? 🤔

All plugins hosted on the "upstream" monorepo:

• Gato GraphQL
• Gato GraphQL - Testing
• Gato GraphQL - Testing Schema

(The last two are utilities to run integration tests for Gato GraphQL. Among others, they provide CPT "dummy-cpt" and custom taxonomies "dummy-category" and "dummy-tag").

All plugins hosted on this "downstream" starter monorepo:

• Gato GraphQL - Hello Dolly

All the WordPress integration plugins, required by the extensions

• Hello Dolly

Besides, some initial configuration is applied to the Gato GraphQL plugin Settings. For instance, the single endpoint is enabled (it is disabled by default).

Log-in to the wp-admin

Credentials for https://gatographql-{composer-vendor}-extensions.lndo.site/wp-admin/:

• Username: admin
• Password: admin

Open the Gato GraphQL plugin in the wp-admin

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

{
  helloDolly
}

Where does field helloDolly come from? 🤔

Field Root.helloDolly is added to the GraphQL schema by the "Gato GraphQL - Hello Dolly" demo extension hosted in this monorepo.

This field returns any quote from the Hello Dolly song. The following query:

{
  helloDolly
}

will return:

{
  "data": {
    "helloDolly": "Dolly, never go away again"
  }
}

...or any of the other lines in that song.

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

Start the Lando webserver for DEV

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

From then on, run:

composer init-server

Run Integration Tests for DEV

Run:

composer integration-test

Create an Extension Plugin

This section explains all the steps needed to add an extension plugin to the monorepo.

Run command to create the extension

Run:

composer create-extension -- \
  --extension-name="Extension name"

If the extension is an integration for some WordPress plugin, run:

composer create-extension -- \
  --integration-plugin-name="Plugin name" \
  --integration-plugin-file=slug/file.php \
  --integration-plugin-version-constraint="..."

For instance, to build an integration for WooCommerce with version 8 or above, run:

composer create-extension -- \
  --integration-plugin-name=WooCommerce \
  --integration-plugin-file=woocommerce/woocommerce.php \
  --integration-plugin-version-constraint="^8"

Print arguments for create-extension

To print all the arguments for the create-extension command, run:

composer create-extension -- --help

View all create-extension command arguments

Option	Description
--template	Template to use to create the extension plugin, from available options: "basic" [default: "basic"]
--integration-plugin-file	Integration plugin file (eg: "woocommerce/woocommerce.php" for the WooCommerce plugin), if any
--integration-plugin-version-constraint	Minimum required version of the integration plugin, in semver (eg: "^8.1"). If not provided, any version is accepted [default: "*"]
--integration-plugin-name	Name of the integration plugin (eg: WooCommerce). If not provided, it is generated from the integration plugin slug
--extension-name	Extension plugin name. If not provided, it is calculated from the integration plugin name
--extension-slug	Slug of the extension plugin. If not provided, it is generated from the integration plugin's slug, or from the "extension-name" option
--extension-classname	PHP classname to append to classes in the extension plugin. If not provided, it is generated from the "extension-slug" option

Commit + Rebuild Lando webservers

After running the command above, execute the following bash commands to complete the process:

# (Git commit/push the changes to the repo)
git add . && git commit -m "Created new extension" && git push origin

# (Rebuild the Lando webserver for DEV)
composer rebuild-app-and-server

# (Install/activate the added plugins on the DEV webserver)
composer activate-extension-plugins

# (Install/activate the integration plugin on the PROD webserver) <= if already created
composer activate-extension-plugins-prod

Complete the Extension Plugin

The new extension plugin created with the command above contains the comment @gatographql-extension-todo indicating that there are items to complete.

Documentation

Complete the documentation for your module, under file:

layers/GatoGraphQLForWP/plugins/{extension-slug}/docs/modules/schema-{extension-slug}/en.md.

Integration Tests for the Extension Schema

To test the schema elements added by the extension, complete the GraphQL document:

layers/GatoGraphQLForWP/plugins/{extension-slug}/tests/Integration/fixture-schema/extension-schema.gql

(and the JSON response, in the same folder).

Stubs for your integration plugin

If integrating with another WordPress plugin, you will need to complete the file with stubs for that plugin (to avoid errors with PHPStan/Rector), under:

stubs/wpackagist-plugin/{integration-plugin}/stubs.php.

What are stubs needed for? And how to generate them? 🤔

Stubs are placeholders to "load" a functionality that is otherwise missing (because the plugin that contains it is not loaded when running unit tests and static analysis).

Stubs avoid PHPStan producing an error when analyzing packages which invoke classes, methods, constants, etc, from 3rd-party WordPress plugins. (Eg: the stubs file for hello-dolly avoids an error from calling hello_dolly_get_lyric() in the field resolver).

It also avoids Rector from producing errors when downgrading the code.

Stubs must be added for all the WordPress integration plugins for which there is an extension in the monorepo (eg: WooCommerce, Yoast SEO, etc).

The stub files, if not already available for that WordPress plugin, can be generated using php-stubs/generator (check also php-stubs/wordpress-stubs).

Extending the GraphQL Schema

This section provides examples from the codebase in the upstream GatoGraphQL/GatoGraphQL monorepo, demonstrating how to create the resolvers to extend the GraphQL schema (for fields, mutations, input objects, directives, etc).

In your code editor, copy the example file and paste it inside your extension folder (under the original folder structure), and adapt it to your needs:

• Adapt its content accordingly
• Inspect all services referenced inside the class, and verify if any of them must too be duplicated and adapted
• Similarly, find all references to the original class (eg: using the PHP Intelephense addon for VSCode), and verify if any of them must also be duplicated and adapted

You must also define those services in the service container, by uncommenting the corresponding entries on configuration file layers/GatoGraphQLForWP/packages/{extension-slug}-schema/config/schema-services.yaml.

(Check submodules/GatoGraphQL/layers/CMSSchema/packages/users/config/schema-services.yaml for an example.)

Type Resolver

(From this section downwards, these features are general to GraphQL.)

User type:

submodules/GatoGraphQL/layers/CMSSchema/packages/users/src/TypeResolvers/ObjectType/UserObjectTypeResolver.php

Field Resolver

Fields name, displayName, and others, for the User type:

submodules/GatoGraphQL/layers/CMSSchema/packages/users/src/FieldResolvers/ObjectType/UserObjectTypeFieldResolver.php

Mutation Resolver

Mutation createPost:

submodules/GatoGraphQL/layers/CMSSchema/packages/post-mutations/src/FieldResolvers/ObjectType/RootObjectTypeFieldResolver.php

Custom Scalar Resolver

Custom scalar Email:

submodules/GatoGraphQL/layers/Schema/packages/schema-commons/src/TypeResolvers/ScalarType/EmailScalarTypeResolver.php

Enum Resolver

Enum CommentTypeEnum:

submodules/GatoGraphQL/layers/CMSSchema/packages/comments/src/TypeResolvers/EnumType/CommentTypeEnumTypeResolver.php

Interface Resolver

Interface CustomPostInterfaceTypeResolver:

submodules/GatoGraphQL/layers/CMSSchema/packages/customposts/src/TypeResolvers/InterfaceType/CustomPostInterfaceTypeResolver.php

Union Type-Resolver

Union type CustomPostUnionTypeResolver:

submodules/GatoGraphQL/layers/CMSSchema/packages/customposts/src/TypeResolvers/UnionType/CustomPostUnionTypeResolver.php

Input Object Resolver

Input Object UserSortInput:

submodules/GatoGraphQL/layers/CMSSchema/packages/users/src/TypeResolvers/InputObjectType/UserSortInputObjectTypeResolver.php

Oneof Input Object Resolver

Oneof Input Object UserByInput:

submodules/GatoGraphQL/layers/CMSSchema/packages/users/src/TypeResolvers/InputObjectType/UserByOneofInputObjectTypeResolver.php

Directive Resolver

Directive @skip:

submodules/GatoGraphQL/layers/Engine/packages/engine/src/DirectiveResolvers/SkipFieldDirectiveResolver.php

Global Field Resolver

(From this section downwards, these features are specific to Gato GraphQL.)

Field __typename:

submodules/GatoGraphQL/layers/GraphQLByPoP/packages/graphql-server/src/FieldResolvers/ObjectType/GlobalObjectTypeFieldResolver.php

Enum String Resolver

Enum String CustomPostEnumString:

submodules/GatoGraphQL/layers/CMSSchema/packages/customposts/src/TypeResolvers/EnumType/CustomPostEnumStringScalarTypeResolver.php

Error Payload Union Type Resolver

Error Payload Union Type RootAddCommentToCustomPostMutationErrorPayloadUnion:

submodules/GatoGraphQL/layers/CMSSchema/packages/comment-mutations/src/TypeResolvers/UnionType/RootAddCommentToCustomPostMutationErrorPayloadUnionTypeResolver.php

Adding Nested Mutations

Mutation Post.update:

submodules/GatoGraphQL/layers/CMSSchema/packages/post-mutations/src/FieldResolvers/ObjectType/PostObjectTypeFieldResolver.php

Field Arguments to filter data

Field Root.comments:

submodules/GatoGraphQL/layers/CMSSchema/packages/comments/src/FieldResolvers/ObjectType/RootObjectTypeFieldResolver.php

Custom Post Type - Type Resolver

(From this section downwards, these features are specific to WordPress.)

Custom Post Type Page:

submodules/GatoGraphQL/layers/CMSSchema/packages/pages/src/TypeResolvers/ObjectType/PageObjectTypeResolver.php

Custom Post Type - Field Resolver

Field CustomPost.author:

submodules/GatoGraphQL/layers/CMSSchema/packages/users/src/ConditionalOnModule/CustomPosts/FieldResolvers/ObjectType/CustomPostObjectTypeFieldResolver.php

Release your extension plugins for PROD

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

Follow these steps:

Set the "Workflow permissions" to "Read and write" in your repo settings

(This is done only the first time, after creating the repo)

On your repo's "Settings > Actions > General > Workflow permissions", select option Read and write permissions.

This will enable uploading the generated artifacts when creating a new release.

Tag the monorepo as patch, minor or major

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

What do these commands do? 🤔

Executing these commands will first prepare the repo for PROD:

• Update the version (in the plugin file's header, readme.txt's Stable tag, others) for all the extension plugins in the monorepo
• Update the documentation image URLs to point to that tag, under raw.githubusercontent.com
• Commit and push
• Git tag with the version, and push tag to GitHub

And then, it will prepare the repo for DEV again:

• Update the version to the next DEV version (next semver + -dev)
• Commit and push

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

composer release-patch -- --dry-run

Create release from tag in GitHub

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, head over to the tags page in your GitHub repo (https://github.com/my-account/GatoGraphQLExtensionsForMyCompany/tags), and click on the new tag (eg: 0.1.0).

Then, on the tag page, click on Create release from tag, and then add a title and content, and submit the form.

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

Install the extension in the PROD webserver

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, if your repo is my-account/GatoGraphQLExtensionsForMyCompany and you have released version 0.1.0, run:

$ cd webservers/gatographql-extensions-for-prod
$ lando wp plugin install https://github.com/my-account/GatoGraphQLExtensionsForMyCompany/releases/latest/download/gatographql-hello-dolly-0.1.0.zip --force --activate
$ cd ../..

Query the extension in the wp-admin

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:

{
  helloDolly
}

If the release was generated successfully, you will receive a response:

Run the webserver for PROD

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

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

Follow these steps:

Build the Lando webserver for PROD

Run (only the first time):

composer build-server-prod

After a few minutes, the website will be available under https://gatographql-{composer-vendor}-extensions-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 URL again, run:

composer server-info-prod

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

Start the Lando webserver for PROD

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

From then on, run:

composer init-server-prod

Run Integration Tests for PROD

Run:

composer integration-test-prod

Development Tips

Purging the cache

When developing an extension 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

How does Gato GraphQL use a service container? 🤔

The Gato GraphQL plugin uses a service container (via the Symfony DependencyInjection library), to manage all services in PHP.

Services are PHP classes, and must be defined in configuration files services.yaml and schema-services.yaml to be injected into the container.

The first time the application is invoked, the container gathers all injected services and compiles them, generating a single PHP file that is loaded in the application.

Generating this file can take several seconds. To avoid waiting for this time on each request, the Gato GraphQL plugin caches this file after it has been generated the first time.

The container needs to be purged whenever a service is created, or an existing one updated or removed.

(In production, the Gato GraphQL plugin purges the cache whenever a new extension plugin is activated, or when the plugin Settings are updated. During development, it can in addition be triggered manually, by running composer purge-cache.)

This applies to resolvers (type resolvers, field resolvers, directive resolvers, and any other resolver that gives shape to the GraphQL schema), as these are PHP services. Whenever a resolver is added or removed, or is updated in such a way that modifies the GraphQL schema, the cached container must be purged.

Some example resolvers are:

• String type: StringScalarTypeResolver
• Field User.name (and others): UserObjectTypeFieldResolver
• @skip directive: SkipFieldDirectiveResolver

Regenerating the monorepo configuration

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

Run:

composer update-monorepo-config

What does command update-monorepo-config do? 🤔

The update-monorepo-config command will:

• Regenerate the root composer.json, adding the new packages
• Regenerate the root phpstan.neon, adding the new packages

Re-install the WordPress site (DEV and 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)

Re-build the Lando webserver for DEV

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

Regenerate the Composer autoload files for DEV

When a new extension 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

Development Tools

Error logs

Access the error logs from the Lando webserver:

composer log-server-errors

For PROD:

composer log-server-errors-prod

SSH

SSH into the Lando webserver:

composer ssh-server

For PROD:

composer ssh-server-prod

Debugging

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).

Debugging in the Lando webserver for DEV

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-{composer-vendor}-extensions.lndo.site/wp-admin/edit.php?page=gatographql&action=execute_query&XDEBUG_TRIGGER=1
• https://gatographql-{composer-vendor}-extensions.lndo.site/graphiql/?XDEBUG_TRIGGER=1

Debugging PHPUnit tests

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

For instance:

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

Continuous Integration

Executing Integration Tests against InstaWP

When a PR is merged, all extension plugins in the monorepo are generated for DEV, and attached to workflow generate_plugins.yml (in its Summary tab).

Then, workflow integration_tests.yml is triggered. This workflow installs the generated plugins in an InstaWP instance, and executes the integration tests against this instance.

To use it, you need to:

• Expose the artifacts in your repo via nightly.link (so these can be installed by InstaWP without being logged-in using a GitHub account)
• Have an account on InstaWP with access to SSH + WP-CLI
• Prepare a template in InstaWP, and import the needed dataset to run the tests, via WP-CLI
• Provide the template slug and repo ID from InstaWP via file InstaWPConfigDataSource.php

To import the dataset, you must run the following bash scripts in your InstaWP instance:

• setup/setup.sh
• setup-extensions/setup.sh

Disable unneeded workflows

Review the GitHub Actions workflows that you need for your project.

Most likely, the following GitHub Actions workflows are not initially needed:

• integration_tests.yml: You first need to have InstaWP and configure the template accordingly
• scoping_tests.yml: Initially there are no packages to scope in the starter
• split_monorepo_tagged.yml: The "Monorepo Split" is not enabled by default (see section Monorepo Split below)
• split_monorepo.yml: Same as above

If this is the case, you can disable these workflows so they don't run unnecessarily.

Multi-Monorepo (Architecture of the Extension Starter)

GatoGraphQL/ExtensionStarter is multi-monorepo. To learn about the features provided by this architecture, visit Multi-Monorepo (Architecture of the Extension Starter).

Multi-Monorepo Tools

Synchronizing files from the upstream Gato GraphQL repo

Run:

composer copy-upstream-files

What files does copy-upstream-files copy? 🤔

Executing composer copy-upstream-files will copy files from the "upstream" GatoGraphQL/GatoGraphQL repo (which is a Git submodule), to the "downstream" my-account/GatoGraphQLExtensionsForMyCompany repo.

These files include GitHub Actions workflows and Lando config files.

For instance, the Lando webserver for DEV uses the source code files from the main Gato GraphQL plugin, via the mapping defined in the upstream file .lando.upstream.yml.

Whenever that file is updated in the Gato GraphQL repo, by executing composer copy-upstream-files we will fetch that updated file and copy it as the downstream .lando.base.yml file (it is renamed in the process, and the paths are adapted to point to submodules/GatoGraphQL/...).

Then we execute composer rebuild-server, and the new mapping will take effect.

Monorepo Commands

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

composer list

View all monorepo commands

composer command	Description
activate-extension-plugins	Download/activate the extension plugins, and any required integration plugin
activate-extension-plugins-prod	Download/activate the extension plugins, and any required integration plugin, in the PROD server
analyse	Run PHPStan static analysis of the code
build-js	Build all JS packages, blocks and editor scripts for all plugins in the Gato GraphQL - Extension Starter repo
build-server	Initialize the Lando webserver with the 'Gato GraphQL' demo site, for development. To be executed only the first time
build-server-prod	Initialize the Lando webserver with the 'Gato GraphQL' demo site, for production. To be executed only the first time
check-style	Validate PSR-12 coding standards (via phpcs)
check-style-wp	Validate WordPress custom rules coding standards (via phpcs)
copy-files-from-upstream-monorepo	[multi-monorepo] Copy specific files to be reused across monorepos, from the upstream GatoGraphQL/GatoGraphQL to this downstream repo
copy-folders-from-upstream-monorepo	[multi-monorepo] Copy all files in specific folders to be reused across monorepos, from the upstream GatoGraphQL/GatoGraphQL to this downstream repo
copy-upstream-files	[multi-monorepo] Copy both specific files, and all files in specific folders, to be reused across monorepos, from the upstream GatoGraphQL/GatoGraphQL to this downstream repo
create-extension	Create an extension plugin, hosted in this monorepo
debug	Run and debug PHPUnit tests
delete-settings	Delete the plugin settings from the DB
deoptimize-autoloader	Removes the optimization of the Composer autoloaders for all the plugins installed in the webserver
destroy-server	Destroy the Lando webserver with the 'Gato GraphQL' demo site
destroy-server-prod	Destroy the Lando webserver with the 'Gato GraphQL' demo site for PROD
disable-caching	Disable caching for the 'Gato GraphQL' in DEV
disable-restrictive-defaults	Do not use restrictive default values for the Settings
enable-caching	Enable caching for the 'Gato GraphQL' in DEV
enable-restrictive-defaults	Use restrictive default values for the Settings
fix-style	Fix PSR-12 coding standards (via phpcbf)
fix-style-wp	Fix WordPress custom rules coding standards (via phpcbf)
import-data	Imports pre-defined data into the DB (posts, users, CPTs, etc)
improve-code-quality	Improve code quality (via Rector)
init-server	Alias of 'start-server
init-server-prod	Runs the init-server-prod script as defined in composer.json
init-server-upstream	Runs the init-server-upstream script as defined in composer.json
initialize-project	Initialize the project, replacing the extension starter data with your own data
install-deps-build-js	Install all dependencies from npm to build the JS packages, blocks and editor scripts for all plugins in the Gato GraphQL - Extension Starter repo
install-site	Installs the WordPress site
install-site-prod	Installs the WordPress site in the PROD server
integration-test	Execute integration tests (PHPUnit)
integration-test-prod	Execute integration tests (PHPUnit) against the PROD webserver
log-server-errors	Show (on real time) the errors from the Lando webserver
log-server-errors-prod	Show (on real time) the errors from the Lando webserver for PROD
log-server-warnings	Show (on real time) the warnings from the Lando webserver
log-server-warnings-prod	Show (on real time) the warnings from the Lando webserver for PROD
merge-monorepo	Create the monorepo's composer.json file, containing all dependencies from all packages
merge-phpstan	Generate a single PHPStan config for the monorepo, invoking the config for the PHPStan config for all packages
preview-code-downgrade	Run Rector in 'dry-run' mode to preview how the all code (i.e. src/ + vendor/ folders) will be downgraded to PHP 7.4
preview-hello-dolly-downgrade	Runs the preview-hello-dolly-downgrade script as defined in composer.json
preview-src-downgrade	Run Rector in 'dry-run' mode to preview how the src/ folder will be downgraded to PHP 7.4
preview-vendor-downgrade	Run Rector in 'dry-run' mode to preview how the vendor/ folder will be downgraded to PHP 7.4
propagate-monorepo	Propagate versions from the monorepo's composer.json file to all packages
purge-cache	Purge the cache for the 'Gato GraphQL' in DEV
purge-cache-upstream	Runs the purge-cache-upstream script as defined in composer.json
rebuild-app-and-server	Update the App dependencies (from Composer) and rebuild the Lando webserver
rebuild-server	Rebuild the Lando webserver
rebuild-server-prod	Rebuild the Lando webserver for PROD
release-major	Release a new 'major' version (MAJOR.xx.xx) (bump version, commit, push, tag, revert to 'dev-master', commit, push)
release-minor	Release a new 'minor' version (xx.MINOR.xx) (bump version, commit, push, tag, revert to 'dev-master', commit, push)
release-patch	Release a new 'patch' version (xx.xx.PATCH) (bump version, commit, push, tag, revert to 'dev-master', commit, push)
remove-unused-imports	Remove unused use imports
reset-db	Resets the WordPress database
reset-db-prod	Resets the WordPress database in the PROD server
server-info	Retrieve information from the Lando webserver
server-info-prod	Retrieve information from the Lando webserver for PROD
ssh-server	SSH into the Lando webserver with the 'Gato GraphQL' demo site
ssh-server-prod	SSH into the Lando webserver for PROD with the 'Gato GraphQL' demo site
start-server	Start the Lando webserver with the 'Gato GraphQL' demo site, for development
start-server-prod	Start the Lando webserver for PROD with the 'Gato GraphQL' demo site, for development
stop-server	Stop the Lando webserver
stop-server-prod	Stop the Lando webserver for PROD
stop-server-upstream	Runs the stop-server-upstream script as defined in composer.json
stopping-integration-test	Runs the stopping-integration-test script as defined in composer.json
stopping-integration-test-prod	Execute integration tests (PHPUnit) against the PROD webserver, stopping as soon as there's an error or failure
stopping-unit-test	Runs the stopping-unit-test script as defined in composer.json
unit-test	Execute unit tests (PHPUnit)
update-deps	Update the Composer dependencies for the 'Gato GraphQL' plugins
update-monorepo-config	Update the monorepo's composer.json and phpstan.neon files, with data from all packages
use-default-restrictive-defaults	Remove the set value, use the default one
validate-monorepo	Validate that version constraints for dependencies are the same for all packages

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

Testing

Unit Tests

Execute unit tests via PHPUnit:

composer unit-test

Integration Tests

Execute integration tests against the Lando webserver for DEV:

composer integration-test

Execute against the Lando webserver for PROD:

composer integration-test-prod

Static analysis

To execute PHPStan, run:

composer analyse

Previewing code downgrade

Via Rector (dry-run mode):

composer preview-code-downgrade

Report issues

Use the issue tracker to report a bug or request a new feature for all packages in the monorepo.

Contributing

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.