Laravel Microsoft Graph Laravel Package

Getting Started

The package (dcblogdev/laravel-microsoft-graph) is a thin, opinionated wrapper around Microsoft Graph: token storage + OAuth routes + a fluent HTTP client. Auto-discovery registers the service provider and the MsGraph facade, so the setup is mostly credentials and consent.

1. composer require dcblogdev/laravel-microsoft-graph
2. Publish the config: php artisan vendor:publish --tag=msgraph (fall back to --provider="Dcblogdev\MsGraph\MsGraphServiceProvider"). Populate the client ID, client secret, tenant ID and redirect URI — the env key names in the shipped config differ from the config keys (e.g. client_secret is fed by MSGRAPH_SECRET_ID), so read the published file rather than guessing.
3. Decide on a token store (database or cache). For database, publish and run the migrations — you get an msgraph_tokens table keyed to the authenticated user.
4. In Entra ID, register the redirect URI verbatim, add the delegated/application permissions you need, and grant admin consent for anything tenant-wide.

First use case: redirect the user to /msgraph/oauth, let /msgraph/oauth/callback land, then hit the API:

use Dcblogdev\MsGraph\Facades\MsGraph;

if (! MsGraph::isConnected()) {
    return redirect()->route('msgraph.oauth');
}

$me = MsGraph::get('me');

Protect your app routes with the package's MsGraphAuthenticated middleware (alias it in bootstrap/app.php on Laravel 11+/13). First places to look: config/msgraph.php, the MsGraph facade, the token model, and the v4 documentation added in 4.0.9 (PR #113).

Implementation Patterns

• Wrap the facade in your own service. MsGraph is static-ish and hard to fake. Put a GraphService/MicrosoftGraph class behind an interface, inject the facade, and expose domain methods (sendWelcomeMail, listDriveItems). Controllers stay clean and tests can swap a fake.
• Centralise the "connected" gate. A small middleware or base controller check — MsGraph::isConnected() → redirect to msgraph.oauth — keeps re-auth flows out of every action. On the way back, the callback only needs to redirect to your intended destination.
• Token lifecycle. Access tokens live ~1 hour; let the package refresh them by always going through MsGraph::get/post/... instead of pulling a raw token. Call refreshToken() explicitly in long-running jobs, and logout() on user disconnect (this also clears the cached/DB token — don't leave a stale cache key behind).
• Acting on behalf of another user. With the database store, tokens resolve from the authenticated user. The request methods accept a third argument for the token record — use that when queueing work that must run as a specific user rather than the currently logged-in one.
• OData querying. Pass $select, $filter, $top, $orderby, $expand as array keys on get(). Graph rejects unencoded $/spaces; keep filters in a builder helper rather than string-concatenating in controllers.
• Pagination. Responses carry @odata.nextLink. Loop on it (passing the full URL back into get()) inside a queued job, not a web request. Persist @odata.deltaLink if you need incremental sync.
• Batching. For bulk operations, POST to $batch with up to 20 sub-requests — one round trip, much lower 429 risk than N sequential calls.
• Mail. The package registers a msgraph mail transport; set MAIL_MAILER=msgraph and grant Mail.Send. This is the escape hatch for environments where SMTP is blocked, and it gives you the Graph send-and-save-to-Sent-Items behaviour for free.
• Folder/name arguments. Folder helpers accept an ID or a path name (root, /Inbox, nested paths). This is the area touched by the 4.0.9 variable rename — pass names directly instead of pre-resolving IDs.
• Testing. Fake at your wrapper boundary and assert on endpoint + payload. Any test that hits real Graph will be flaky (throttling, tenant-specific folder names) and slow.

Gotchas and Tips

• Authenticatable typing is the real breaking-ish change in 4.0.9. The user type was refactored from User/TestUser to Illuminate\Contracts\Auth\Authenticatable (PR #111). If you extended the token store, overrode a method, or type-hinted the concrete class, update your signatures. Normal facade usage is unaffected.
• $folderIdOrName rename (PR #110) is a bug fix — folder lookups now correctly honour name-or-ID. If you'd worked around it by resolving folder IDs manually before calling, simplify the code but re-verify against shared mailboxes, where folder paths differ from personal ones.
• Laravel 13.x support (PR #112) landed here. If you pin framework versions, confirm composer update actually pulls 4.0.9+ rather than resolving an older tag against L13.
• Redirect URI mismatch is the #1 "it just doesn't work". It must byte-match the Entra registration — scheme, host, trailing slash, port. Similarly, common vs a specific tenant ID changes consent and guest-account behaviour.
• Delegated vs application permissions. The package's default flow is authorization-code (user-delegated). Client-credentials needs a specific tenant ID, a .default scope, and no user in context — mixing the two produces opaque 401s.
• Scopes are additive and sticky. Adding a scope later requires re-consent; users must logout() and re-auth, or an admin must pre-consent in the portal. Plan the full scope list up front.
• 429 throttling is normal at scale. Honour Retry-After; in queued jobs ->release($seconds) instead of retrying immediately. Retrying blindly is how you get throttled into a multi-hour lockout.
• Graph returns arrays, not objects, and errors are arrays too. Wrap calls and log error.code plus the request-id response header — Microsoft support will ask for it.
• beta endpoints (MsGraph::setApiVersion('beta')) are the only path to some newer features, but they change without notice. Isolate beta calls so a breaking change is one file, not fifty.
• Extension points worth knowing: publish and own the config; swap token_store between database and cache; bind a custom token store implementation; override the package routes/middleware in your own route file if the built-in OAuth endpoints don't match your UX. The v4 docs added in 4.0.9 (PR #113) are the current reference — older blog posts and v2/v3 snippets frequently reference renamed variables and config keys.