Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

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

GraphQL API for WordPress

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

The interactive schema visualizer

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

Installing the plugin (for production)

👀 Instructions: Installing the GraphQL API for WordPress plugin.

Development

👀 Instructions: Setting-up the development environment.

Supported PHP features

Check the list of Supported PHP features

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.

Building static sites

The GraphQL API for WordPress provides safe default settings, to make "live" sites secure:

  • The single endpoint is disabled
  • The "admin" elements (eg: input field status to query posts with status "draft") are not added to the schema
  • Only a few of settings options and meta keys (for posts, users, etc) can be queried
  • The number of entities (for posts, users, etc) that can be queried at once is limited

These safe default settings are not needed when building "static" sites, where the WordPress site is not exposed to the Internet. These settings can be used instead:

  • The single endpoint is enabled
  • The "admin" elements are exposed in the schema
  • All settings options and meta keys can be queried
  • The number of entities that can be queried at once is unlimited

In development, to enable unsafe defaults, execute:

composer enable-unsafe-defaults

On a site in production, set in wp-config.php:

define( 'GRAPHQL_API_ENABLE_UNSAFE_DEFAULTS', true );

Or define this same key/value as an environment variable.

Modules

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

ModuleDescription

Endpoint
Single EndpointExpose a single GraphQL endpoint under /graphql/, with unrestricted access
Persisted QueriesExpose predefined responses through a custom URL, akin to using GraphQL queries to publish REST endpoints
Custom EndpointsExpose 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
API HierarchyCreate a hierarchy of API endpoints extending from other endpoints, and inheriting their properties

Schema Configuration
Schema ConfigurationCustomize 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 NamespacingAutomatically namespace types with a vendor/project name, to avoid naming collisions
Nested MutationsExecute mutations from any type in the schema, not only from the root
Public/Private SchemaEnable 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)

Access Control
Access ControlSet-up rules to define who can access the different fields and directives from a schema
Access Control Rule: Disable AccessRemove access to the fields and directives
Access Control Rule: User StateAllow or reject access to the fields and directives based on the user being logged-in or not
Access Control Rule: User RolesAllow or reject access to the fields and directives based on the user having a certain role
Access Control Rule: User CapabilitiesAllow or reject access to the fields and directives based on the user having a certain capability

User Interface
Low-Level Persisted Query EditingHave access to schema-configuration low-level directives when editing GraphQL queries in the admin
Excerpt as DescriptionProvide a description of the different entities (Custom Endpoints, Persisted Queries, and others) through their excerpt

Performance
Cache ControlProvide HTTP Caching for Persisted Queries, sending the Cache-Control header with a max-age value calculated from all fields in the query

Clients
GraphiQL for Single EndpointMake a public GraphiQL client available under /graphiql/, to execute queries against the single endpoint. It requires pretty permalinks enabled
Interactive Schema for Single EndpointMake a public Interactive Schema client available under /schema/, to visualize the schema accessible through the single endpoint. It requires pretty permalinks enabled
GraphiQL for Custom EndpointsEnable custom endpoints to be attached their own GraphiQL client, to execute queries against them
Interactive Schema for Custom EndpointsEnable custom endpoints to be attached their own Interactive schema client, to visualize the custom schema subset
GraphiQL ExplorerAdd the Explorer widget to the GraphiQL client, to simplify coding the query (by point-and-clicking on the fields)

Schema Type
Schema Expose Admin DataExpose "admin" elements in the GraphQL schema (such as field Root.roles, input field Root.posts(status:), and others), which provide access to private data
Schema Self FieldsAdd "self" fields to the GraphQL schema (such as Post.self and User.self), which can help give a particular shape to the GraphQL response
Schema Custom PostsBase functionality for all custom posts
Schema Generic Custom PostsQuery any custom post type (added to the schema or not), through a generic type GenericCustomPost
Schema PostsQuery posts, through type Post added to the schema
Schema PagesQuery pages, through type Page added to the schema
Schema UsersQuery users, through type User added to the schema
Schema User RolesQuery user roles, through type UserRole added to the schema
Schema User AvatarsQuery user avatars, through type UserAvatar added to the schema
Schema CommentsQuery comments, through type Comment added to the schema
Schema TagsBase functionality for all tags
Schema Post TagsQuery post tags, through type PostTag added to the schema
Schema CategoriesBase functionality for all categories
Schema Post CategoriesQuery post categories, through type PostCategory added to the schema
Schema MediaQuery media elements, through type Media added to the schema
Schema Custom Post MetaAdd the option field to custom posts, such as type Post
Schema User MetaAdd the option field to type User
Schema Comment MetaAdd the option field to type Comment
Schema Taxonomy MetaAdd the option field to taxonomies, such as types PostTag and PostCategory
Schema MenusQuery menus, through type Menu added to the schema
Schema SettingsFetch settings from the site
Schema MutationsModify data by executing mutations
Schema User State MutationsHave the user log-in, and be able to perform mutations
Schema Custom Post MutationsBase functionality to mutate custom posts
Schema Post MutationsExecute mutations on podyd
Schema Custom Post Media MutationsExecute mutations concerning media items on custom posts
Schema Post Media MutationsExecute mutations concerning media items on posts
Schema Post Tag MutationsAdd tags to posts
Schema Post Category MutationsAdd categories to posts
Schema Comment MutationsCreate comments

Resources

Architectural resources

PHP Architecture

Articles explaining how the plugin is "downgraded", using PHP 8.0 for development but deployable to PHP 7.1 for production:

  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
  3. Tips for transpiling code from PHP 8.0 down to 7.1
  4. Including both PHP 7.1 and 8.0 code in the same plugin … or not?

Service container implementation:

Explanation of how the codebase is split into granular packages, to enable CMS-agnosticism:

  1. Abstracting WordPress Code To Reuse With Other CMSs: Concepts (Part 1)
  2. Abstracting WordPress Code To Reuse With Other CMSs: Implementation (Part 2)

Description of how the plugin is scoped:

GraphQL by PoP documentation

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

Technical information on how the GraphQL server works:

Description of how a GraphQL server using server-side components works:

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
  12. HTTP caching 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

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

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 leo@getpop.org instead of using the issue tracker.

Credits

License

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