Laravel Instagram Feed Laravel Package

Getting Started

• Install with composer require cnrp/laravel-instagram-feed.
• Publish and run migrations/config: php artisan vendor:publish --tag=instagram-feed-config and php artisan vendor:publish --tag=instagram-feed-migrations (check README for exact tags), then php artisan migrate.
• Add Instagram OAuth credentials to .env / config/services.php or the package config: client ID, client secret, and redirect URI. The redirect URI must match exactly what is registered in the Meta/Instagram app.
• Register the package’s Filament plugin in your panel provider (e.g. ->plugin(InstagramFeedPlugin::make()) — confirm the class name in the README).
• Open the Filament admin panel, create an Instagram profile, and complete the OAuth connection flow.
• Trigger a feed fetch from the admin UI (or via the package’s documented action/command) and confirm media records and WebP conversions are stored.
• First use case: connect one profile, fetch its feed, then render the latest media on a public page by querying the package’s Eloquent models or using the documented front-end helper/component.

Implementation Patterns

• Use the Filament admin panel as the primary management surface: connect multiple Instagram profiles, re-authenticate when needed, and trigger feed refreshes manually.
• Model multiple profiles as separate records. Scope front-end queries by profile so different site sections can display different Instagram accounts.
• Fetch and store feed data, then render from your database rather than calling Instagram on every page load. This keeps page performance predictable and avoids hitting API limits.
• For public pages, query stored media records ordered by Instagram timestamp or fetched time, and use the stored/converted WebP URLs for rendering.
• If the package exposes actions or services, wrap feed fetching in your own queued job or scheduled command until built-in scheduling lands. This prevents admin requests from timing out on large feeds.
• Use the Filament resource for operational tasks (connect, refresh, inspect errors) and keep public-facing rendering in your own controllers/Blade/Livewire components.
• Cache rendered feed blocks or query results briefly if the same profile appears across many pages.
• When integrating with existing content, consider a polymorphic or config-based mapping between Instagram profiles and site sections rather than hard-coding profile IDs.

Gotchas and Tips

• Scheduled token refresh and feed fetching are explicitly planned, not included in v1.0.0. Plan to refresh tokens and fetch feeds manually or via your own scheduler/job until those features ship.
• Batch API/download support is not yet available. Large feeds may be slow or time out if fetched synchronously; run fetches in a queue where possible.
• WebP conversion is a core feature, but configurable compression and disabling conversion are planned. Until then, expect WebP output and verify storage/disk requirements.
• Hiding posts is planned but not available. If you need moderation now, add your own visibility flag or filtering layer around the package’s media records.
• OAuth redirect URI mismatches are a common failure point. Ensure the exact URI is registered in the Instagram/Meta app and matches the package config for every environment.
• Tokens can expire or be revoked. Without automatic refresh yet, build an operational habit of checking profile connection status in Filament and re-authenticating when needed.
• Check Filament version compatibility before installing. This package is Filament-integrated, so a major Filament upgrade may require a package update.
• Publish config and migrations first, and run php artisan storage:link if media is stored on the public disk.
• For debugging, inspect the Filament profile record’s auth/connection state, application logs around OAuth callbacks, and the stored media records after a fetch. Confirm whether failures happen at OAuth, API fetch, download, or conversion stage.
• Extension points are likely limited in this initial release. Prefer composing around the package’s models/services rather than modifying vendor code, and watch the README for published views/components as front-end customization matures.