Matinee Laravel Package

Technical Evaluation

Architecture fit. Matinée is a Filament form field, not a media library. It occupies one narrow seam in the application: the authoring surface of the admin panel, plus exactly one model column. It registers no routes, ships no controllers, no storage disk abstraction, no queue jobs, and — critically — appears to perform no outbound HTTP at render time, resolving URLs by parsing the host against a provider contract and assembling an embed_url with http_build_query(). That makes it an authoring-time dependency with a blast radius confined to the panel and a single JSON column. Your public-facing site consumes only the stored JSON via a Blade component you are free to replace with your own markup. This is the favorable shape for a TPM: the package never becomes a runtime hard dependency of customer traffic.

Integration feasibility. High, but conditional on two prerequisites that must be scheduled as tasks, not footnotes:

1. Filament 4 or 5 on the target panel. Filament 3 users must pin Matinée 1.x, a divergent line best treated as legacy.
2. A custom theme with the vendor views added to Tailwind via @source '../../../../vendor/awcodes/matinee/resources/**/*.blade.php'. The README flags this as [!IMPORTANT]. It is the single most common place implementations stall, because teams without an existing custom theme must build one first.

After those, the field is a one-liner (Matinee::make('video')), the model needs a single cast ('video' => 'array'), and front-end work can be parallelized against a documented, stable JSON payload (url, embed_url, width, height, responsive, options).

Technical risk. The risks here are supply-chain and version-coupling, not runtime correctness.

Key questions for the maintainer / a timeboxed spike.

1. What is the compatibility policy across Filament majors — will 3.x continue to span 4 and 5, or fork per major?
2. Is the JSON schema a public contract with a migration path, or can key shapes drift between minors? (v3.1.2's "missing sizes" fix implies defensive reading is expected.)
3. Does the field ever make a server-side request to a provider's oEmbed endpoint, or is resolution purely URL parsing? This determines whether you inherit SSRF surface, rate limits, and latency.
4. What is the behavior when a stored provider is later removed from config — hard failure or graceful degradation?
5. Is there intent to add first-party providers, or is custom-provider authorship the sanctioned answer?

Integration Approach

Stack fit. Adopt only if the target admin is Filament 4 or 5. There is no adaptation path for Nova, Backpack, or hand-rolled Laravel admin — do not attempt one; a hand-rolled URL field plus a Blade partial is less work than bending this package. No database engine, queue, cache, or hosting constraints apply.

Migration path. Two scenarios with very different cost:

• Greenfield column — the cheap case. Add a nullable json column, add the cast, drop the field into the form. No backfill, no dual-write, no cutover. Estimate 0.5 day, plus theme setup if none exists.
• Existing video data — the expensive case. Legacy varchar URL columns, or rows where a youtube_url string and separate start_time integer already exist, require a one-way transform into the JSON shape. Realistically: write a backfill command that constructs {url, embed_url, width, height, responsive, options} per row, run it in dry-run mode against a production snapshot, verify a sample of 20–50 rows render correctly through <x-matinee::embed>, then keep the old column read-only for one release cycle before dropping. Estimate 3–5 days including verification and a rollback plan (retain the source column until the new render path is signed off in production).

Compatibility. Pin explicitly. Filament 4/5 → Matinée ^3.1.2; PHP floor ^8.2 is declared but 3.1.x history argues for testing on your exact PHP minor. Do not use a floating * constraint given 0 dependents — you are the only canary.

Sequencing. Order matters here because the theme prerequisite gates everything visual:

1. Spike (0.5 day). Branch environment, install, render one field with theme applied, confirm styling and one YouTube + one Vimeo round-trip. Kill criterion: theme work exceeds one day or the field fails on your Filament major.
2. Theme + design system alignment (0.5–1 day). Rebuild CSS, confirm the field respects your panel's density and dark mode.
3. Schema + cast (0.5 day). Migration, cast, model factory updates, seed data.
4. Backfill, if applicable (2–4 days). Command, dry run, sample verification, staged rollout.
5. Front-end render component (0.5–1 day). Start with <x-matinee::embed>, then decide whether to keep it or substitute your own markup for consent gating.
6. Consent / compliance layer (1 day). Add the nocookie option to the provider defaults and wrap embeds in your consent manager. Video embeds are a known GDPR/CCPA friction point; bake this in rather than retrofitting.

Total for greenfield: ~2–3 days including compliance. Existing-data migration: add 3–4 days.

Operational Impact

Maintenance. Expect near-zero routine maintenance and a low but non-zero upgrade tax. The package tracks Filament majors, so your real maintenance trigger is a Filament upgrade, not a Matinée release. Because 3.x supports two Filament majors simultaneously, that tax is currently deferred. Assign a named owner (a single developer is sufficient) and a review policy: read every patch diff before merging — one to two files, minutes of effort. Watch for the pattern seen in 3.1.1/3.1.2 where a fix ships a day apart from the release that introduced the issue; that argues for a short soak period on staging before production.

Support. No vendor SLA, no commercial support, community-only issue tracker. For an internal admin tool used by a bounded set of editors, that is usually acceptable. Establish an internal runbook covering: how to add a new provider, what the stored JSON shape is, how to debug a blank embed, and where the fork lives if you need it. Two translations (Italian, Spanish) already ship — if your editors work in other locales, budget a small i18n contribution or an override.

Scaling. Effectively a non-issue on the write side: form submissions are rare, human-paced, and involve no external calls or queues. Two scaling considerations on the read side:

• Listing pages. If an index table column renders many embeds inline, each is an iframe — that is a heavy page. Prefer a thumbnail or provider link in tables and reserve the embed component for detail pages.
• Iframe weight is the provider's, not the package's. YouTube/Vimeo embeds carry their own JS and cookies. The nocookie flag is your lever; consider lazy-loading (loading="lazy") in your wrapper.

Failure modes and responses.

Ramp-up. Very low. One developer, half a day to a day, with the README plus a short internal note. The concepts an engineer must hold are three: the JSON column contract, the provider interface (getId, getDomains, getOptions, convertUrl), and the theme @source requirement. No new infrastructure, no new runtime, no new mental model beyond Filament forms they already use.

Build-vs-buy verdict. At 22 stars, 0 dependents, and a single maintainer, the honest framing is: you are adopting a convenience wrapper worth perhaps 1–2 developer-days of saved effort, in exchange for a small ongoing dependency and a documented fork option. That trade is favorable for a greenfield Filament 4/5 panel where the field replaces bespoke code. It is not favorable if you are on Filament 3 (take 1.x as legacy or skip), if you have complex existing video data (the backfill dominates the value), or if your compliance posture requires full control over embed markup from day one — in which case take the stored-JSON idea and the provider interface, and implement the field yourself.