Add web.auth.UserInfo to map the returned user from a flow

[thekid]

This pull request:

• creates a fluent API modeled after https://github.com/xp-forge/sequence for working with the flow's result
• adds a facility for fetching information about the authenticated user at the end of a successful OAuth flow.

Example

The following shows how code can be rewritten when using this class:

- use web\auth\{AuthenticationError, SessionBased};
+ use web\auth\SessionBased;
  use web\auth\oauth\OAuth2Flow;

  $flow= new OAuth2Flow(/* shortened for brevity */);
- $auth= new SessionBased($flow, $sessions, function($client) {
-   $res= $client->fetch('https://graph.microsoft.com/v1.0/me');
-   if ($res->status() >= 400) throw new AuthenticationError('Unexpected status '.$res->status());
-   return $res->value();
- });
+ $auth= new SessionBased($flow, $sessions, $flow->fetchUser('https://graph.microsoft.com/v1.0/me'));

Mapping the user

Often, the user object returned needs to be mapped to an app-specific structure, or cached in a local database. This is where the map() function comes into play:

$auth= new SessionBased($flow, $sessions, $flow->fetchUser('https://graph.microsoft.com/v1.0/me')
  ->map(fn($graph) => ['ref' => $graph['id'], 'name' => $graph['displayName']])
  ->map(fn($user) => $users->modify(['ref' => $user['ref']], $user, upsert: true)
    ->document()
    ->properties()
  )
);

Debugging

To debug the values inside a mapping pipeline, insert a peek() call:

$auth= new SessionBased($flow, $sessions, $flow->fetchUser('https://graph.microsoft.com/v1.0/me')
  ->peek(Console::writeLine(...))
  ->map(fn($graph) => ['ref' => $graph['id'], 'name' => $graph['displayName']])
);

[thekid]

Given the above example, there is no way to also fetch the user's avatar image as shown in this piece of code:

$auth= new SessionBased($flow, $sessions, function($client) use($storage) {
  $res= $client->fetch('https://graph.microsoft.com/v1.0/me');
  if ($res->status() >= 400) throw new AuthenticationException('Unexpected error', nameof($client));

  // Cache user photo locally
  $user= $res->value();
  $picture= $client->fetch('https://graph.microsoft.com/v1.0/me/photo/$value');
  if (200 === $picture->status()) {
    $storage->store($user['id'], 'photo', $picture->header('Content-Type'), $picture->stream());
  }

  return $user;
});

See https://learn.microsoft.com/en-us/graph/api/profilephoto-get?view=graph-rest-1.0&tabs=http#http-request

[thekid]

Given the above example, there is no way to also fetch the user's avatar image as shown in this piece of code:
[...]

After passsing the original authentication result as second argument to callbacks this can now be written as:

$auth= new SessionBased($flow, $sessions, $flow->fetchUser('https://graph.microsoft.com/v1.0/me')
  ->map(function($user, $client) use($storage) {
    $picture= $client->fetch('https://graph.microsoft.com/v1.0/me/photo/$value');
    if (200 === $picture->status()) {
      $storage->store($user['id'], 'photo', $picture->header('Content-Type'), $picture->stream());
    }
    return $user;
  })
);

[thekid]

Mapping the user info and being able to easily add debugging via peek would also be nice to have available for CAS authentication flows. This could be accomplished by adding a userInfo() method to the flow classes:

use web\auth\SessionBased:
use web\auth\cas\CasFlow;
use web\auth\oauth\OAuth2Flow;

// CAS uses the user info as returned
$flow= new CasFlow(/* ... */);
$userInfo= $flow->userInfo();

// OAuth fetches user info from a given endpoint
$flow= new OAuth2Flow(/* ... */);
$userInfo= $flow->fetchUser('https://graph.microsoft.com/v1.0/me');

// This call is the same in both cases
$auth= new SessionBased($flow, $sessions, $userInfo
  ->peek(Console::writeLine(...)) // Debugging
  ->map(fn($user) => ['ref' => $user['id'], 'name' => $user['displayName']])
);