Microsoft Graph PHP SDK

A TokenRequestContext contains the credentials used to authenticate requests. The SDK supports several OAuth 2.0 flows through different context classes. These contexts are passed to an authentication provider that handles fetching, caching, and refreshing access tokens.

Client Credentials Flow (App-only access)

Use ClientCredentialContext to get access without a user (service-to-service authentication).

Authorization Code Flow (User delegation)

Use AuthorizationCodeContext to get access on behalf of a user. Note that your application must handle the redirect to the Microsoft Identity login page to obtain the authCode required for this context.

// Client Credentials (No user)
use Microsoft\Kiota\Authentication\Oauth\ClientCredentialContext;

$tokenRequestContext = new ClientCredentialContext(
    'tenantId',
    'clientId',
    'clientSecret'
);

// Authorization Code (On behalf of a user)
use Microsoft\Kiota\Authentication\Oauth\AuthorizationCodeContext;

$tokenRequestContext = new AuthorizationCodeContext(
    'tenantId',
    'clientId',
    'clientSecret',
    'authCode',
    'redirectUri'
);

For large result sets, use the PageIterator. It automatically handles @odata.nextLink to fetch subsequent pages. You provide an initial response and the request adapter. The iterate() method accepts a callback that is executed for each item; returning false from the callback pauses the iteration.

use Microsoft\Graph\Core\Tasks\PageIterator;
use Microsoft\Graph\Generated\Models\Message;
use DateTimeInterface;

$messages = $graphServiceClient->users()->byUserId(USER_ID)->messages()->get()->wait();

$pageIterator = new PageIterator($messages, $graphServiceClient->getRequestAdapter());

$counter = 0;
$callback = function (Message $message) use (&$counter) {
    echo "Subject: {$message->getSubject()}, Received at: {$message->getReceivedDateTime()->format(DateTimeInterface::RFC2822)}\n";
    $counter ++;
    return ($counter % 5 != 0);
};

while ($pageIterator->hasNext()) {
    // iteration pauses and resumes after every 5 messages
    $pageIterator->iterate($callback);

    echo "\nPaused iteration...Total messages: {$counter}\n\n";
}

Continuous Access Evaluation (CAE) is disabled by default. When enabled, if the Microsoft Graph API returns a claims challenge, the SDK attempts to refresh the access token once. If that fails, it executes a custom callback provided by the developer to re-authenticate the user.

To use CAE:

1. Set setCAEEnabled(true) on your TokenRequestContext.
2. Implement setCAERedirectCallback() to handle the asynchronous re-authentication logic and return a new TokenRequestContext.
3. Wrap calls in a try-catch block to handle ContinuousAccessEvaluationException if the re-authentication fails to resolve the challenge.

$tokenRequestContext = new AuthorizationCodeContext(
    'tenantId',
    'clientId',
    'clientSecret',
    'authCode',
    'redirectUri'
);
$graphServiceClient = new GraphServiceClient($tokenRequestContext);

$tokenRequestContext->setCAEEnabled(true);
$tokenRequestContext->setCAERedirectCallback(function (string $claims) {
    // your app makes the user log in again asynchronously
    return yourCustomLoginAsync()->then(
        function (string $authCode) {
            $newTokenRequestContext = new AuthorizationCodeContext(
                'tenantId',
                'clientId',
                'clientSecret',
                $authCode,
                'redirectUri'
            );
            return $newTokenRequestContext;
        }
    );
});

try {
    $numUsers = $graphServiceClient->users()->count()->get()->wait();
} catch (ContinuousAccessEvaluationException $ex) {
    echo $ex->getError()->getMessage();
}

To persist tokens across different PHP processes (e.g., in a database or Redis), implement the AccessTokenCache interface. When the SDK performs a request, it will call persistAccessToken() to save the token.

To ensure your custom cache aligns with the SDK's lookup logic, you should use the cache key generated by the TokenRequestContext. You can manually set this key using $tokenRequestContext->setCacheKey($accessToken).

$accessToken = new AccessToken([
    'access_token' => $accessToken,
    'refresh_token' => $refreshToken,
    'expires' => ...
]);

$tokenRequestContext->setCacheKey($accessToken);

// init custom cache with tokens mapped to specific user/app using $tokenRequestContext->getCacheKey()
$customCache = new CustomCache($tokenRequestContext->getCacheKey(), $accessToken);

// init graph client
$graphServiceClient = GraphServiceClient::createWithAuthenticationProvider(
    GraphPhpLeagueAuthenticationProvider::createWithAccessTokenProvider(
        GraphPhpLeagueAccessTokenProvider::createWithCache(
            $customCache,
            $tokenRequestContext,
            $scopes
        )
    )
);