Solving Preview Related Exceptions Outside of the HTTP environment

[gsteel]

The problem of expired preview tokens is a pain in the ass. Whilst it is easy to recover from an expired preview by removing the user's preview cookie within middleware and the HTTP request cycle, it is much harder to recover from an expired token if you use data from the api anywhere outside of the dispatch process.

For example, anywhere that you might be using a document as the root node in a hierarchy for routing purposes.

Littering your code with try { /**..**/ } catch (PreviewTokenExpired $e) {} is going to get boring very quickly.

A potential solution for avoiding fatal errors due to this problem is to wrap the api client in a delegator that tries for you and simply re-submits the request with the master ref when it encounters an expired token. The main drawback to this approach is that it will double the number of operations for the user for as long as the cookie is present in their browser.

To mitigate this, some logic could be implemented in the delegator such as $api->usesExpiredPreviewToken() - a simple middleware could inspect the api instance and clear the cookie, replacing the current implementation that fails to catch the situation when it occurs outside of HTTP.