- How do I install Matinee in a Laravel Filament app?
- Install it with composer require awcodes/matinee. If you use Filament Panels with a custom theme, add the package Blade views to your theme CSS using the @source path shown in the README. Then cast the JSON column on your model to array or json and add Matinee::make('video') to your form. The field stores data in that existing column rather than requiring a separate package table.
- Which Filament versions are compatible with awcodes/matinee?
- The compatibility table maps Matinee 1.x to Filament 3.x, Matinee 2.x to Filament 4.x, and Matinee 3.x to Filament 4.x and 5.x. This tight coupling means you should align package upgrades with your Filament upgrade plan. The v3.1.2 patch requires no config, asset, or migration changes, so a composer update is sufficient for that patch. Check the README compatibility table before major upgrades.
- How does Matinee store video data in the database?
- Matinee stores embed data as JSON in a single column on your model, so you must cast that column to array or json. As of v3.1.2 the payload includes presentation state such as a responsive flag plus optional width and height, not only the provider response. Because JSON payload shape can drift, use null-safe accessors and explicit casts when reading the data.
- How do I render a Matinee embed in a Blade view?
- Use the public x-matinee::embed Blade component as the documented rendering entry point. In v3.1.2 its sizing contract is stable and it branches on the stored responsive flag, so responsive embeds stretch to container width while fixed embeds use stored pixel dimensions. Pass the stored embed data to the component and ensure your theme includes the package views.
- Does Matinee support YouTube and Vimeo out of the box?
- Yes, Matinee ships with built-in YouTube and Vimeo providers. You can also add custom OEmbed providers by creating a class that implements MatineeProvider and uses the IsMatineeProvider trait. Pass your provider classes into the providers modifier on the Matinee field.
- How do I create a custom OEmbed provider for Matinee?
- Create a class implementing MatineeProvider and use the IsMatineeProvider trait. Implement getId to return a unique provider key, getDomains to list supported domains, and getOptions for provider options. Then pass the class into the providers modifier on Matinee::make('video'). This lets you support platforms beyond YouTube and Vimeo.
- What changed in Matinee v3.1.2?
- v3.1.2 fixes a defect where a stored embed missing width or height raised an undefined array key warning and rendered at size 0; it now falls back to 16:9. The stored payload now carries presentation state, including a responsive flag and optional dimensions, and rendering branches on that flag. It also prevents fixed-size embeds from silently flipping back to responsive when opened and saved. The patch requires no config, asset, or migration changes.
- Why do my Matinee embeds render full width after upgrading?
- Starting with v3.1.2, rendering honors the stored responsive flag instead of forcing full-width behavior. Embeds authored on 3.1.1 or earlier may carry a responsive value that no longer reflects editorial intent, so they can now render as responsive even if editors expected fixed sizing. Audit existing records and backfill responsive, width, and height values where needed. Also ensure fixed embeds have dimensions so the 16:9 fallback is not used unexpectedly.
- Can I use Matinee outside Filament with Livewire or Inertia?
- Matinee is designed specifically for Filament Panel and Form Builders and is not intended for non-Filament contexts such as standalone Livewire or Inertia apps. It relies on Filament's asset pipeline and custom theme setup for styling and Blade integration. For non-Filament use cases you would need a different OEmbed solution or considerable custom integration.
- How should I cache OEmbed requests and handle failures in Matinee?
- External OEmbed calls to providers such as YouTube and Vimeo can add latency and run into rate limits, so cache responses with Laravel's Cache facade where appropriate. Plan fallbacks for failed or deleted videos, and consider a retry or placeholder strategy so forms and rendered embeds degrade gracefully. For high-traffic pages, avoid calling provider APIs on every render and store enough provider data in the JSON column to render without a live request.