Statamic Instagram User Feed Laravel Package

Getting Started

This is a Laravel package for fetching and rendering a social feed (Instagram-style), shipped with an Alpine.js example component. Start with the vendor docs, not the code — 1.0.2 explicitly clarifies what differs from the free marketplace build, so confirm you're on the paid/pro version before debugging "missing" behaviour.

1. Install via Composer and publish config/assets: php artisan vendor:publish --tag=<package>-config (and -assets if the Alpine example is published).
2. Add your API credentials to .env (typically an access token / app ID / secret). The package reads these through config/<package>.php, not directly from env().
3. First use case: register the provided route or call the facade/service in a controller, then drop the Alpine example component into a Blade view to render the feed. The 1.0.2 fix means the component no longer throws on initial mount before the feed resolves — safe to use as-is.
4. Cache the feed response from day one. Feed APIs are rate-limited and slow; a Cache::remember() wrapper around the fetch call is the difference between a usable page and a 2s TTFB.

If you hit checkpoint_required, jump straight to the 1.0.2 docs section — it now documents the resolution (typically re-authenticating the account / clearing the checkpoint in the Instagram app and regenerating the token). Previously this was a support-ticket black hole.

Implementation Patterns

• Service-layer wrapping. Don't call the package directly from Blade. Wrap it in a small FeedService that returns a normalised array/collection, so you can swap the package, add caching, and test without hitting the network.
• Cache-first fetch with a refresh command. Pair the package with a scheduled php artisan feed:refresh command writing to cache (or a DB table). Controllers read from cache; the scheduler does the API call. This decouples user traffic from rate limits.
• Alpine component as a starting point, not a target. The bundled example (now fixed in 1.0.2) is a good reference for the fetch/render lifecycle but you'll want to extend it: loading states, empty state, error state, and pagination/"load more".
• Blade partial for the item template. Keep the markup for a single feed item in resources/views/partials/feed-item.blade.php and loop it — makes it trivial to restyle or switch to a Livewire/Inertia front end later.
• Config-driven token rotation. Store the access token in config backed by env; add a note in your .env.example. Token expiry is the #1 cause of "it worked yesterday" tickets.
• Feature-flag the free vs pro surface. Since 1.0.2 documents the delta from the marketplace (free) version, gate pro-only behaviour behind a config flag if you maintain both editions, so the same codebase/Blade views serve both.
• Integration tip: pair with a Feed model or repository if you need persistence (e.g. moderation, analytics). The package fetches; it doesn't store.

Gotchas and Tips

• checkpoint_required is an auth/account-state error, not a code bug. 1.0.2 adds docs for it; the fix is on the Instagram account side (confirm identity in the app, then reissue the token). Don't waste time in your HTTP client.
• Free vs pro confusion. 1.0.2's docs update is the first place to check whether a behaviour you expect is genuinely missing or simply a free-edition limitation. Read that section before filing issues.
• Alpine lifecycle. Prior to 1.0.2, the example component initialised the feed fetch before x-data was ready, throwing on undefined bindings. If you've forked the example, diff against the 1.0.2 version — the fix (guard the render / defer until fetch resolves) is worth backporting into your own components.
• Rate limits and 429s. Wrap fetches in retry-with-backoff and cache aggressively. Log the raw API response on failure; feed APIs return surprisingly helpful error payloads.
• Token/secret leakage. Never echo the access token into the rendered page or into the Alpine component's x-data. Pass only the resolved feed data from the server.
• Config cache. After changing .env credentials run php artisan config:clear — a stale config cache is a classic "why is it still using the old token" trap.
• Extension points. Override the feed-fetching class via the container binding or a config key (most packages of this shape allow a class override); this is cleaner than forking the vendor code and survives composer update.
• Version pinning. This is a young 1.x package (1.0.2), so pin to ^1.0 and read the changelog on every minor bump — the free/pro split makes "small" releases worth checking.