Nova Audio Laravel Package

Getting Started

nova-audio is a Laravel Nova field that stores an audio file on a model attribute and renders an inline player (and upload control) inside the Nova UI. Version 3.0.0 adds Laravel 10 support, which in practice means it targets Nova 4.x and a modern PHP runtime — treat it as a Nova-4-era package.

Minimal steps:

1. composer require rhyslees/nova-audio (Nova itself must already be installed — it is a paid package and not pulled in by this one).
2. Make sure the model has a column to hold the file path:

   Schema::table('tracks', fn (Blueprint $t) => $t->string('audio')->nullable());
   

3. Use the field in the Nova resource:

   use RhysLees\NovaAudio\Audio;
   
   public function fields(Request $request): array
   {
       return [
           Audio::make('Audio'),
       ];
   }
   

4. Publish/refresh Nova's compiled assets after install (php artisan nova:publish or the package's own vendor:publish tag if it ships one) — the field's JS/CSS lives in the package's dist/ directory.

Where to look first: the package README for the exact field namespace and supported chainable options, then src/ for the field class to confirm inherited methods (it wraps Nova's file-upload behaviour), and dist/js/field.js if the player misbehaves. First real use case: attach a single MP3 to a resource, upload it in the Nova create form, and confirm it plays back in the detail view.

Implementation Patterns

• Single audio attribute per field. The field maps to one string column. For multiple clips, add several fields/columns (e.g. intro_audio, full_audio) rather than trying to store an array.
• Disk and path chaining. Pass through the standard file-field options (->disk('s3'), ->path('audio/'.$this->resource->id), ->storeAs(fn () => Str::slug($this->title).'.mp3')) so uploads land where your app expects and URLs remain stable.
• Nullable / optional media. Pair with ->nullable() and a ->help() hint so editors can leave the field empty; guard playback in the frontend with @if ($track->audio).
• Display vs editing. Use ->exceptOnForms() for fields populated by an importer/job, and ->readonly() where the audio is generated server-side. Use ->hideFromIndex() if you don't want players rendered in the resource table.
• Validation belongs on the field. Constrain uploads at the Nova layer: ->rules('mimes:mp3,wav,ogg', 'max:20480'). The browser player is far pickier than the validator, so validate codecs you know play everywhere.
• Storage visibility. For S3/Spaces, the field needs a publicly resolvable URL (public disk or a signed/temporary URL). Configure config/filesystems.php and the field's disk consistently; a private disk without URL signing produces silent players.
• Policies and authorization. File uploads bypass model observers you might rely on, so gate the field with ->canSee(fn () => $request->user()->can('update', $this->resource)) where media rights matter.
• Deployment workflow. Treat the package's frontend assets like any other Nova custom field: publish them during deploy, and re-publish after every Composer update — stale dist assets are the single most common "upgrade did nothing / field broke" cause.

Gotchas and Tips

• 3.0.0 is a major bump. The changelog only advertises Laravel 10 support, but a 2.x → 3.x jump can rename namespaces, asset handles, or drop older Nova/PHP support. Read the diff (2.0.2...3.0.0) before upgrading a production app, and pin ^2.0 if you are still on Nova 3 / Laravel 9.
• Laravel 10 implies Nova 4. If you are on Laravel 10 but an old Nova release, this field will not be the thing that breaks first — verify Nova's own compatibility matrix, not just Laravel's.
• Browser codec reality. The inline player is an HTML5 <audio> element; .mp3 and .m4a are safe, .wav is large but fine, .ogg/.opus is patchy on older Safari. If a file uploads but nothing plays, test the stored URL directly in a browser tab before blaming the field.
• 403/404 on the audio source is almost always disk visibility, a missing storage:link, or a path mismatch after renaming the column — check the Network tab, not the PHP logs.
• PHP upload limits beat Nova validation. upload_max_filesize / post_max_size truncate large audio before max: rules run, producing confusing "file is required" errors instead of a size message.
• Don't stack a plain File::make() on the same attribute. Two fields writing one column will fight over the stored path; pick one.
• Asset publishing is not automatic. After composer update, run php artisan nova:publish (and any package publish tag) and hard-refresh the browser; cached mix/vite manifests in Nova can serve the old field JS.
• Extension points are thin. The field inherits Nova's file-field behaviour, so custom naming, disk, and path usually come from chainable methods on the field rather than subclassing. If you need bespoke behaviour (transcoding, waveform previews, multiple files), subclass the field and override component/resolveUsing, or wrap it in a custom tool — don't hack the vendored dist files, since upgrades overwrite them.
• Debugging tip. Set APP_DEBUG=true and inspect the field's props in the Vue devtools panel — the resolved file URL and disk are serialized there, which is the fastest way to see whether the problem is server-side storage or client-side rendering.