Filament Oembed Laravel Package

Getting Started

• Install with composer require awcodes/filament-oembed (v1.1.1 is the current patch line; ^1.1 is a safe constraint — the release notes are an empty changelog, so treat it as a bug-fix bump with no API changes).
• The package targets Filament v3 on PHP 8.1+/Laravel 10+. It pulls in an oEmbed client and resolves embed data server-side, so there is no JS SDK to configure.
• Add the field to a form. The entry point you want first is the OEmbed form component:

use Awcodes\FilamentOembed\Forms\Components\OEmbed;

OEmbed::make('video_url')
    ->label('Video')
    ->required();

• If the package registers a panel plugin in your version, add it in AdminPanelProvider::panel() via ->plugins([...]); if not, the component works standalone. Check vendor/awcodes/filament-oembed/README.md and src/ first — the component's public methods are the real API surface and are more reliable than the docs.
• Publish/compile Filament assets (php artisan filament:assets) if the preview relies on a Blade view with CSS, otherwise the iframe preview can render unstyled.
• First use case: a PostResource form with a "Video URL" field, a table column showing the provider/thumbnail, and a front-end Blade partial that renders the stored embed.

Implementation Patterns

• Store the URL, resolve on demand. Persisting the raw URL and resolving oEmbed at render time keeps data portable; persisting the resolved payload avoids repeated outbound calls but locks in stale markup when providers change. Pick one consciously.
• Form + preview loop. Use ->live(onBlur: true) plus afterStateUpdated() to trigger resolution only when the URL settles, rather than on every keystroke.
• Resource integration. Pair the field with a validation rule (->url(), ->rules(['url'])) and ->columnSpanFull() so long URLs don't break the grid layout.
• Table/infolist display. Render the embed through the package's view or a custom column callback that calls the resolver and HtmlStrings the result — don't store raw iframe HTML in a text column you might later echo unescaped.
• Actions and modals. The component works inside Action::form() and RelationManager forms, but the Livewire request budget grows: each resolve is an HTTP round trip. Wrap resolution in Cache::remember() keyed on the normalized URL.
• Provider allow-listing. Most oEmbed libraries let you restrict providers; do that in config (or in a wrapper service) so users can't point the resolver at arbitrary internal URLs — this is your SSRF boundary.
• Testing. Use Http::fake() with recorded provider responses and assert the field resolves and renders; the real endpoints are flaky in CI and rate-limited.
• Front end. Keep a Blade partial that accepts the stored URL and renders {!! $embed->code !!} so the admin preview and the public site share one resolution path.

Gotchas and Tips

• Outbound HTTP on save is the #1 pitfall. Slow or unreachable oEmbed endpoints stall the Livewire request. Set a short timeout, catch exceptions, and fail gracefully to "preview unavailable" rather than throwing inside save().
• Provider rot. Twitter/X and several others have moved oEmbed behind auth or changed response shapes; a patch release like v1.1.1 may be exactly that kind of fix. Smoke-test every provider you actually use after upgrading.
• Empty and malformed input. null, partial URLs, and unsupported hosts should short-circuit before the HTTP call — otherwise you get noisy exceptions in the log on every form render.
• Livewire re-render storms. Any component state change can re-resolve the URL. Guard with a cached payload and ->lazy(), and never resolve inside a getStateUsing() callback.
• Duplicate resolution. Preview-on-type plus resolve-on-save often means two identical requests. Resolve once, cache the result, and let both paths read it.
• Security. Third-party embed HTML is untrusted input. Escape stored URLs, allow-list iframe hosts, and avoid {!! !!} on anything a non-admin can write.
• Responsive embeds. oEmbed responses typically return fixed width/height. Wrap the iframe in an aspect-ratio container in your own CSS; the package won't solve layout for you.
• Asset/theme quirks. If previews look unstyled in a custom panel, re-run php artisan filament:assets after upgrading — patch bumps occasionally touch compiled views.
• Extension points. Prefer subclassing the field or wrapping the resolver in your own service bound in a service provider over editing vendor files; you keep upgrade paths clean when the next patch lands.
• v1.1.1 specifically. No documented changes beyond the compare link. Bump, run your test suite and one manual embed per provider, and there is no migration or config work to do.