Skip to content
master
Go to file
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

GraphQL API for WordPress

Build Status Quality Score Software License

Transform your WordPress site into a GraphQL server.

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

Why

Please read the author's introduction to the GraphQL API for WordPress, which describes:

  • How does it compare with the existing solutions: WP REST API and WPGraphQL
  • Its most important features
  • An overview of all its features
  • Q&A

Requirements

WordPress 5.4 or above, PHP 7.2.5 or above.

Install

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

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

The interactive schema visualizer

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.

If any problem arises, either installing or running the plugin, please create a new issue.

Development

Clone repo, and then install Composer dependencies, by running:

$ git clone https://github.com/GraphQLAPI/graphql-api.git
$ cd graphql-api
$ composer install

Launch a development environment with wp-env

Launch a WordPress environment with the GraphQL API plugin activated through wp-env.

Prerequisites:

  • Node.js
  • npm
  • Docker

To install wp-env globally, run in the terminal:

npm -g i @wordpress/env

To start a new WordPress instance with the GraphQL API plugin already installed and activated, execute in the root folder of the plugin (make sure Docker is running):

wp-env start

Please notice: The first time using wp-env, this process may take a long time (half an hour or even more). To see what is happening, execute with the --debug option: wp-env start --debug

The site will be available under http://localhost:6666.

To access the wp-admin, under http://localhost:6666/wp-admin/:

  • User: admin
  • Password: password

To enable pretty permalinks, run:

wp-env run cli wp rewrite structure '/%postname%/'

Pulling code

Whenever pulling changes from this repo, install again the dependencies:

composer install

Pushing code

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, is not allowed in the repo.

Clone own dependencies

GraphQL API is not a monorepo. Instead, its code is distributed across packages (living in repos from PoP, GraphQLByPoP and PoPSchema), and managed through Composer.

File dev-helpers/scripts/clone-all-dependencies-from-github.sh contains the list of all own dependencies, ready to be cloned.

For development, the GraphQL API plugin can use these local projects by overriding Composer's autoload PSR-4 sources. To do so:

This file will override any corresponding entry defined in composer.json.

Modules

GraphQL API is extensible, and ships with the following modules:

(The documentation for the modules is currently being created)

Module Description
Single Endpoint Expose a single GraphQL endpoint under /graphql/, with unrestricted access
GraphiQL for Single Endpoint Make a public GraphiQL client available under /graphiql/, to execute queries against the single endpoint. It requires pretty permalinks enabled
Interactive Schema for Single Endpoint Make a public Interactive Schema client available under /schema/, to visualize the schema accessible through the single endpoint. It requires pretty permalinks enabled
Persisted Queries Expose predefined responses through a custom URL, akin to using GraphQL queries to publish REST endpoints
Custom Endpoints Expose different subsets of the schema for different targets, such as users (clients, employees, etc), applications (website, mobile app, etc), context (weekday, weekend, etc), and others
GraphiQL for Custom Endpoints Enable custom endpoints to be attached their own GraphiQL client, to execute queries against them
Interactive Schema for Custom Endpoints Enable custom endpoints to be attached their own Interactive schema client, to visualize the custom schema subset
Schema Configuration Customize the schema accessible to different Custom Endpoints and Persisted Queries, by applying a custom configuration (involving namespacing, access control, cache control, and others) to the grand schema
Schema Namespacing Automatically namespace types and interfaces with a vendor/project name, to avoid naming collisions
Access Control Set-up rules to define who can access the different fields and directives from a schema
Access Control Rule: Disable Access Remove access to the fields and directives
Access Control Rule: User State Allow or reject access to the fields and directives based on the user being logged-in or not
Access Control Rule: User Roles Allow or reject access to the fields and directives based on the user having a certain role
Access Control Rule: User Capabilities Allow or reject access to the fields and directives based on the user having a certain capability
Public/Private Schema Enable to communicate the existence of some field from the schema to certain users only (private mode) or to everyone (public mode). If disabled, fields are always available to everyone (public mode)
Cache Control Provide HTTP Caching for Persisted Queries, sending the Cache-Control header with a max-age value calculated from all fields in the query
Field Deprecation Deprecate fields, and explain how to replace them, through a user interface
API Hierarchy Create a hierarchy of API endpoints extending from other endpoints, and inheriting their properties
Low-Level Query Editing Have access to schema-configuration low-level directives when editing GraphQL queries in the admin
GraphiQL Explorer Add the Explorer widget to the GraphiQL client when creating Persisted Queries, to simplify coding the query (by point-and-clicking on the fields)
Schema Editing Access Grant access to users other than admins to edit the GraphQL schema
Excerpt as Description Provide a description of the different entities (Custom Endpoints, Persisted Queries, and others) through their excerpt
Configuration Cache Cache the generated application configuration to disk
Schema Cache Cache the generated schema to disk
Schema Custom Posts Base functionality for all custom posts
Schema Generic Custom Posts Query any custom post type (added to the schema or not), through a generic type GenericCustomPost
Schema Posts Query posts, through type Post added to the schema
Schema Pages Query pages, through type Page added to the schema
Schema Users Query users, through type User added to the schema
Schema User Roles Query user roles, through type UserRole added to the schema
Schema Comments Query comments, through type Comment added to the schema
Schema Tags Base functionality for all tags
Schema Post Tags Query post tags, through type PostTag added to the schema
Schema Media Query media elements, through type Media added to the schema

Resources

The following videos show several features:

For technical information on how the GraphQL server works, check out GraphQL by PoP's documentation and resources (these are still a work in progress).

Standards

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

Change log

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

Testing

composer test

Static Analysis

Execute phpstan with level 5:

composer analyse

To run checks for level 0 (or any level from 0 to 8):

./vendor/bin/phpstan analyse -l 0 src tests

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email leo@getpop.org instead of using the issue tracker.

Credits

License

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

You can’t perform that action at this time.