Adjusting filters, updating README.

Author: chriszarate

readme.md

@@ -1,5 +1,64 @@
 # WPGraphQL Persisted Queries
 
-Persist queries in a custom post type, allowing them to be loaded by ID using
-the `queryId` operation parameter. This paves the way for using `GET` requests
-and leveraging edge cache.
+Persisted GraphQL queries allow a GraphQL client to optimistically send a hash
+of the query instead of the full query; if the server has seen the query
+before, it can satisfy the request. This saves network overhead and makes it
+possible to move to `GET` requests instead of `POST`. The primary benefit of
+`GET` requests is that they can be easily cached at the edge (e.g., with
+Varnish).
+
+This plugin requires [WPGraphQL][wp-graphql] 0.2.0 or newer.
+
+## Compatibility
+
+Apollo Client provides an easy implementation of persisted queries:
+
+https://github.com/apollographql/apollo-link-persisted-queries#automatic-persisted-queries
+
+This plugin aims to be compatible with that implementation, but will work with
+any client that sends a `queryId` alongside the `query`. Make sure your client
+also sends `operationName` with the optimistic request.
+
+## Implementation
+
+When the client provides a query hash or ID, that query will be persisted in a
+custom post type. By default, this post type will be visible in the dashboard
+only to admins.
+
+Query IDs are case-insensitive (that is `MyQuery` and `myquery` are equivalent).
+
+## Filters
+
+### `graphql_persisted_queries_post_type`
+
+- Default: `'graphql_query'`
+- The custom post type used to persist queries. If empty, queries will not be
+ persisted.
+
+### `graphql_persisted_queries_show_in_graphql`
+
+- Default: `false`
+- Whether the custom post type will itself be exposed via GraphQL. Enabling
+ allows insight into which queries are persisted. Note that queries are
+ inserted as drafts, so you will need to query accordingly, e.g.:
+
+ ```
+ query PersistedQueryQuery {
+ persistedQueries (
+ where: {
+ status: DRAFT
+ }
+ ) {
+ nodes {
+ id
+ title
+ content(format: RAW)
+ }
+ }
+ }
+ ```
+
+If you'd like to further customize the custom post type, filter
+`register_post_type_args`.
+
+[wp-graphql]: https://github.com/wp-graphql/wp-graphql

src/loader.php

@@ -11,16 +11,14 @@
  * Load or save a persisted query from a custom post type. This allows users to
  * avoid sending the query over the wire, saving bandwidth. In particular, it
  * allows for moving to GET requests, which can be cached at the edge.
- *
- * @package WPGraphQL\Extensions\PersistedQueries
  */
 class Loader {
 /**
- * Whether query persistence is enabled.
+ * Namespace for WP filters.
  *
- * @var bool
+ * @var string
  */
-private $enabled = true;
+private $namespace = 'graphql_persisted_queries';
 
 /**
  * Post type for default query persistence. Unused if query persistence is
@@ -37,22 +35,16 @@ class Loader {
  * @return void
  */
 public function init() {
-/**
- * Whether to enable persisted queries.
- *
- * @param bool $enabled Enable?
- */
-$this->enabled = apply_filters( 'graphql_persisted_query_enabled', $this->enabled );
-
 /**
  * Post type to use to persist queries. Unused if disabled.
  *
  * @param string $post_type
+ * @since 1.0.0
  */
-$this->post_type = apply_filters( 'graphql_persisted_query_post_type', $this->post_type );
+$this->post_type = apply_filters( "{$this->namespace}_post_type", $this->post_type );
 
-// If not enabled or the post type doesn't look right, don't hook.
-if ( ! $this->enabled || empty( $this->post_type ) || post_type_exists( $this->post_type ) ) {
+// If the post type doesn't look right, don't hook.
+if ( empty( $this->post_type ) || post_type_exists( $this->post_type ) ) {
 return;
 }
 
@@ -86,41 +78,50 @@ public function load( $query_id ) {
  * @return array
  */
 public function process_request_data( $request_data ) {
-// Client sends *both* queryId and query = request to persist query.
+// Client sends *both* queryId and query == request to persist query.
 if ( ! empty( $request_data['queryId'] ) && ! empty( $request_data['query'] ) ) {
 $this->save( $request_data['queryId'], $request_data['query'], $request_data['operation'] );
 }
 
-// Client sends queryId but *not* query = optimistic request to use cached query.
+// Client sends queryId but *not* query == optimistic request to use cached query.
 if ( ! empty( $request_data['queryId'] ) && empty( $request_data['query'] ) ) {
 $request_data['query'] = $this->load( $request_data['queryId'] );
 }
 
-// We've got this; call off any other persistence implementations.
+// We've got this. Call off any other persistence implementations.
 unset( $request_data['queryId'] );
 
 return $request_data;
 }
 
 /**
- * Register the persisted query post type. Filter register_post_type_args to
- * show persisted queries in GraphQL. 💅
+ * Register the persisted query post type. We could filter a lot of individual
+ * values here, but we won't. If further customization is wanted, filter
+ * register_post_type_args.
  *
  * @return void
  */
 private function register_post_type() {
+/**
+ * Whether persisted queries can be themselves queried via GraphQL. 💅
+ *
+ * @param bool $show_in_graphql Show in GraphQL?
+ * @since 1.0.0
+ */
+$show_in_graphql = apply_filters( "{$this->namespace}_show_in_graphql", false );
+
 register_post_type(
 $this->post_type,
 [
 'label' => 'Queries',
 'public' => false,
-'query_var' => true,
+'query_var' => false,
 'rewrite' => false,
 'show_in_rest' => false,
-'show_in_graphql' => false,
+'show_in_graphql' => $show_in_graphql,
 'graphql_single_name' => 'persistedQuery',
 'graphql_plural_name' => 'persistedQueries',
-'show_ui' => true,
+'show_ui' => is_admin(),
 'supports' => [ 'title', 'editor' ],
 ]
 );

wp-graphql-persisted-queries.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: WPGraphQL Persisted Queries
  * Plugin URI: https://github.com/Quartz/wp-graphql-persisted-queries
- * Description: Provides persistence to queries allowing them to be queried by ID (hash)
+ * Description: Provides persistence to GraphQL queries allowing them to be queried by ID or hash. Requires WPGraphQL 0.2.0 or newer.
  * Author: Chris Zarate, Quartz
  * Version: 1.0.0
  * Author URI: https://qz.com/