Add new logical theme event to customize OIDC ID token data

[ssddanbrown]

As a way to supplement or augment the existing data so users can manipulate anything that's outside the bounds of what we support, into the format that BookStack expects.

Should be very early in the token's usage within BookStack.
Maybe also provide other token data so user can do things like call userinfo endpoint? (Related to #3873).

Request originated from conversations in #4147.

[ssddanbrown]

Added in f64ce71, to be part of the next release.

Example: Prefix "Sir" to names ending with "Chuckle"

Theme::listen(ThemeEvents::OIDC_ID_TOKEN_PRE_VALIDATE, function (array $idTokenData, array $accessTokenData) {
    $currentName = $idTokenData['name'];
    if (str_ends_with($currentName, 'Chuckle')) {
        return array_merge($idTokenData, [
            'name' => 'Sir ' . $currentName,
        ]);
    }
});

Example: Replace multiple aud values with single azp value

@the-voidl I think this should do what you need (using the theme system once on a release using this addition). I have not tested this specific example though.

<?php

use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;

Theme::listen(ThemeEvents::OIDC_ID_TOKEN_PRE_VALIDATE, function (array $idTokenData, array $accessTokenData) {
    if (is_array($idTokenData['aud']) && in_array($idTokenData['azp'], $idTokenData['aud'])) {
        return array_merge($idTokenData, [
            'aud' => [$idTokenData['azp']]
        ]);
    }
});