Instagram Basic Display Php Laravel Package

Getting Started

• Read the README first, specifically the new v1.1.7 note. It documents that the Instagram Basic Display API is deprecated and points to the maintained replacement package: https://github.com/espresso-dev/instagram-php. Treat this as the package’s current migration guidance.
• For new integrations, do not start here. Install and evaluate the linked successor package instead. Use this package only if you are maintaining an existing Basic Display API integration that has not yet been migrated.
• If you must use it, confirm your Meta app still has Basic Display API access. Create or reuse a Meta app, add the Instagram Basic Display product, configure the OAuth redirect URI, and collect a client ID/secret.
• First use case to validate: complete the OAuth flow, exchange the authorization code for a short-lived token, exchange that for a long-lived token, then fetch the authenticated user’s profile and media. Use the README examples as the reference path before wiring anything into Laravel.

Implementation Patterns

• Keep the package behind an application service. Wrap OAuth and API calls in a dedicated InstagramClient or service class rather than calling package classes directly from controllers. This makes the eventual migration to espresso-dev/instagram-php much cheaper.
• Persist tokens per user and treat them as credentials. Store the long-lived access token encrypted, along with its expiry and the Instagram user ID. Never store tokens in plaintext logs or expose them in API responses.
• Use a scheduled refresh workflow. Long-lived Basic Display tokens expire, so schedule a command to refresh tokens before expiry and dispatch a job or event if refresh fails. Queue media syncs rather than doing them inline in web requests.
• Cache read-heavy responses. Profile and media endpoints are good candidates for short-lived caching, especially if you render Instagram content on public pages. Store the raw payload alongside your normalized model so you can debug mapping issues later.
• Plan migration as an adapter, not a rewrite. Define an internal interface for the operations you actually use, such as getProfile(), getMedia(), and refreshToken(). Implement it once with this package and once with the successor package, then switch bindings in the service container when ready.
• Handle rate limits and transient failures explicitly. Use Laravel’s HTTP client retry/backoff where applicable, and surface API errors as domain exceptions so controllers and jobs can react consistently.

Gotchas and Tips

• The deprecation is the main risk. The v1.1.7 README update is not a feature release; it is a warning that the underlying API is going away. Do not build new functionality on this package, and check Meta’s current Basic Display API timeline before committing to any legacy integration work.
• Token lifetimes are easy to get wrong. Short-lived tokens are exchanged for long-lived tokens, which still expire. Store expiry timestamps, refresh proactively, and do not assume a successful OAuth callback means you have a durable token.
• Redirect URI mismatches are a common failure. The redirect URI configured in the Meta app must exactly match the one used in the authorization request, including scheme, host, path, and trailing slash behavior.
• App review and test users can block you early. Basic Display API access often requires adding test users in the Meta dashboard before app review. If profile/media calls fail during development, verify app product configuration and user roles before debugging package code.
• Debug at the HTTP boundary. Log request URLs and raw response bodies with tokens redacted. Common errors are invalid or expired tokens, missing permissions, and redirect URI mismatches, not package bugs.
• Use the README link as the extension path. The successor package is the intended migration target. If this package lacks a needed extension point, such as custom token storage or response mapping, wrap it rather than patching vendor code, and prioritize moving to the linked package.