Instagram Laravel Package

Getting Started

1. Install and inspect. composer require andreyco/instagram. Then read, in order: README.md (the only usage docs), composer.json (PSR-4 namespace and PHP/extension requirements), and src/ — the client class plus the Exception/ directory. Look for an examples/ folder; it is the fastest way to see the intended OAuth loop.
2. Know what you are wiring up. This is a thin cURL wrapper around the legacy Instagram API (api.instagram.com), not the Facebook Graph/Basic Display API. That API was retired, so treat the package as legacy-maintenance tooling or a reference implementation, not something to build new features on.
3. Configure the client. The options array is the whole configuration surface:

   use Andreyco\Instagram\Client;
   
   $client = new Client([
       'client_id'     => env('INSTAGRAM_CLIENT_ID'),
       'client_secret' => env('INSTAGRAM_CLIENT_SECRET'),
       'redirect_uri'  => env('INSTAGRAM_REDIRECT_URI'),
       'scope'         => ['basic', 'public_content'],
   ]);
   

4. First use case — the OAuth handshake. Redirect the user to $client->getLoginUrl(), handle the callback, exchange the code for a token (getAccessToken($code); older docs/forks call it getOAuthToken()), persist the token + user id, then construct an authenticated client ('access_token' => $token) and call a cheap endpoint such as users/self to prove the flow end to end.

Implementation Patterns

Bind it once, inject it everywhere. A Laravel singleton keeps configuration in one place and makes the client swappable in tests:

// AppServiceProvider::register()
$this->app->singleton(Client::class, fn () =>
    new Client(config('services.instagram'))
);

Split the OAuth flow into two controllers. redirect() returns redirect()->away($client->getLoginUrl()); callback() exchanges the code, stores access_token (and user->id, user->username) on the user record, and redirects home. Never keep tokens in the session for long-lived use — persist them encrypted.

Per-user clients for multi-account apps. The singleton holds app credentials only; build a short-lived authenticated instance per request/job with the stored token, or call setAccessToken($token) before each batch.

Endpoint calls follow a resource/verb shape. Use get(), post(), delete() with a path and query array, and always read the data envelope:

$page = $client->get('users/self/media/recent', ['count' => 24]);
foreach ($page->data as $media) { /* ... */ }

Paginate with next_max_id, not offsets. Loop while $page->pagination->next_max_id is set, passing it back as max_id. Keep it as a string — casting to int truncates it and silently returns page one forever.

Cache reads, queue writes. Wrap feed/profile reads in Cache::remember() with a short TTL; push likes/comments/follows into queued jobs so a slow or rate-limited API never blocks a request.

Normalize errors at the boundary. Catch Andreyco\Instagram\Exception\ApiException, log code + message + endpoint, and convert to your app's domain exception. For anything the package does not wrap, check the raw response's meta->code because some versions return error payloads instead of throwing.

Test behind an interface. The client does its own cURL, so mocking is awkward. Define a small InstagramGateway contract, implement it with this client, and bind a fake in tests — this also gives you a migration seam when you move to the Graph API.

Gotchas and Tips

• The API is dead. The legacy endpoints this package targets stopped working years ago; even the successor Basic Display API was retired in December 2024. Any call will fail regardless of correct code. Confirm before debugging your integration.
• Unmaintained since 2017. No PHP 8 fixes, no security patches, zero dependents. Vendor/fork it if you must keep it, pin the exact version, and never rely on dev-master.
• Option key drift between forks. client_id/client_secret/redirect_uri in this package vs apiKey/apiSecret/apiCallback in cosenary/Instagram-PHP-API. Copy the keys from the README of the version you actually installed.
• Redirect URI must match byte-for-byte, including trailing slash and scheme, or the token exchange fails with an opaque error.
• Scopes are fixed at login. Adding a scope later requires the user to re-authorize; you cannot request it on a per-call basis.
• Sandbox mode looks like a bug. Apps in sandbox only see sandbox-authorized users, so feeds return empty data arrays while the call itself "succeeds." Check app mode before chasing pagination issues.
• Watch rate limits. Handle HTTP 429 and inspect rate-limit headers; add exponential backoff in the job layer rather than retrying inline.
• cURL/SSL issues are common on old stacks — stale CA bundles and verify_peer settings surface as generic transport exceptions, not API errors.
• Debug by capturing the wire format. Log the full request URL, HTTP status, and raw JSON body. If the client exposes a "last response" accessor, dump it; otherwise subclass the client and log inside the request method — that is also the cleanest extension point for retries and metrics.
• Token lifetime traps. Legacy tokens were long-lived but revocable by Instagram at any time, and the 2016 long-lived exchange endpoint is gone. Design for re-authentication instead of assuming permanence.