Instagram Bundle Laravel Package

Getting Started

This is a Symfony2 bundle, not a Laravel package, so "getting started" in a Laravel app really means deciding whether you want to carry a Symfony DI shim into a Laravel codebase. For most teams the answer is no; treat this as a reference implementation of wiring Instaphp v2 into a container rather than something you composer require into app/Providers.

Minimal path if you proceed:

1. composer require ollieltd/instagram-bundle (pin it; the Instaphp v2 dependency is ancient and may not resolve cleanly on modern PHP — check composer why-not if install fails).
2. Look first at the bundle's DependencyInjection/ extension and Resources/config/services.yml — that is where the Instaphp client is constructed and which config keys (client ID, client secret, redirect URI, scopes) are injected.
3. Read the controller/example code shipped in the repo to see the intended auth dance (getLoginUrl, callback handling, token storage), because the bundle itself does little beyond service registration.
4. In Laravel, bypass the bundle entirely: register a singleton in a service provider that mirrors the services.yml construction and returns an Instaphp\InstagramAPI instance.

First use case to prove it works: authenticate a single account and fetch that user's recent media (/users/self/media/recent equivalent in Instaphp v2), then dump the raw response. Do not build on top of it until you have confirmed the HTTP layer actually reaches Instagram with a valid token — most failures here are auth/token issues, not bundle issues.

Implementation Patterns

Container bridging (Symfony intent). The bundle's value is a service definition that injects config into Instaphp v2. If you are in Symfony, enable the bundle in AppKernel, put credentials under the bundle's config key, and inject the service into your controllers/services by type-hint or service id.

Laravel adaptation. Since Laravel has no bundle/extension mechanism, reproduce it in a service provider:

$this->app->singleton(\Instaphp\InstagramAPI::class, function ($app) {
    $config = $app['config']->get('services.instagram');
    return new \Instaphp\InstagramAPI(
        $config['client_id'],
        $config['client_secret'],
        $config['redirect_uri'],
        $config['scope'] ?? ['basic']
    );
});

Then resolve it via constructor injection rather than app() calls, so you can swap a fake in tests.

Auth/token workflow. Typical pattern is a two-route flow: a "connect" route that redirects to the Instaphp-generated login URL, and a callback route that exchanges the code for an access token. Persist the token (and Instagram user id) in your own table — the bundle/Instaphp v2 does not give you durable token storage you should rely on. Treat tokens as user-owned data so you can support multiple accounts and re-auth.

Service-layer wrapper. Don't sprinkle Instaphp calls through controllers. Wrap it in a small InstagramClient service exposing domain methods (recentMedia($userId), userProfile($userId), like($mediaId)), and have that wrapper own the Instaphp instance, error mapping, and rate-limit backoff. This is the single most useful pattern because it isolates you from the library's array-heavy responses and from a future replacement.

Integration tips.

• Keep Instaphp objects out of queued job payloads (they aren't serializable); pass scalar ids/tokens instead.
• Cache read endpoints (profile, recent media) with a short TTL — legacy Instagram rate limits are strict and unhelpful when exceeded.
• Bind your wrapper to an interface in the container so a later migration to a maintained client is a one-line binding change.
• Route all outbound calls through Laravel's HTTP client or a Guzzle instance you configure, if you end up reimplementing the thin parts, rather than relying on the bundled transport.

Gotchas and Tips

• The API is the real problem. This wraps Instaphp v2, which targets Instagram's legacy API. That platform has been effectively retired for third-party read/write access. Verify current availability before scoping any work; for many endpoints this package cannot succeed regardless of correct usage.
• Symfony bundle in Laravel. You cannot register() a Symfony bundle the normal way. There is no auto-discovery, no config/instagram.php merge, no facade. Expect to copy configuration semantics out of DependencyInjection/Configuration.php by hand.
• Dependency resolution. Old bundles often pin symfony/* constraints and PHP versions that conflict with a modern Laravel skeleton. If Composer refuses, do not fight it — vendor the handful of relevant classes or, better, use a current Instagram client.
• Config quirks. Credentials are expected as constructor args from the DI extension. Missing redirect_uri or mismatched scopes produce opaque OAuth errors from Instagram rather than clear exceptions; log the outgoing authorize URL and compare it to the app's registered redirect URI exactly (scheme, trailing slash, port).
• Error handling. Instaphp v2 returns arrays and throws on HTTP errors in ways that are easy to miss. Wrap every call in try/catch, inspect the response body for meta.code, and translate to your own exceptions. Silent null/empty-array returns usually mean an expired token, not "no data".
• Token expiry. Instagram tokens expire and the library does not auto-refresh for you. Store expires_at, and add a scheduled job or middleware that flags accounts needing re-authentication.
• Debugging. Start at the transport: dump the resolved request URL and headers before blaming the bundle. Then check that the access token belongs to the account you think it does — cross-account mixups are common when tokens are cached in a single config value instead of per-user rows.
• Extension points. Realistically there are few. The service definition is the seam; override it (Symfony: services.yml/compiler pass; Laravel: container binding) to substitute your own client. Do not subclass the bundle's classes — they are thin and unstable.
• Maintenance signals. 10 stars, zero dependents, and an archived-style dependency mix mean no upstream fixes. Budget for replacing this within the project lifetime; keep it behind an interface from day one.