Build PHP apps with Microsoft Graph

This tutorial teaches you how to build a PHP console app that uses the Microsoft Graph API to access data on behalf of a user.

In this tutorial, you will:

• Get the signed-in user
• List the user's inbox messages
• Send an email

Prerequisites

Before you start this tutorial, you should have PHP and Composer installed on your development machine.

You should also have a Microsoft work or school account with an Exchange Online mailbox. If you don't have a Microsoft 365 tenant, you might qualify for one through the Microsoft 365 Developer Program; for details, see the FAQ. Alternatively, you can sign up for a 1-month free trial or purchase a Microsoft 365 plan.

Register the app in the portal

• 28 minutes remaining

In this exercise you will register a new application in Azure Active Directory to enable user authentication. You can register an application using the Microsoft Entra admin center, or by using the Microsoft Graph PowerShell SDK.

Register application for user authentication

In this section you will register an application that supports user authentication using device code flow.

Create a PHP console app

• 25 minutes remaining

Begin by initializing a new Composer project. Open your command-line interface (CLI) in a directory where you want to create the project. Run the following command.

composer init

Answer the prompts. You can accept the defaults for most questions, but respond n to the following:

Would you like to define your dependencies (require) interactively [yes]? n
Would you like to define your dev dependencies (require-dev) interactively [yes]? n
Add PSR-4 autoload mapping? Maps namespace "Microsoft\Graphtutorial" to the entered relative path. [src/, n to skip]: n

Install dependencies

Before moving on, add some additional dependencies that you will use later.

• Microsoft Graph SDK for PHP to make calls to the Microsoft Graph.
• vlucas/phpdotenv for reading environment variables from .env files.

Run the following command in your CLI to install the dependencies.

composer require microsoft/microsoft-graph vlucas/phpdotenv

Load application settings

In this section you'll add the details of your app registration to the project.

1. Create a file in the root directory of your project named .env and add the following code.

   CLIENT_ID=YOUR_CLIENT_ID_HERE
   TENANT_ID=common
   GRAPH_USER_SCOPES='user.read mail.read mail.send'
   

2. Update the values according to the following table.

   Setting	Value
   CLIENT_ID	The client ID of your app registration
   TENANT_ID	If you chose the option to only allow users in your organization to sign in, change this value to your tenant ID. Otherwise leave as common.

   Important

   If you're using source control such as git, now would be a good time to exclude the .env file from source control to avoid inadvertently leaking your app ID.

Design the app

In this section you will create a simple console-based menu.

1. Create a file in the root directory of your project named main.php. Add the opening and closing PHP tags.

   <?php
   ?>
   

2. Add the following code between the PHP tags.

   // Enable loading of Composer dependencies
   require_once realpath(__DIR__ . '/vendor/autoload.php');
   require_once 'GraphHelper.php';
   
   print('PHP Graph Tutorial'.PHP_EOL.PHP_EOL);
   
   // Load .env file
   $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
   $dotenv->load();
   $dotenv->required(['CLIENT_ID', 'TENANT_ID', 'GRAPH_USER_SCOPES']);
   
   initializeGraph();
   
   greetUser();
   
   $choice = -1;
   
   while ($choice != 0) {
       echo('Please choose one of the following options:'.PHP_EOL);
       echo('0. Exit'.PHP_EOL);
       echo('1. Display access token'.PHP_EOL);
       echo('2. List my inbox'.PHP_EOL);
       echo('3. Send mail'.PHP_EOL);
       echo('4. Make a Graph call'.PHP_EOL);
   
       $choice = (int)readline('');
   
       switch ($choice) {
           case 1:
               displayAccessToken();
               break;
           case 2:
               listInbox();
               break;
           case 3:
               sendMail();
               break;
           case 4:
               makeGraphCall();
               break;
           case 0:
           default:
               print('Goodbye...'.PHP_EOL);
       }
   }
   

3. Add the following placeholder methods at the end of the file before the closing PHP tag. You'll implement them in later steps.

   function initializeGraph(): void {
       // TODO
   }
   
   function greetUser(): void {
       // TODO
   }
   
   function displayAccessToken(): void {
       // TODO
   }
   
   function listInbox(): void {
       // TODO
   }
   
   function sendMail(): void {
       // TODO
   }
   
   function makeGraphCall(): void {
       // TODO
   }
   

This implements a basic menu and reads the user's choice from the command line.

Add user authentication

• 20 minutes remaining

In this section you will extend the application from the previous exercise to support authentication with Azure AD. This is required to obtain the necessary OAuth access token to call the Microsoft Graph.

Create access token provider

The Microsoft Graph SDK includes authentication providers based on the PHP League OAuth2 client. However for this tutorial, you will use the device code flow to obtain access tokens. The included authentication providers do not implement this flow, so you will implement a custom access token provider.

1. Create a new file in the root directory of your project named DeviceCodeTokenProvider.php. Add the following code.

   <?php
   // Copyright (c) Microsoft Corporation. All rights reserved.
   // Licensed under the MIT license.
   
   use GuzzleHttp\Client;
   use Http\Promise\FulfilledPromise;
   use Http\Promise\Promise;
   use Http\Promise\RejectedPromise;
   use Microsoft\Kiota\Abstractions\Authentication\AccessTokenProvider;
   use Microsoft\Kiota\Abstractions\Authentication\AllowedHostsValidator;
   
   class DeviceCodeTokenProvider implements AccessTokenProvider {
   
       private string $clientId;
       private string $tenantId;
       private string $scopes;
       private AllowedHostsValidator $allowedHostsValidator;
       private string $accessToken;
       private Client $tokenClient;
   
       public function __construct(string $clientId, string $tenantId, string $scopes) {
           $this->clientId = $clientId;
           $this->tenantId = $tenantId;
           $this->scopes = $scopes;
           $this->allowedHostsValidator = new AllowedHostsValidator();
           $this->allowedHostsValidator->setAllowedHosts([
               "graph.microsoft.com",
               "graph.microsoft.us",
               "dod-graph.microsoft.us",
               "graph.microsoft.de",
               "microsoftgraph.chinacloudapi.cn"
           ]);
           $this->tokenClient = new Client();
       }
   
       public function getAuthorizationTokenAsync(string $url, array $additionalAuthenticationContext = []): Promise {
           $parsedUrl = parse_url($url);
           $scheme = $parsedUrl["scheme"] ?? null;
   
           if ($scheme !== 'https' || !$this->getAllowedHostsValidator()->isUrlHostValid($url)) {
               return new FulfilledPromise(null);
           }
   
           // If we already have a user token, just return it
           // Tokens are valid for one hour, after that it needs to be refreshed
           if (isset($this->accessToken)) {
               return new FulfilledPromise($this->accessToken);
           }
   
           // https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code
           $deviceCodeRequestUrl = 'https://login.microsoftonline.com/'.$this->tenantId.'/oauth2/v2.0/devicecode';
           $tokenRequestUrl = 'https://login.microsoftonline.com/'.$this->tenantId.'/oauth2/v2.0/token';
   
           // First POST to /devicecode
           $deviceCodeResponse = json_decode($this->tokenClient->post($deviceCodeRequestUrl, [
               'form_params' => [
                   'client_id' => $this->clientId,
                   'scope' => $this->scopes
               ]
           ])->getBody()->getContents());
   
           // Display the user prompt
           print($deviceCodeResponse->message.PHP_EOL);
   
           // Response also indicates how often to poll for completion
           // And gives a device code to send in the polling requests
           $interval = (int)$deviceCodeResponse->interval;
           $device_code = $deviceCodeResponse->device_code;
   
           // Do polling - if attempt times out the token endpoint
           // returns an error
           while (true) {
               sleep($interval);
   
               // POST to the /token endpoint
               $tokenResponse = $this->tokenClient->post($tokenRequestUrl, [
                   'form_params' => [
                       'client_id' => $this->clientId,
                       'grant_type' => 'urn:ietf:params:oauth:grant-type:device_code',
                       'device_code' => $device_code
                   ],
                   // These options are needed to enable getting
                   // the response body from a 4xx response
                   'http_errors' => false,
                   'curl' => [
                       CURLOPT_FAILONERROR => false
                   ]
               ]);
   
               if ($tokenResponse->getStatusCode() == 200) {
                   // Return the access_token
                   $responseBody = json_decode($tokenResponse->getBody()->getContents());
                   $this->accessToken = $responseBody->access_token;
                   return new FulfilledPromise($responseBody->access_token);
               } else if ($tokenResponse->getStatusCode() == 400) {
                   // Check the error in the response body
                   $responseBody = json_decode($tokenResponse->getBody()->getContents());
                   if (isset($responseBody->error)) {
                       $error = $responseBody->error;
                       // authorization_pending means we should keep polling
                       if (strcmp($error, 'authorization_pending') != 0) {
                           return new RejectedPromise(
                               new Exception('Token endpoint returned '.$error, 100));
                       }
                   }
               }
           }
       }
   
       public function getAllowedHostsValidator(): AllowedHostsValidator {
           return $this->allowedHostsValidator;
       }
   }
   ?>
   

Configure Graph client for user authentication

In this section you will use the DeviceCodeTokenProvider class to request an access token by using the device code flow.

1. Create a new file in the root directory of your project named GraphHelper.php. Add the following code.

   <?php
   class GraphHelper {
   }
   ?>
   

2. Add the following using statements inside the PHP tags.

   use Microsoft\Graph\Generated\Models;
   use Microsoft\Graph\Generated\Users\Item\MailFolders\Item\Messages\MessagesRequestBuilderGetQueryParameters;
   use Microsoft\Graph\Generated\Users\Item\MailFolders\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;
   use Microsoft\Graph\Generated\Users\Item\SendMail\SendMailPostRequestBody;
   use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetQueryParameters;
   use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;
   use Microsoft\Graph\GraphRequestAdapter;
   use Microsoft\Graph\GraphServiceClient;
   use Microsoft\Kiota\Abstractions\Authentication\BaseBearerTokenAuthenticationProvider;
   
   require_once 'DeviceCodeTokenProvider.php';
   

3. Add the following code to the GraphHelper class.

   private static string $clientId = '';
   private static string $tenantId = '';
   private static string $graphUserScopes = '';
   private static DeviceCodeTokenProvider $tokenProvider;
   private static GraphServiceClient $userClient;
   
   public static function initializeGraphForUserAuth(): void {
       GraphHelper::$clientId = $_ENV['CLIENT_ID'];
       GraphHelper::$tenantId = $_ENV['TENANT_ID'];
       GraphHelper::$graphUserScopes = $_ENV['GRAPH_USER_SCOPES'];
   
       GraphHelper::$tokenProvider = new DeviceCodeTokenProvider(
           GraphHelper::$clientId,
           GraphHelper::$tenantId,
           GraphHelper::$graphUserScopes);
       $authProvider = new BaseBearerTokenAuthenticationProvider(GraphHelper::$tokenProvider);
       $adapter = new GraphRequestAdapter($authProvider);
       GraphHelper::$userClient = GraphServiceClient::createWithRequestAdapter($adapter);
   }
   

4. Replace the empty initializeGraph function in main.php with the following.

   function initializeGraph(): void {
       GraphHelper::initializeGraphForUserAuth();
   }
   

This code loads information from the .env file, and initializes two properties, a DeviceCodeTokenProvider object and a GraphServiceClient object. The DeviceCodeTokenProvider object will be used to request an access token, and the GraphServiceClient object will be used to make calls to Microsoft Graph.

Test the device code flow

Next, add code to get an access token from the GraphHelper.

1. Add the following function to the GraphHelper class.

   public static function getUserToken(): string {
       return GraphHelper::$tokenProvider
           ->getAuthorizationTokenAsync('https://graph.microsoft.com')->wait();
   }
   

2. Replace the empty displayAccessToken function in main.php with the following.

   function displayAccessToken(): void {
       try {
           $token = GraphHelper::getUserToken();
           print('User token: '.$token.PHP_EOL.PHP_EOL);
       } catch (Exception $e) {
           print('Error getting access token: '.$e->getMessage().PHP_EOL.PHP_EOL);
       }
   }
   

3. Build and run the app. Enter 1 when prompted for an option. The application displays a URL and device code.

   $ php main.php
   
   PHP Graph Tutorial
   
   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   1
   To sign in, use a web browser to open the page https://microsoft.com/devicelogin and
   enter the code RB2RUD56D to authenticate.
   

4. Open a browser and browse to the URL displayed. Enter the provided code and sign in.

   Important

   Be mindful of any existing Microsoft 365 accounts that are logged into your browser when browsing to https://microsoft.com/devicelogin. Use browser features such as profiles, guest mode, or private mode to ensure that you authenticate as the account you intend to use for testing.

5. Once completed, return to the application to see the access token.

   Tip

   For validation and debugging purposes only, you can decode user access tokens (for work or school accounts only) using Microsoft's online token parser at https://jwt.ms. This can be useful if you encounter token errors when calling Microsoft Graph. For example, verifying that the scp claim in the token contains the expected Microsoft Graph permission scopes.

Get user

• 15 minutes remaining

In this section you will incorporate the Microsoft Graph into the application. For this application, you will use the Microsoft Graph SDK for PHP to make calls to Microsoft Graph.

1. Add the following code to the GraphHelper class.

   public static function getUser(): Models\User {
       $configuration = new UserItemRequestBuilderGetRequestConfiguration();
       $configuration->queryParameters = new UserItemRequestBuilderGetQueryParameters();
       $configuration->queryParameters->select = ['displayName','mail','userPrincipalName'];
       return GraphHelper::$userClient->me()->get($configuration)->wait();
   }
   

2. Replace the empty greetUser function in main.php with the following.

   function greetUser(): void {
       try {
           $user = GraphHelper::getUser();
           print('Hello, '.$user->getDisplayName().'!'.PHP_EOL);
   
           // For Work/school accounts, email is in Mail property
           // Personal accounts, email is in UserPrincipalName
           $email = $user->getMail();
           if (empty($email)) {
               $email = $user->getUserPrincipalName();
           }
           print('Email: '.$email.PHP_EOL.PHP_EOL);
       } catch (Exception $e) {
           print('Error getting user: '.$e->getMessage().PHP_EOL.PHP_EOL);
       }
   }
   

If you run the app now, after you log in the app welcomes you by name.

Hello, Megan Bowen!
Email: [email protected]

Code explained

Consider the code in the getUser function. It's only a few lines, but there are some key details to notice.

Accessing 'me'

The function builds a request to the Get user API. This API is accessible two ways:

GET /me
GET /users/{user-id}

In this case, the code will call the GET /me API endpoint. This is a shortcut method to get the authenticated user without knowing their user ID.

Requesting specific properties

The function uses the $select query parameter to specify the set of properties it needs.

Strongly-typed return type

The function returns a User object deserialized from the JSON response from the API. Because the code uses $select, only the requested properties will have values in the returned User object. All other properties will have default values.

List inbox

• 12 minutes remaining

In this section you will add the ability to list messages in the user's email inbox.

1. Add the following code to the GraphHelper class.

   public static function getInbox(): Models\MessageCollectionResponse {
       $configuration = new MessagesRequestBuilderGetRequestConfiguration();
       $configuration->queryParameters = new MessagesRequestBuilderGetQueryParameters();
       // Only request specific properties
       $configuration->queryParameters->select = ['from','isRead','receivedDateTime','subject'];
       // Sort by received time, newest first
       $configuration->queryParameters->orderby = ['receivedDateTime DESC'];
       // Get at most 25 results
       $configuration->queryParameters->top = 25;
       return GraphHelper::$userClient->me()
           ->mailFolders()
           ->byMailFolderId('inbox')
           ->messages()
           ->get($configuration)->wait();
   }
   

2. Replace the empty listInbox function in main.php with the following.

   function listInbox(): void {
       try {
           $messages = GraphHelper::getInbox();
   
           // Output each message's details
           foreach ($messages->getValue() as $message) {
               print('Message: '.$message->getSubject().PHP_EOL);
               print('  From: '.$message->getFrom()->getEmailAddress()->getName().PHP_EOL);
               $status = $message->getIsRead() ? "Read" : "Unread";
               print('  Status: '.$status.PHP_EOL);
               print('  Received: '.$message->getReceivedDateTime()->format(\DateTimeInterface::RFC2822).PHP_EOL);
           }
   
           $nextLink = $messages->getOdataNextLink();
           $moreAvailable = isset($nextLink) && $nextLink != '' ? 'True' : 'False';
           print(PHP_EOL.'More messages available? '.$moreAvailable.PHP_EOL.PHP_EOL);
       } catch (Exception $e) {
           print('Error getting user\'s inbox: '.$e->getMessage().PHP_EOL.PHP_EOL);
       }
   }
   

3. Run the app, sign in, and choose option 2 to list your inbox.

   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   2
   Message: Updates from Ask HR and other communities
     From: Contoso Demo on Yammer
     Status: Read
     Received: Mon, 18 Apr 2022 14:24:16 +0000
   Message: Employee Initiative Thoughts
     From: Patti Fernandez
     Status: Read
     Received: Mon, 18 Apr 2022 13:52:03 +0000
   Message: Voice Mail (11 seconds)
     From: Alex Wilber
     Status: Unread
     Received: Wed, 13 Apr 2022 02:30:27 +0000
   Message: Our Spring Blog Update
     From: Alex Wilber
     Status: Unread
     Received: Tue, 12 Apr 2022 16:46:01 +0000
   Message: Atlanta Flight Reservation
     From: Alex Wilber
     Status: Unread
     Received: Mon, 11 Apr 2022 13:39:10 +0000
   Message: Atlanta Trip Itinerary - down time
     From: Alex Wilber
     Status: Unread
     Received: Fri, 08 Apr 2022 18:36:01 +0000
   
   ...
   
   More messages available? True
   

Code explained

Consider the code in the getInbox function.

Accessing well-known mail folders

The function passes /me/mailFolders/inbox/messages to the request builder, which builds a request to the List messages API. Because it includes the /mailFolders/inbox segment, the API will only return messages in the requested mail folder. In this case, because the inbox is a default, well-known folder inside a user's mailbox, it's accessible via its well-known name. Non-default folders are accessed the same way, by replacing the well-known name with the mail folder's ID property. For details on the available well-known folder names, see mailFolder resource type.

Accessing a collection

Unlike the getUser function from the previous section, which returns a single object, this method returns a collection of messages. Most APIs in Microsoft Graph that return a collection do not return all available results in a single response. Instead, they use paging to return a portion of the results while providing a method for clients to request the next "page".

Default page sizes

APIs that use paging implement a default page size. For messages, the default value is 10. Clients can request more (or less) by using the $top query parameter. In getInbox, this is accomplished with the queryParameters->top property in the query parameters.

Getting subsequent pages

If there are more results available on the server, collection responses include an @odata.nextLink property with an API URL to access the next page. The PHP SDK exposes this as the getOdataNextLink method on collection request objects. If this method returns a non-empty string, there are more results available. For more information, see Page through a collection using the Microsoft Graph SDKs.

Sorting collections

The function uses the $orderby query parameter to request results sorted by the time the message is received (receivedDateTime property). It includes the DESC keyword so that messages received more recently are listed first.

Send mail

• 8 minutes remaining

In this section you will add the ability to send an email message as the authenticated user.

1. Add the following code to the GraphHelper class.

   public static function sendMail(string $subject, string $body, string $recipient): void {
       $message = new Models\Message();
       $message->setSubject($subject);
   
       $itemBody = new Models\ItemBody();
       $itemBody->setContent($body);
       $itemBody->setContentType(new Models\BodyType(Models\BodyType::TEXT));
       $message->setBody($itemBody);
   
       $email = new Models\EmailAddress();
       $email->setAddress($recipient);
       $to = new Models\Recipient();
       $to->setEmailAddress($email);
       $message->setToRecipients([$to]);
   
       $sendMailBody = new SendMailPostRequestBody();
       $sendMailBody->setMessage($message);
   
       GraphHelper::$userClient->me()->sendMail()->post($sendMailBody)->wait();
   }
   

2. Replace the empty sendMail function in main.php with the following.

   function sendMail(): void {
       try {
           // Send mail to the signed-in user
           // Get the user for their email address
           $user = GraphHelper::getUser();
   
           // For Work/school accounts, email is in Mail property
           // Personal accounts, email is in UserPrincipalName
           $email = $user->getMail();
           if (empty($email)) {
               $email = $user->getUserPrincipalName();
           }
   
           GraphHelper::sendMail('Testing Microsoft Graph', 'Hello world!', $email);
   
           print(PHP_EOL.'Mail sent.'.PHP_EOL.PHP_EOL);
       } catch (Exception $e) {
           print('Error sending mail: '.$e->getMessage().PHP_EOL.PHP_EOL);
       }
   }
   

3. Run the app, sign in, and choose option 3 to send an email to yourself.

   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   3
   
   Mail sent.
   

   Note

   If you are testing with a developer tenant from the Microsoft 365 Developer Program, the email you send might not be delivered, and you might receive a non-delivery report. If this happens to you, please contact support via the Microsoft 365 admin center.

4. To verify the message was received, choose option 2 to list your inbox.

Code explained

Consider the code in the sendMail function.

Sending mail

The function uses the $userClient->me()->sendMail() request builder, which builds a request to the Send mail API. The request builder takes a request body that contains the message to send.

Creating objects

Unlike the previous calls to Microsoft Graph that only read data, this call creates data. To do this with the client library you create an associative array representing the data, set the desired properties, then send it in the API call. Because the call is sending data, the POST method is used instead of GET.

Optional: add your own code

• 5 minutes remaining

In this section you will add your own Microsoft Graph capabilities to the application. This could be a code snippet from Microsoft Graph documentation or Graph Explorer, or code that you created. This section is optional.

Update the app

1. Add the following code to the GraphHelper class.

   public static function makeGraphCall(): void {
       // INSERT YOUR CODE HERE
   }
   

2. Replace the empty makeGraphCall function in main.php with the following.

   function makeGraphCall(): void {
       try {
           GraphHelper::makeGraphCall();
       } catch (Exception $e) {
           print(PHP_EOL.'Error making Graph call'.PHP_EOL.PHP_EOL);
       }
   }
   

Choose an API

Find an API in Microsoft Graph you'd like to try. For example, the Create event API. You can use one of the examples in the API documentation, or create your own API request.

Configure permissions

Check the Permissions section of the reference documentation for your chosen API to see which authentication methods are supported. Some APIs don't support app-only, or personal Microsoft accounts, for example.

• To call an API with user authentication (if the API supports user (delegated) authentication), add the required permission scope in .env.
• To call an API with app-only authentication see the app-only authentication tutorial.

Add your code

Add your code into the makeGraphCall function in GraphHelper.php.

Congratulations!

• 100% complete!

You've completed the PHP Microsoft Graph tutorial. Now that you have a working app that calls Microsoft Graph, you can experiment and add new features.

• Learn how to use app-only authentication with the Microsoft Graph PHP SDK.
• Visit the Overview of Microsoft Graph to see all of the data you can access with Microsoft Graph.

PHP Samples

• Laravel web app