GraphQL API for WordPress
Transform your WordPress site into a modern GraphQL server: graphql-api.com.
This plugin is the implementation for WordPress of GraphQL by PoP, a CMS-agnostic GraphQL server in PHP.
Requirements
- WordPress 5.4 or above
- PHP 8.0+ for development
- PHP 7.1+ for production
Install
Please read Installing the GraphQL API for WordPress plugin, on the monorepo.
Development
The source code is hosted on the PoP monorepo, under GraphQLAPIForWP/plugins/graphql-api-for-wp.
Please read Setting-up the development environment, on the monorepo.
Allowed code in the repo
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.
PHP versions
Requirements:
- PHP 8.0+ for development
- PHP 7.1+ for production (through release
graphql-api.zip)
Supported PHP features
Check the list of Supported PHP features in leoloso/PoP
Modules
GraphQL API is extensible, and ships with the following modules (organized by category):
| Module | Description |
|---|---|
Endpoint |
|
| Single Endpoint | Expose a single GraphQL endpoint under /graphql/, with unrestricted access |
| 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 |
| API Hierarchy | Create a hierarchy of API endpoints extending from other endpoints, and inheriting their properties |
Schema Configuration |
|
| 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 |
| 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) |
Access Control |
|
| 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 |
Versioning |
|
| Field Deprecation | Deprecate fields, and explain how to replace them, through a user interface |
User Interface |
|
| Low-Level Persisted Query Editing | Have access to schema-configuration low-level directives when editing GraphQL queries in the admin |
| Excerpt as Description | Provide a description of the different entities (Custom Endpoints, Persisted Queries, and others) through their excerpt |
Performance |
|
| 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 |
| Configuration Cache | Cache the generated application configuration to disk |
| Schema Cache | Cache the generated schema to disk |
Operational |
|
| Multiple Query Execution | Execute multiple GraphQL queries in a single operation |
| Remove if Null | Addition of @removeIfNull directive, to remove an output from the response if it is null |
| Proactive Feedback | Usage of the top-level entry extensions to send deprecations, warnings, logs, notices and traces in the response to the query |
| Embeddable Fields | Resolve a field within an argument for another field from the same type, using syntax {{ fieldName }} |
| Composable Directives | Have directives modify the behavior of other directives |
| Nested Mutations | Execute mutations from any type in the schema, not only from the root |
Plugin Management |
|
| Schema Editing Access | Grant access to users other than admins to edit the GraphQL schema |
Clients |
|
| 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 |
| 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 |
| GraphiQL Explorer | Add the Explorer widget to the GraphiQL client, to simplify coding the query (by point-and-clicking on the fields) |
Schema Type |
|
| Admin for the Schema | Add "unrestricted" fields to the GraphQL schema (such as Root.unrestrictedPosts, Root.roles, and others), to be used by the admin only |
| Schema Mutations | Modify data by executing mutations |
| 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 Categories | Base functionality for all categories |
| Schema Post Categories | Query post categories, through type PostCategory added to the schema |
| Schema Custom Post Meta | Add the option field to custom posts, such as type Post |
| Schema User Meta | Add the option field to type User |
| Schema Comment Meta | Add the option field to type Comment |
| Schema Taxonomy Meta | Add the option field to taxonomies, such as types PostTag and PostCategory |
| Schema Media | Query media elements, through type Media added to the schema |
| Schema Menus | Query menus, through type Menu added to the schema |
| Schema Settings | Fetch settings from the site |
| Schema User State Mutations | Have the user log-in, and be able to perform mutations |
| Schema Custom Post Mutations | Base functionality to mutate custom posts |
| Schema Post Mutations | Execute mutations on podyd |
| Schema Custom Post Media Mutations | Execute mutations concerning media items on custom posts |
| Schema Post Tag Mutations | Add tags to posts |
| Schema Post Category Mutations | Add categories to posts |
| Schema Comment Mutations | Create comments |
Resources
Videos
GraphQL API for WordPress demo:
The following videos demonstrate several features:
- Persisted queries
- Custom endpoints
- Access control
- Public/private API
- HTTP caching
- Field deprecation
- Query inheritance
Comparison with WPGraphQL
These articles demonstrate how the GraphQL API fares against WPGraphQL:
WordPress Philosophy
Detailed explanation of the plugin goals, and how it renders the WordPress philosophy:
PHP Architecture
Articles explaining how the plugin is coded using PHP 8.0 but can run on PHP 7.1:
- Transpiling PHP code from 8.0 to 7.x via Rector
- Coding in PHP 7.4 and deploying to 7.1 via Rector and GitHub Actions
GraphQL by PoP documentation
GraphQL API for WordPress is powered by the CMS-agnostic GraphQL server GraphQL by PoP.
For technical information on how it works, check out its documentation.
Description of how a GraphQL server using server-side components works:
These articles explain the concepts, design and implementation of GraphQL by PoP:
- Designing a GraphQL server for optimal performance
- Simplifying the GraphQL data model
- Schema-first vs code-first development in GraphQL
- Speeding-up changes to the GraphQL schema
- Versioning fields in GraphQL
- GraphQL directives are underrated
- Treating GraphQL directives as middleware
- Creating an @export GraphQL directive
- Adding directives to the schema in code-first GraphQL servers
- Coding a GraphQL server in JavaScript vs. WordPress
- Supporting opt-in nested mutations in GraphQL
- HTTP caching in GraphQL
Gutenberg
These articles explain the integration with Gutenberg (the WordPress editor).
- Adding a Custom Welcome Guide to the WordPress Block Editor
- Using Markdown and Localization in the WordPress Block Editor
Standards
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 [email protected] instead of using the issue tracker.
Credits
License
GPLv2 or later. Please see License File for more information.
77 Dec 12, 2022
3 Jan 17, 2022
1 Oct 27, 2022
61 Dec 3, 2022
60 Jan 2, 2023
101 Dec 1, 2022
14 Jul 15, 2022
4 Dec 20, 2022
5 Aug 19, 2022
3 Nov 28, 2022
1 Nov 17, 2021
640 Dec 29, 2022
3 Oct 6, 2022
12 Apr 13, 2022
120 Oct 19, 2022
2 Nov 3, 2022
1 Jun 24, 2022
6 Aug 27, 2022
3.5k Dec 31, 2022