Sessions and redirects

The client needs somewhere to store the login exchange between requests, and a way to send the browser to another URI. For a small PHP application, the default implementations use $_SESSION and a Location header.

Starting a native session

require __DIR__ . "/vendor/autoload.php";
session_start();

Do this before constructing Authenticator and before sending output. GlobalSessionContainer wraps the existing $_SESSION array; it does not start the session. If the array is absent it throws SessionNotStartedException.

The authentication data is stored under Authwave\SessionData::class. Although Authenticator declares a SESSION_STORE_KEY constant, its current storage operations use the class name instead.

The browser must retain the application's session cookie while visiting the provider. Losing that session loses the token needed to process the return response. Use session storage shared across application servers if requests can arrive on different servers.

Supplying a container

Existing applications can pass an implementation of GT\Session\SessionContainer. Its contract is get(), set(), contains() and remove() with string keys. It must preserve the stored objects across the browser's redirect round trip.

For example, we can explicitly wrap an already started native session:

$session = new GT\Session\SessionArrayWrapper($_SESSION);

$auth = new Authwave\Authenticator(
	clientKey: $clientKey,
	currentUriPath: $_SERVER["REQUEST_URI"],
	session: $session,
);

An in-memory array is useful in tests, but does not persist between web requests on its own. A custom storage adapter must preserve the SessionData and Token objects expected by the client.

Redirect behaviour

The default Authwave\RedirectHandler sends a 303 response with a Location header, then calls exit. This happens during login, ordinary provider logout and response tidying. A constructor handling a return response can therefore end the request before the next line of application code runs.

A framework integration can subclass RedirectHandler and override:

public function redirect(
	Psr\Http\Message\UriInterface $uri,
	int $code = 303,
):void

Pass the instance through the redirectHandler constructor argument. The replacement should transfer control out of the current request, for example through the framework's redirect exception. Merely recording a response and returning lets execution continue, which can differ from the client's normal control flow.

Building a login URI directly

getLoginUri(Token $token) returns a URI without storing the token or redirecting. For normal web applications, prefer login(): it performs those steps together. If you build a login URI yourself, you must also preserve the matching token in the correct session data for the return request.

---

See Development and testing for an example of a redirect handler that records destinations in tests.