Statamic Instagram Feed Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and publish the config: php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>" (add --tag=config if the package registers tags).
• Open config/<package>.php first. As of 2.2.0 the config file is the source of truth for profiles: each entry is a named set of display options (source, limits, view/template, cache, formatting). The default profile should be present out of the box — copy it and rename rather than editing it in place.
• First use case: render the existing feed exactly as before (no profile argument) to confirm the upgrade is a no-op, then add a second named profile and render both on the same page:

<x-feed />                      {{-- default profile --}}
<x-feed profile="sidebar" />   {{-- new in 2.2.0 --}}

or, in a controller:

return view('dashboard', [
    'main'    => Feed::profile('default')->render(),
    'sidebar' => Feed::profile('sidebar')->render(),
]);

• Read the package README's "Profiles" section and the config file side by side — the config keys are the de facto API, and the changelog entry for #7 is the only thing that changed in 2.2.0.

Implementation Patterns

Named profiles as first-class configuration. Treat each profile as a reusable display definition, not an ad-hoc argument. Define them in config (or at runtime via whatever registration method the package exposes) and reference them by string from Blade, controllers, and routes. This keeps per-location differences (item count, markup, caching, trimming) out of your templates.

Multi-feed pages. The primary 2.2.0 use case: a page that surfaces several feeds (e.g. "latest news" plus "upcoming events" plus a sidebar ticker). Give each profile a distinct name, its own cache TTL, and its own view so you can style them independently without branching in one template.

// config/<package>.php
'profiles' => [
    'default' => [ /* unchanged, keeps BC */ ],
    'news'    => ['source' => 'https://example.com/news.rss', 'limit' => 5, 'cache' => 300],
    'sidebar' => ['source' => 'https://example.com/blog.rss', 'limit' => 3, 'cache' => 300, 'view' => 'feeds.compact'],
],

Route-driven profiles. If you expose feeds over HTTP, map a route parameter to the profile name and validate it against a whitelist (Rule::in(array_keys(config('<package>.profiles')))) so user input never reaches a config lookup directly.

Profile-scoped caching. Wrap each profile's fetch in its own cache key that includes the profile name. If the package already does this internally, verify it during review — a cache key that ignores the profile is the classic failure mode of this feature and produces feeds bleeding into each other.

Testing. Assert on rendered output per profile rather than on internal state: hit the page/endpoint, assertSee an item you know only belongs to that profile's source. For units, bind a fake HTTP client and confirm each profile requests only its own source exactly once. If the package ships a facade, Feed::fake()-style helpers (if present) are preferable to mocking the container.

Extension points. Prefer overriding the view per profile over subclassing the renderer. If you need custom post-processing, a decorator around the renderer that runs after the profile is resolved keeps upgrade risk low.

Gotchas and Tips

• Config caching is the #1 trap. New profiles added in config/<package>.php do not appear until you run php artisan config:cache again. Locally with config:cache disabled this is invisible; in production it looks like your new profile "doesn't exist".
• Unknown profile behaviour. Check what happens with profile="typo" — an exception is fine in development but should not become a 500 on a public page. Wrap it, whitelist it, or fall back to the default per your tolerance.
• Upgrade is intended to be backward compatible. 2.2.0 only adds a parameter; omitting it must resolve to the previous behaviour. Still, pin ^2.2 and run your feed tests after the bump, and republish/merge the config file if the package shipped a changed stub.
• Cache key collisions. After enabling a second profile, manually inspect the cache store (php artisan cache:clear then compare keys) to confirm profile names are part of the key. If they are not, disable caching for secondary profiles or wrap the package call in your own Cache::remember("feed:{$profile}:{$source}", ...).
• View resolution. If profiles can specify views, remember Laravel resolves them relative to resources/views and that view-name typos fail at render time, not at config load time. Prefer view('feeds.news') resolution checks in a test.
• Rate limits and external services. Two profiles pointing at the same upstream host double your request volume; keep per-profile TTLs sane and consider a shared fetch layer if the sources overlap.
• Debugging. php artisan tinker → dump the resolved config array for the package; php artisan config:show <package> gives the cached view. If output is stale after a deploy, it is almost always config cache or the feed cache, in that order.
• Extension points to prefer. Per-profile views and post-render transformation callbacks age well; overriding protected methods on the renderer does not. Re-check that contract on the next minor bump.