Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/graphqlapi/graphql-api-for-wp

[READ ONLY] GraphQL API for WordPress
https://github.com/graphqlapi/graphql-api-for-wp

api api-server graphql graphql-server php plugin wordpress

Last synced: 3 months ago
JSON representation

[READ ONLY] GraphQL API for WordPress

Awesome Lists containing this project

README 

        



# GraphQL API for WordPress



Transform your WordPress site into a modern GraphQL server: [graphql-api.com](https://graphql-api.com).



![The interactive schema visualizer](docs/images/interactive-schema.png)



This plugin is the implementation for WordPress of [GraphQL by PoP](https://graphql-by-pop.com/), a CMS-agnostic GraphQL server in PHP.



## Installing the plugin (for production)



👀 Instructions: [Installing the GraphQL API for WordPress plugin](https://github.com/leoloso/PoP/blob/master/docs/installing-graphql-api-for-wordpress.md).



## Development



👀 Instructions: [Setting-up the development environment](https://github.com/leoloso/PoP/blob/master/docs/development-environment.md).



### Supported PHP features



Check the list of [Supported PHP features](https://github.com/leoloso/PoP/blob/master/docs/supported-php-features.md)



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



## Modules



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



ModuleDescription




Endpoint

Single EndpointExpose the single GraphQL endpoint under /graphql/

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)


User Interface

Excerpt as DescriptionProvide a description of the different entities (Custom Endpoints, Persisted Queries, and others) through their excerpt


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

Expose Sensitive Data in the SchemaExpose “sensitive” data elements in the GraphQL schema (such as field Root.roles, field arg Root.posts(status:), and others), which provide access to potentially private user data

Self FieldsExpose "self" fields in the GraphQL schema (such as Post.self and User.self), which can help give a particular shape to the GraphQL response

Schema Custom PostsQuery Custom Post Types

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

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



- [YouTube video: GraphQL API for WordPress demo](https://youtu.be/LnyNyT2RwwI)

- [Making GraphQL Work In WordPress](https://www.smashingmagazine.com/2021/04/making-graphql-work-in-wordpress/)

- [Rendering the WordPress philosophy in GraphQL](https://css-tricks.com/rendering-the-wordpress-philosophy-in-graphql/)

- [Comparing the GraphQL API for WordPress vs WPGraphQL](https://graphql-api.com/blog/graphql-api-vs-wpgraphql-the-fight/)



Architectural resources



### PHP Architecture



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



1. [Transpiling PHP code from 8.0 to 7.x via Rector](https://blog.logrocket.com/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](https://blog.logrocket.com/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](https://blog.logrocket.com/tips-transpiling-code-from-php-8-0-to-7-1/)

4. [Including both PHP 7.1 and 8.0 code in the same plugin … or not?](https://blog.logrocket.com/including-php-7-1-and-8-0-code-same-plugin-or-not/)



Service container implementation:



- [Building extensible PHP apps with Symfony DI](https://blog.logrocket.com/building-extensible-php-apps-with-symfony-di/)



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)](https://www.smashingmagazine.com/2019/11/abstracting-wordpress-code-cms-concepts/)

2. [Abstracting WordPress Code To Reuse With Other CMSs: Implementation (Part 2)](https://www.smashingmagazine.com/2019/11/abstracting-wordpress-code-reuse-with-other-cms-implementation/)



Description of how the plugin is scoped:



- [GraphQL API for WordPress is now scoped, thanks to PHP-Scoper!](https://graphql-api.com/blog/graphql-api-for-wp-is-now-scoped-thanks-to-php-scoper/)



### GraphQL by PoP documentation



GraphQL API for WordPress is powered by the CMS-agnostic GraphQL server [GraphQL by PoP](https://graphql-by-pop.com).



Technical information on how the GraphQL server works:



- [GraphQL by PoP documentation](https://graphql-by-pop.com/docs/getting-started/intro.html).



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



- [Implementing a GraphQL server with components in PHP](https://www.wpkube.com/implementing-graphql-server/)



These articles explain the concepts, design and implementation of GraphQL by PoP:



1. [Designing a GraphQL server for optimal performance](https://blog.logrocket.com/designing-graphql-server-optimal-performance/)

2. [Simplifying the GraphQL data model](https://blog.logrocket.com/simplifying-the-graphql-data-model/)

3. [Schema-first vs code-first development in GraphQL](https://blog.logrocket.com/code-first-vs-schema-first-development-graphql/)

4. [Speeding-up changes to the GraphQL schema](https://blog.logrocket.com/speeding-up-changes-to-the-graphql-schema/)

5. [Versioning fields in GraphQL](https://blog.logrocket.com/versioning-fields-graphql/)

6. [GraphQL directives are underrated](https://blog.logrocket.com/graphql-directives-are-underrated/)

7. [Treating GraphQL directives as middleware](https://blog.logrocket.com/treating-graphql-directives-as-middleware/) 

8. [Creating an @export GraphQL directive](https://blog.logrocket.com/creating-an-export-graphql-directive/)

9. [Adding directives to the schema in code-first GraphQL servers](https://blog.logrocket.com/adding-directives-schema-code-first-graphql-servers/)

10. [Coding a GraphQL server in JavaScript vs. WordPress](https://blog.logrocket.com/coding-a-graphql-server-in-javascript-vs-wordpress/)

11. [Supporting opt-in nested mutations in GraphQL](https://blog.logrocket.com/supporting-opt-in-nested-mutations-in-graphql/)

12. [HTTP caching in GraphQL](https://blog.logrocket.com/http-caching-graphql/)



### Gutenberg



These articles explain the integration with Gutenberg (the WordPress editor).



1. [Adding a Custom Welcome Guide to the WordPress Block Editor](https://css-tricks.com/adding-a-custom-welcome-guide-to-the-wordpress-block-editor/)

2. [Using Markdown and Localization in the WordPress Block Editor](https://css-tricks.com/using-markdown-and-localization-in-the-wordpress-block-editor/)



## Standards



[PSR-1](https://www.php-fig.org/psr/psr-1), [PSR-4](https://www.php-fig.org/psr/psr-4) and [PSR-12](https://www.php-fig.org/psr/psr-12).



To check the coding standards via [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer), run:



``` bash

composer check-style

```



To automatically fix issues, run:



``` bash

composer fix-style

```



## Release notes



- [1.0](docs/release-notes/1.0/en.md)

- **[0.10](docs/release-notes/0.10/en.md)** (current)

- [0.9](docs/release-notes/0.9/en.md)

- [0.8](docs/release-notes/0.8/en.md)

- [0.7](docs/release-notes/0.7/en.md)

- [0.6](docs/release-notes/0.6/en.md)



## Change log



Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.



## Testing



To execute [PHPUnit](https://phpunit.de/), run:



``` bash

composer test

```



## Static Analysis



To execute [PHPStan](https://github.com/phpstan/phpstan), run:



``` bash

composer analyse

```



## Downgrading code



To visualize how [Rector](https://github.com/rectorphp/rector) will downgrade the code to PHP 7.1:



```bash

composer preview-code-downgrade

```



## Report issues



To report a bug or request a new feature please do it on the [PoP monorepo issue tracker](https://github.com/leoloso/PoP/issues).



## Contributing



We welcome contributions for this package on the [PoP monorepo](https://github.com/leoloso/PoP) (where the source code for this package is hosted).



Please see [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) for details.



## Security



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



## Credits



- [Leonardo Losoviz][link-author]



## License



GPLv2 or later. Please see [License File](LICENSE.md) for more information.



[ico-license]: https://img.shields.io/badge/license-GPL%20(%3E%3D%202)-brightgreen.svg?style=flat-square

[ico-travis]: https://img.shields.io/travis/GraphQLAPI/graphql-api-for-wp/master.svg?style=flat-square

[ico-scrutinizer]: https://img.shields.io/scrutinizer/coverage/g/GraphQLAPI/graphql-api-for-wp.svg?style=flat-square

[ico-code-quality]: https://img.shields.io/scrutinizer/g/GraphQLAPI/graphql-api-for-wp.svg?style=flat-square

[ico-release]: https://img.shields.io/github/release/GraphQLAPI/graphql-api-for-wp.svg

[ico-downloads]: https://img.shields.io/github/downloads/GraphQLAPI/graphql-api-for-wp/total.svg



[link-travis]: https://travis-ci.com/github/GraphQLAPI/graphql-api-for-wp

[link-scrutinizer]: https://scrutinizer-ci.com/g/GraphQLAPI/graphql-api-for-wp/code-structure

[link-code-quality]: https://scrutinizer-ci.com/g/GraphQLAPI/graphql-api-for-wp

[link-downloads]: https://GitHub.com/GraphQLAPI/graphql-api-for-wp/releases/

[link-release]: https://GitHub.com/GraphQLAPI/graphql-api-for-wp/releases/

[link-downloads]: https://GitHub.com/GraphQLAPI/graphql-api-for-wp/releases/

[link-contributors]: ../../../../../../contributors

[link-author]: https://github.com/leoloso



[latest-release-url]: https://github.com/leoloso/PoP/releases/latest/download/graphql-api.zip