Filament Giphy Laravel Package

Getting Started

• Install with composer require the package and register the plugin on your panel in app/Providers/Filament/*PanelProvider.php via ->plugin(FilamentGiphyPlugin::make()). Without this the modal assets (giphy.css, JS) are never loaded and the picker will render unstyled or not at all.
• Publish the config (php artisan vendor:publish --tag=...giphy...config) early, before you build anything on top of it. From v1.0.1 the config contains grid_rendition, modal_icon and modal_icon_color; older published configs will be missing the icon keys and still default to the old rendition.
• Put your Giphy API key in .env and reference it from the config file rather than hardcoding — it's the one secret this package needs and it's easy to leak into a committed config.
• First use case: drop the Giphy field into a form schema (e.g. a cover_gif column on a Post resource), save a record, and confirm the saved value round-trips. Do this before wiring it into a rich editor, since the editor integration hides the stored value behind editor state.
• Where to look first when something's off: the published config (rendition + icon), the browser network tab for the Giphy API call, and the rendered data-giphy-* attributes on the saved figure — those tell you whether the problem is fetch-side or render-side.

Implementation Patterns

• Form field as the primary integration. Add the picker as a field in a resource form and store the selected GIF URL (plus whatever metadata you need) on the model. Treat the field as a normal Filament form component so validation, ->required(), and ->columnSpanFull() behave as expected.
• Config-first, fluent-second. Set panel-wide defaults in config/giphy.php (grid_rendition, modal_icon, modal_icon_color) and override per panel with FilamentGiphyPlugin::make()->modalIcon('heroicon-o-photo')->modalIconColor('warning'). Keep overrides in the panel provider so the intent is visible in one file.
• Rendition selection is a rendering decision, not a storage decision. grid_rendition (now fixed_width) only affects picker previews. Store the canonical/original URL for output and let the front end pick a size — do not persist the preview URL, or you'll be stuck with a 200px GIF as your hero image.
• Rendering saved GIFs. The rendered figure carries data-giphy-* creator attributes. If you need attribution or a credit line, read those attributes in your own Blade partial / JS rather than relying on the package's markup — v1.0.1 deliberately stopped rendering the caption.
• Masonry previews. Previews keep aspect ratio in a masonry grid, so don't fight it with fixed-height CSS on the modal body; constrain the results container instead if you need a different density.
• Editor integration. In a rich editor, the picker inserts a figure node; test that your editor's HTML sanitizer / strip_tags allowlist keeps data-giphy-* attributes and the <figure> wrapper, otherwise attribution data silently disappears on save.
• Custom modal chrome per panel. Multi-panel apps (admin vs. tenant) can use different icons/colors cheaply — this is the cleanest way to make the picker feel native in each context.

Gotchas and Tips

• Upgrade step is manual if you published the config. v1.0.1 does not migrate your published file. Set grid_rendition to fixed_width and add modal_icon / modal_icon_color, or you'll keep the blurrier previews and silently lose the new icon defaults.
• The creator caption is gone from the UI but the data remains. Behaviour changed at v1.0.1: no caption in the editor or the rendered figure, while data-giphy-* attributes persist. If you were relying on the caption for layout (spacing, <figcaption> styling), those styles are now dead. More importantly, check Giphy's current attribution requirements for your use case before shipping a UI with no visible credit — the data attributes give you the hook to add your own credit line.
• CSS is now self-contained (giphy.css). The picker no longer depends on your host Tailwind build, which is good — but it also means host Tailwind resets/preflight can still bleed into the modal. If styles look subtly wrong, scope a reset around the modal rather than editing package CSS.
• Asset caching after upgrade. Filament caches registered assets. After bumping the package, run php artisan filament:assets (and clear view/config cache) before debugging "my styles didn't change" — this is the most common false alarm.
• Scroll containment changed. Only the results area scrolls now and the picker fills the modal body. Any custom CSS you added to work around the old double-scroll behaviour should be removed; leaving it produces a squashed grid.
• Invalid rendition names fail quietly. Rendition keys are Giphy's (fixed_width, fixed_height, downsized, original, …). A typo yields missing/blank previews rather than an exception, so verify the network response when previews don't appear.
• API key and rate limits. Giphy rate-limits per key; in local dev with several devs behind one key you'll see intermittent empty results — check for a 429 before assuming a package bug.
• Debugging checklist: config published and current → plugin registered → assets rebuilt → API key present → network response has data → data-giphy-* present in saved markup. Working that list in order avoids chasing CSS for what is almost always config or assets.