Microsoft Graph Api Laravel Package

Getting Started

• Install with composer require apility/microsoft-graph-api. Since this is a release candidate, pin it explicitly (e.g. "apility/microsoft-graph-api": "1.0.0-RC4") so a later RC doesn't silently change behaviour under you.
• Publish and review the package config first (php artisan vendor:publish — check the service provider for the actual tag; it varies), then map the config values to .env. You will typically need a tenant ID, client ID, and client secret from an Azure AD app registration.
• Register the app in the Azure portal, create a client secret, and grant admin consent for the Graph application permissions you need before writing any code. Most "it doesn't work" first-run problems are consent problems, not code problems.
• First use case: authenticate with client credentials and make one read call (e.g. list users or fetch the signed-in organisation). Once a token round-trip succeeds, layer your real use case (sending mail, reading a calendar, syncing users) on top.
• Where to look first: the published config file, the service provider bindings (to see what's resolvable from the container), and the package's client/service class — that's the surface you'll actually be calling day-to-day.

Implementation Patterns

• Resolve from the container, don't instantiate. Inject the client/service via constructor injection or resolve it from the container. This keeps you testable and lets the package manage token state for you.
• Own your token lifecycle. Client-credentials tokens should be acquired once and cached (the package usually handles this, but confirm). Don't request a fresh token per API call — you'll hit Azure AD throttling and add latency to every request.
• Wrap Graph behind your own service classes. Create thin domain services (MailService, CalendarService, UserSyncService) that depend on the package client. Your application code then depends on your interfaces, and you can swap endpoints, add retries, or mock in tests without touching call sites.
• Queue anything slow or bulk. Sending mail, large directory syncs, and file uploads belong in queued jobs. Combine with $select to keep payloads small and jobs fast.
• Use $select aggressively. Graph returns fat objects by default. Requesting only the fields you need is the single biggest performance win in day-to-day usage.
• Handle pagination explicitly. Collection endpoints return @odata.nextLink; loop until it's absent rather than assuming one page.
• Batch where it fits. Graph's $batch endpoint is useful for many small operations, but keep batches modest — one failing sub-request shouldn't sink a large job.
• Test with fakes. Fake the underlying HTTP layer (or the package's client) in feature tests, and assert on the request shape — endpoint version, $select, and payload — not just the response.

Gotchas and Tips

• 403 vs 401. A 401 is a token problem (wrong tenant, expired secret, bad scope). A 403 is almost always a permissions/consent problem — check that the app registration has the permission and that admin consent was granted.
• Application vs delegated permissions. These are not interchangeable. Client-credentials flows only work with application permissions; anything requiring a signed-in user needs a different auth flow entirely.
• Throttling is real. Graph returns 429 with a Retry-After header. Implement exponential backoff and honour that header; naive retry loops make throttling worse.
• Endpoint version matters. v1.0 and beta behave differently, and beta is explicitly unstable. Default to v1.0 and only opt into beta for specific features — don't let beta leak into everything.
• Token expiry edge cases. Cache tokens with a safety margin before expires_in; a token that expires mid-request produces confusing intermittent failures.
• Config caching bites. After changing .env values, run php artisan config:clear. Stale cached config is a classic "I changed the secret and it still fails" trap.
• Timestamps are ISO 8601 UTC. Don't hand Graph local datetimes; convert and be explicit about time zones, especially for calendar operations.
• Large files need upload sessions. Simple PUT uploads cap out around 4 MB; anything larger requires a resumable upload session.
• RC stability. As a release candidate, treat minor version bumps as potentially breaking. Read the changelog diff between RCs (the v1.0.0-RC3…RC4 compare link) before upgrading, pin the version in composer.json, and run your integration tests against a real tenant after each bump.
• Extension point. If the package's client doesn't expose an endpoint you need, check whether it lets you pass a raw request through — that's usually cleaner than forking, and keeps you upgradeable.