Oauth2 Instagram Laravel Package

Product Decisions This Supports

• Channel roadmap: "Login with Instagram" / Instagram as an acquisition surface. Unchanged in shape: adding Instagram as an identity provider affects onboarding funnel design, account-linking UX, and whether Instagram sits in the MVP or a later phase. What changed is which Instagram surface we'd be building against — 3.0.0 commits the package to the Basic Display flow and explicitly drops the legacy api.instagram.com/v1 endpoints.
• Build vs. buy for OAuth adapters. Still a thin provider on top of league/oauth2-client, but the new custom Graph host configuration makes the "standardize on the League ecosystem" option slightly more attractive: a single abstraction can now be pointed at different Graph hosts (Google/Facebook/Instagram, or a version-pinned or proxied host) instead of forking per provider. The real decision remains "do we adopt League as our standard social-auth abstraction?" — not "Instagram, yes/no."
• Creator/influencer and UGC feature bets. Instagram OAuth is the prerequisite for media import, scheduled publishing, comment moderation, and insights dashboards. Because 3.0.0 targets Basic Display — a read-only, consumer-account flow — it unblocks media import and profile display only. Publishing, moderation, and insights require business/creator accounts and remain unaddressed. Roadmap scoping should reflect that gap rather than assume "Instagram is now supported."
• Marketing attribution and cross-property identity. Linking an Instagram handle to a user account enables audience segmentation, referral tracking, and creator-tier reporting — a data-model decision, not just an integration one. Note 3.0.0 narrows default scopes to ['user_profile'], and removes the getName() / getImageUrl() / getDescription() shorthands, so the resource-owner payload we can persist and join on is now narrower and must be re-specified in the data model.
• Support and compliance burden. 3.0.0 is a major version bump with removals — any spike or prototype built on 2.x breaks and needs re-validation. The security-review question is unchanged in kind, but the maintenance signal is now mixed: one new tagged release does not establish a cadence, and the package remains a single-maintainer, ~66-star, zero-dependent artifact. We own the code.
• Scope negotiation for the MVP. The custom-host hook materially lowers the cost of the reversible-spike strategy: we can ship a single-provider spike behind an internal SocialIdentityProvider interface, route the Graph host through configuration, and swap to a first-party or business-account adapter later without changing the interface.
• Vendor/API lifecycle risk is now explicit. The package moved to Basic Display at the same time Meta has been winding that surface down in favour of Instagram API with Instagram Login for business and creator accounts. That means the upgrade does not restore production relevance — it relocates the risk from "stale endpoints" to "endpoints nearing end of life." This is a decision input, not an engineering footnote.

When to Consider This Package

Consider it when:

• Your stack is already Laravel/PHP and already depends on league/oauth2-client; adding a provider is a one-line wiring change versus adopting a second auth library.
• You are starting fresh on 3.x and need the classic authorization-code flow against Instagram Basic Display for a prototype, internal tool, or a narrow read-only "connect your profile" feature — the exact use case 3.0.0 now targets.
• You want configurable Graph host routing so you can pin an API base, point at a proxy, or align the call path with other Graph-based providers.
• You are time-boxing a discovery spike and want to validate the Instagram funnel before committing engineering effort.
• You can pin the version, wrap it in your own adapter, and accept ownership of the code yourself.

Look elsewhere when:

• You need current Instagram API with Instagram Login (business and creator accounts), token refresh, webhooks, permission-scoped publishing, or insights — 3.0.0 does not add any of this, and Basic Display is itself being retired by Meta. Confirm the sunset status of Basic Display against current Meta docs before scoping the feature, not after.
• You are still on 2.x. 3.0.0 is a breaking major: the legacy api.instagram.com/v1 support and the getImageUrl() / getName() / getDescription() helpers are gone, and default scopes changed to ['user_profile']. Upgrading means re-testing every call site and re-checking your Meta app review scope justification.
• Your security or compliance review requires a maintained dependency with a demonstrated release cadence, security response, and an active maintainer. One release — however welcome — does not establish that. ~66 stars and zero dependents still means effectively no community backstop; you are the maintainer.
• You need production SLAs for token exchange failures, rate-limit handling, or long-lived token storage and revocation — 3.0.0 addresses none of these, and the host-config hook is not a substitute for version-pinning discipline.
• You are not on PHP/League already; pulling in this abstraction for one provider is not worth the surface area.

Bottom line: 3.0.0 is a genuine, overdue modernisation and it removes the "stale legacy endpoints" objection — but it re-bases the package onto a deprecated Instagram surface. Keep treating it as a reference implementation and spike tool, not a production dependency.

How to Pitch It (Stakeholders)

To executives: The picture improves slightly but the recommendation stands. A new 3.0.0 release modernised the adapter — it now targets Instagram Basic Display instead of the retired legacy API, and it adds a configuration point that lets us control which Graph host we talk to. That is real progress on a package that hadn't shipped in years, and it makes the "cheap experiment" framing more credible. The caveats are unchanged in substance: one release does not make this a supported vendor, and it lands us on a Meta API that is itself being wound down in favour of the business/creator login flow. Recommendation: fund the two-week spike, but re-scope it — the question is no longer "do these endpoints work?" but "which Instagram APIs are we actually permitted to use, and do we need business accounts?" Budget a small ongoing maintenance line (or a fork) if the channel proves out. Do not put it on the critical path of a committed launch.

To engineering: 3.0.0 is a breaking major — legacy API support and three InstagramResourceOwner shorthands are removed, default scopes narrowed to ['user_profile'], and Graph host is now configurable. If any spike code sits on 2.x, budget a re-validation pass; the removals will surface as fatal errors, not warnings. The host-config addition is the useful part: it gives us a clean seam for version pinning or an egress proxy and lets one League abstraction serve multiple Graph providers without a fork. It is still a thin AbstractProvider subclass, still single-maintainer with zero dependents, still ours to own. Wrap it behind our interface, pin the exact version, and verify Basic Display's sunset timeline against current Meta docs before we commit the roadmap item — that verification, not the code, is now the gating cost.

Decision requested: approve the spike and the interface abstraction; approve the 3.0.0 pin as the spike baseline; defer the production-adoption decision until the spike confirms which Instagram API surface is viable and we have a named maintenance owner.