Nova Video Laravel Package

Technical Evaluation

Architecture fit. Nova-video is a deliberately thin package: a Nova form field that delegates all real behavior to two underlying libraries — mostafaznv/larupload (storage, naming, metadata, cleanup) and mostafaznv/laravel-video (FFmpeg conversions, poster extraction). That separation is the single most important architectural fact for a TPM, because it means the Nova field is not where the semantics live. Any estimate, risk assessment, or migration plan that treats this as "one small Nova field" is wrong by roughly 3x. The real footprint is three packages, a queue worker pool, an FFmpeg binary in the runtime image, and a storage disk with public/CDN access semantics.

Fit is strong if the organization is already a Laravel Nova shop on PHP 8.1+. It is a poor fit if Nova is incidental, if admin is built on something else, or if the team has no appetite for operating FFmpeg and queue workers. There is no managed-service escape hatch built in — the package commits you to in-house transcoding, and that is a strategic decision, not an implementation detail.

Integration feasibility. Mechanically straightforward and well-trodden for a Laravel team: Composer install, publish config tags, run larupload migrations, storage:link, nova:publish, attach the trait to the model, register Video::make('Video')->disk(...)->rules(...). A competent Laravel dev can run the 30-minute spike (upload a 20 MB MP4 through the Nova form, confirm inline playback, confirm a poster was generated, inspect the bucket) and get a genuine go/no-go signal the same day. The field is well-behaved with Nova conventions — onlyOnForms() / onlyOnDetail() split, readonly(), standard ->rules() — so it slots into existing resources without bespoke frontend work.

The realistic integration cost is not the field; it is the environment: FFmpeg on the PATH of the PHP-FPM user and the queue worker user, a dedicated media queue, worker timeouts sized to transcode duration, and upload limits reconciled across php.ini, nginx, and any load balancer. Budget a day for a greenfield environment, more if the platform is containerized and the base image needs rebuilding.

Technical risk. Concentrated, and mostly supply-side rather than technical:

• Single maintainer, 22 stars, 0 dependents. There is no downstream population stress-testing upgrades or filing bugs ahead of you. Effectively you are the QA function for this package.
• Three-package dependency chain. A break can originate in Nova, larupload, or laravel-video, and diagnosing which is a real skill. Pin all three.
• Nova major-version coupling. Nova field packages break across majors (frontend asset/Vite changes). Failure mode is a blank form, not an exception — it will not page anyone, it will just silently stop working after a Nova upgrade.
• Implicit platform commitment. FFmpeg + queue + storage is a durable operational obligation that is cheap to adopt and expensive to unwind once assets and editor workflows accumulate.
• Silent failure surfaces. Conversion failures leave the record intact with a playable file but no poster or no renditions. Without deliberate instrumentation, editors discover this before you do.

Apache-2.0 removes license risk entirely; the residual risk is operational and lifecycle, not legal.

Key questions.

1. Is Nova a strategic commitment for the next 18–24 months, or is admin a candidate for replacement? This package's value collapses if Nova goes.
2. Are we willing to own FFmpeg transcoding and a media worker pool indefinitely, or is Mux/Cloudflare Stream/MediaConvert the intended end state? If the latter, is this a deliberate interim or accidental lock-in?
3. What is the asset volume and egress forecast for 12 months, and who owns that line on the infrastructure budget?
4. Who is accountable for testing this field after every Nova upgrade, and is that in a runbook or just assumed?
5. Does the domain require video semantics outside admin (public API uploads, imports, seeders, console commands)? If yes, the adapter layer is mandatory, not optional.

Integration Approach

Stack fit. Requires Laravel Nova 4/5, PHP 8.1+ with fileinfo and gd/imagick, FFmpeg + ffprobe on the runtime path, a queue backend (Redis/SQS/database), a supervisor/systemd worker, and a storage disk — local with storage:link in dev, S3 or equivalent in production. If any of those are absent, the true adoption cost is building them, not installing the package. The most common fit gap is a PaaS filesystem (Heroku/Render/Fly) where storage/app is ephemeral and every uploaded asset — including the generated poster — is destroyed on deploy.

Migration path. There is no meaningful "migration" in the data sense; this is net-new capability on a resource that currently has no video field, or a replacement for ad-hoc File::move() code that should be deleted, not ported. The correct path is: spike on staging → wrap → adopt one resource → reconcile → expand.

The wrapper is the highest-value architectural decision in the whole engagement. A thin MediaService / VideoPresenter between domain code and the package (exposing src, poster, duration from larupload accessors, always null-safe) costs an afternoon and converts a future move to a managed platform into a one-file change rather than a codebase-wide grep. It also gives you a testable seam so video behavior can be exercised without a Nova form.

Compatibility. Verify three version constraints before committing: Nova major ↔ field package, PHP ↔ larupload, and laravel-video ↔ your FFmpeg build. Register the published config tags explicitly in the deploy script rather than relying on interactive vendor:publish — publish tags drift between versions, and a missed tag means defaults silently win. Keep the path convention identical between local and S3 so URLs, tests, and seeders behave identically; the parity is what makes staging meaningful.

Two compatibility traps worth naming in the plan: S3 bucket CORS must allow GET/HEAD from both admin and public origins or the inline player fails with an opaque media error, and signed URLs must not be cached in a Blade view or a Nova index column.

Sequencing. Five steps, strictly ordered:

1. Environment proof first, before any package code. Confirm FFmpeg is visible to www-data and the worker user (sudo -u www-data ffmpeg -version), upload limits are reconciled across all three layers, storage:link is idempotent in the deploy pipeline, and a media queue worker exists with timeouts longer than your worst-case transcode. Ninety percent of the documented failure modes collapse into this step.
2. 30-minute spike on staging, on the real container image. Upload, play, poster, inspect bucket. Kill the initiative here if it doesn't work cleanly.
3. Build the adapter and a MediaResource. Nothing else consumes the package directly.
4. Adopt one low-traffic resource. Instrument job status visibly in the Nova field (a badge/status column) and give editors an explicit "regenerate" action rather than an FAQ entry.
5. Add the reconciliation command (media:reconcile --dry-run) and schedule it weekly before, not after, the orphaned-object bill arrives.

Operational Impact

Maintenance. This is the dominant ongoing cost and it is not the package's fault — it is the dependency chain's. Pin exact versions for the field, larupload, and laravel-video, and record the pin in an ADR. An unbounded ^1.0 constraint with a single maintainer and zero dependents is how an unrelated composer update breaks your admin panel during a sprint. Add "render the Nova video form" to the QA checklist for every Nova upgrade — the failure is a blank form, so nothing will alert you.

Support. The upside is real and is the reason to adopt: editors upload and swap videos without a deploy or a ticket, and you get a crisp acceptance criterion — "an editor can publish a video without engineering involvement." The cost is that a class of silent failures now surfaces as editor complaints rather than logs. Mitigate with visible job status in the field, alerting on queue:failed, and a short written playbook in the debugging order the docs already establish: (1) did the file land on disk? (2) did the job get picked up? (3) did it fail — queue:failed, laravel.log, FFmpeg stderr? (4) does the file exist but 404 — storage:link, visibility, CORS? That sequence resolves most incidents in minutes, but only if it is written down before the first incident.

Scaling. Two dimensions, both budgeted rather than engineered:

• Compute. FFmpeg pins roughly a core per concurrent job. A dedicated media queue and separate worker pool is mandatory — a 500 MB transcode must never compete with notification jobs. Set --tries=1 (retrying a deterministically broken input just burns CPU) and ensure retry_after exceeds the worker --timeout, or you get two FFmpeg processes racing on one file.
• Storage and egress. Video is where infrastructure cost arrives quietly and stays. Storage grows monotonically, egress scales with views, and the choice between public URL, CDN URL, and signed URL is a line item. Set Cache-Control at upload and reference a CDN host in the accessor from day one, so adding CloudFront later requires no model changes. Plan retention and deletion policy now — originals plus derived renditions is a multiplier, not a sum.

Failure modes, ranked by observed likelihood:

Ramp-up. The 30-minute spike is genuinely 30 minutes for someone who knows Laravel. The deeper ramp is the larupload semantics — entity accessors, naming methods, meta keys, styles — which is where roughly 80% of the real behavior lives and where the docs point you to a second package. Budget an afternoon for the adapter plus a day of environment work, and treat the "1–3 sprints of undifferentiated engineering" the field replaces as the honest comparison. The break-even is fast; the ongoing obligation is what the plan must state explicitly, because "and then it streams to customers" is the default scope-drift path from a working admin upload field.