Audiofeedback For Filament Laravel Package

Getting Started

Package renamed in v1.4.0. You now install blemli/audiofeedback-for-filament (previously blemli/filament-audiofeedback). The plugin class, config key, translation namespace, routes and the audiofeedback_settings table are all unchanged — only the Composer package name and the published asset paths moved.

Fresh install:

composer require blemli/audiofeedback-for-filament
php artisan vendor:publish --tag=audiofeedback-config   # verify tag with `php artisan vendor:publish`
php artisan migrate                                     # creates audiofeedback_settings
php artisan filament:assets                             # publishes to public/{js,css}/blemli/audiofeedback-for-filament/

Migrating an existing app from v1.3.x:

composer remove blemli/filament-audiofeedback
composer require blemli/audiofeedback-for-filament
php artisan filament:assets
rm -rf public/js/blemli/filament-audiofeedback public/css/blemli/filament-audiofeedback

Then register the (unchanged) plugin class in your panel provider — no code edit should be required:

->plugin(\Blemli\AudioFeedback\AudioFeedbackPlugin::make())

Where to look first

1. config/audiofeedback.php — the config key is unchanged, so any overrides you already have keep working. This is where sound files, enable/disable defaults and behaviour live.
2. The audiofeedback_settings table — per-user/global toggles. Unchanged in this release, so existing rows survive the upgrade.
3. resources/lang/vendor/audiofeedback (or lang/vendor/audiofeedback) — translation namespace unchanged; your published overrides still apply.
4. The plugin class itself, for the list of Filament hooks (notifications, action success/failure, etc.) it attaches to.

First use case: switch the plugin on for one panel, open the panel in a browser, trigger a success notification or a table action, and confirm audio fires. If nothing plays, that is almost always either (a) a stale asset URL from the rename, or (b) browser autoplay policy — see below.

Implementation Patterns

Panel-scoped rollout. Register the plugin only on the panels where you want feedback (e.g. the operator/admin panel, not the customer-facing one). Because registration lives in the panel provider, you can stage it: enable on a staging panel first, then promote.

Config-driven sound mapping. Publish the config and point each event key at your own audio file rather than editing vendor assets. Keep your custom sounds somewhere stable (public/sounds/... or a disk URL) so a future package rename doesn't relocate them again — v1.4.0 is a good reminder that vendor-published asset paths are not a stable contract.

Per-user opt-out via the settings table. The package persists preferences in audiofeedback_settings. Treat that table as the source of truth and surface the toggle in your own profile/settings form (or the package's page, if it ships one) rather than inventing a parallel column. Because the table name didn't change, an upgrade preserves user choices — do not truncate it during the rename migration.

Deployment pipeline. Asset publishing is a build step, not a runtime step. Add php artisan filament:assets to your deploy script (after composer install, before php artisan optimize). Teams that previously relied on the old public/{js,css}/blemli/filament-audiofeedback/ path must update any .gitignore, CDN sync, or Docker COPY public/ assumptions.

Composer constraint hygiene. Pin the new name explicitly ("blemli/audiofeedback-for-filament": "^1.4"). If the old name lingers in composer.json — including anywhere in replace/provide blocks or a monorepo path repository — you'll get confusing "class not found" or "package not found" errors.

Local development. php artisan audiofeedback:install (check the exact signature with php artisan list) is the fast path for a dev machine. Note it no longer prompts you to star the repo, so it is now safe to run non-interactively in scripts and CI-style setup docs.

Uninstall/teardown. v1.4.0 fixed the uninstall command to also delete the published stylesheet directory. Use the package's uninstall command for clean removal instead of hand-deleting files — it now cleans up both public/js/... and public/css/....

Gotchas and Tips

The rename is the whole release. There are no new features. Everything in v1.4.0 is packaging: the Composer name and the asset output directory. Budget for a composer.lock churn and a CI cache invalidation, but expect zero application code changes.

Two packages, one namespace — don't install both. Because the namespace and plugin class are identical, having blemli/filament-audiofeedback and blemli/audiofeedback-for-filament installed simultaneously gives you duplicate class definitions and unpredictable autoload resolution. Always composer remove the old one first, then composer require the new one, then composer dump-autoload.

Stale assets are the #1 post-upgrade bug. The HTML will reference the new public/js/blemli/audiofeedback-for-filament/ path while the old directory still sits on disk, or the browser serves a cached older bundle. Fix in order: php artisan filament:assets, delete the old blemli/filament-audiofeedback directories, php artisan optimize:clear, then hard-reload (disable cache in devtools). Check the network tab for 404s on the JS/CSS before touching any PHP.

Config and translation caches. The config key and translation namespace are unchanged, so a cached config from v1.3.x remains valid — but php artisan config:clear after composer changes costs nothing and rules out a whole class of "settings are ignored" reports.

Browser autoplay policies will bite you. Audio playback requires a prior user gesture in most browsers. Sounds triggered on page load, on a polling refresh, or in a Livewire request that isn't user-initiated may be silently dropped. Validate against a real click-driven action, not an automatic one, before filing a bug against the package.

Silent failure modes. If audio doesn't play, test the asset URL by hand in the address bar. If the file downloads, the path is right and the problem is autoplay or the enabled/settings state; if it 404s, it's the rename. If it 403s, it's web-server permissions on the new public directory — a fresh directory created by filament:assets may not inherit your usual ownership.

Debugging the settings layer. Query audiofeedback_settings directly for the acting user before assuming a config problem. A global "enabled" default can mask a per-user row that disables sound.

Extension points. Prefer the published config and your own sound assets over editing anything under vendor/. If you need behaviour the plugin doesn't expose, check whether the plugin class binds a sound resolver or exposes Filament hooks you can decorate — that survives package renames, whereas a patched vendor file does not.

Watching for the next rename. v1.4.0 shows the package's identity can change without a semver-major signal on code. Keep your integration surface to: one composer require line, one ->plugin(...) registration, one published config file, and your own sound assets. Apps wired that way absorb renames in a single commit.