Understanding the User Session

Typically, GraphQL requests don’t have an effect on the context of the PHP environment. This is due to any context hardly ever being needed when querying for public data. However, when dealing with private data, it’s best practice to hide values, fields, or possibly types behind some kind of context.

When I refer to the context of the PHP environment, I’m referring to any preset values assigned to PHP globals and storage like PHP sessions and PHP cookies, when the WPGraphQL server begins to process the query.

To elaborate further, user context could be any preset value related to the end-user whose browser sent the request. These values can be used by WordPress to do common tasks like authenticate the end-user or identify some data object related to the end-user.

In HTTP requests made when navigating links on a WordPress site, those common tasks are managed by cookies created in previous requests and saved to the end-users computer. These cookies are then sent by the end user’s browser along with any HTTP request sent to WordPress from within the WordPress domain.

On the other hand, when dealing with a decoupled front-end application that makes GraphQL requests from external origins and domains, using cookies to manage the user context of these requests is difficult to set up and not always possible. Sending JSON Web Tokens as HTTP headers in the GraphQL request is the recommended solution for creating context.

JSON Web Token (JWT) solutions for the purpose of WordPress user authentication are available. Most commonly in the form of plugins, that authenticate the end-user by decoding and reading JWTs sent through the “Authorization” HTTP header container the end-users WordPress User ID.

Why is this important?

WooGraphQL has the ability to take advantage of JWTs build and distribute in-house to provide a gateway to WooCommerce’s functionality that relies on user context.

This includes the shopping cart, shipping calculator, and guest data/orders.

The shopping cart data and guest data are saved temporarily in the WordPress database, so rolling your own objects for these client-side won’t be necessary if using methods demonstrated throughout this section.

What is a JWT and a WooCommerce Session Token?

A JWT (pronounced “jot”) refers to any JSON Web Token (JWT) sent through the “Authorization” or any other HTTP header for the purpose of authenticating the end-user before the core logic of the HTTP request has been executed.

A WooCommerce session token is a JWT created by WooGraphQL for the sole purpose of identifying the WooCommerce customer session of the end-user.

Small note: As I said, there are multiple solutions available but throughout this documentation you’ll find references to the WPGraphQL-JWT-Authentication plugin, so that will be the JWT solution discussed here.

They both work by storing the user/customer ID along with some info about who made it and whose to receive the token into an object and encrypting that into a string a.k.a. a JWT. WPGraphQL-JWT-Authentication and WooGraphQL make these tokens available through the way of queryable fields

However, the user context typically has to be set up before these fields are accessible.

Most of the time the way to generate a JWTs that will set up the user context in all future requests is to run a mutation that changes the context by authenticating a user or creating a session.

For instance the login() mutation provided by the WPGraphQL-JWT-Authentication plugin is perfect for this, and when used with WooGraphQL the following mutation can be used.

After retrieving these tokens they are to be provided as headers “Authorization” and “woocommerce-session” for all future requests until you wish to end the end-user session by means of logging out or expiration. There are a number of ways to do this so I won’t be going into too much detail here, but if using a client-side library like Apollo or Relay, just look up how to access the middleware layer for your library of choice.

Once you set the newly created tokens in their proper headers and a new request is made. Before the init hook is executed the tokens are decrypted and their identifiers verified, then this is where the tokens differ.

The JWT generated by WPGraphQL-JWT-Authentication is relatively simple. Essentially, you can just say it runs wp_set_current_user() on the encrypted user ID.

The WooCommerce session token is also simple but with a little complexity. It searches the database for session data connected to the encrypted customer ID. Please note: the customer ID may be a guest ID that doesn’t have a corresponding user ID. Good to know

WPGraphQL-JWT-Authentication tokens and WooCommerce session tokens can be used to identify an end user’s WooCommerce session but it’s recommended that you use both, unless you intend to support guest checkout only then you can use just the WooCommerce session token.

Why does WooGraphQL use a custom session handler in the first place?

If you’re familiar with WooCommerce, you may be wondering why use a custom session handler at all instead of the WooCommerce default session handler. A number of reasons but the ones that really matter are.

• The default session handler only supports cookies.
• The default session handler only saves changes at the end of the request in the shutdown hook.
• The default session handler has no support for concurrent requests.
• More consistent with the most modern web.