Fuse Utilities Laravel Package

Getting Started

mitydigital/fuse-utilities is a companion package for Laravel Fuse applications — it bundles the small helpers, Blade components and asset/settings plumbing you'd otherwise re-implement in every Fuse build. Treat it as an internal-toolkit package rather than a standalone framework: it assumes a Fuse-style app (dashboard layout, Media Library integration, published config).

Minimal setup:

composer require mitydigital/fuse-utilities
php artisan vendor:publish --tag=fuse-utilities-config

Then confirm the service provider is auto-discovered (php artisan about or php artisan package:discover), clear caches, and open config/fuse-utilities.php first — that file is the map of everything the package does. The package's own README.md and the src/ tree are the next stop; there's no deep docs site, so the source is the documentation.

First use case: render a Fuse dashboard page that pulls an image out of the Media Library. In 6.2.0 that now works for assets on a private disk, not just public, so the same Blade component/helper serves both authenticated-user content and public marketing imagery.

For the new private-asset support specifically:

1. Add a private disk in config/filesystems.php (e.g. 'private' => ['driver' => 'local', 'root' => storage_path('app/private')]).
2. Point the package's asset/media config at that disk.
3. Verify the delivery route sits behind your auth middleware group and that php artisan storage:link is not required for the private path.

Implementation Patterns

Config-driven over code-driven. Nearly every behaviour (disk names, route prefixes, thumbnail sizes, cache TTLs) is a config key. In day-to-day work this means you rarely touch package classes — you change config, then php artisan config:clear. Keep environment-specific disk choices in .env (FUSE_ASSET_DISK=private) so local and production differ without code drift.

Blade-first integration. The intended workflow is composing Fuse pages out of the package's components and helpers inside your own layouts. Keep your app's Blade views thin: pass a model or media item in, let the package resolve URLs and markup. When you need to deviate, publish the package views rather than editing vendor/.

Public vs. private asset branching (new in 6.2.0). The main new pattern is a single render path that resolves to either a direct Storage::disk('public')->url() or a signed/authenticated route depending on the asset's disk. Practical rules:

• Store the disk name alongside the media record, not a fully-qualified URL; URLs for private assets are temporary and must be generated per request.
• Use short-lived temporary URLs for private assets and never cache them beyond their expiry — a cached 60-minute URL inside a 24-hour page cache will 403.
• For authenticated delivery, prefer a route that authorises against the model (policy or Gate::authorize) rather than relying on obscurity of the path.
• If you're behind a CDN, exclude private-asset routes from caching rules and add Cache-Control: private, no-store where appropriate.

Integrating with Spatie Media Library. Where the media conversions are defined, keep ->nonQueued() off the private path if you need synchronous thumbnails for authenticated previews; otherwise conversions land after the first request and the first render shows a placeholder.

Testing pattern. Use Storage::fake('private') and assert the route returns 403 for guests and 200 (with the correct Content-Type) for an authorised user. assertDownload() / assertStreamed() cover the common delivery paths. Add one test per disk configuration — this is where regressions from asset-related releases show up first.

Upgrade workflow. This is a fast-moving 6.x line. Pin to a minor range (^6.2), read the changelog on each bump, and run your asset tests before deploying — asset handling changes are the ones most likely to break silently.

Gotchas and Tips

• Private assets and caching are the big trap. Temporary URLs expire. Any page cache, HTTP cache, or Blade fragment cache that stores a rendered private URL will eventually serve a broken link. Cache the media reference, render the URL at request time.
• Symlinked storage confusion. Private assets deliberately bypass public/storage. If a link 404s, check whether your config is still pointing at the public disk after a config publish — stale published configs are the #1 cause of "the new feature doesn't work" reports.
• config:cache in production. Package config merged at boot is fine, but any env() call outside a config file returns null once cached. If private-asset behaviour differs between artisan serve and production, this is why.
• Middleware order. If you've customised the Fuse dashboard route group, confirm the asset delivery route inherits the same web + auth stack. A route registered without web loses session-based auth and silently serves 302s instead of files.
• Content-Disposition and filenames. Streamed private responses need an explicit filename and MIME type; without them browsers download response or render nothing for SVG/PDF. Set both at the call site.
• Debugging tip: php artisan route:list --path=<asset-prefix> quickly shows whether the delivery route exists, which middleware it carries, and whether a conflicting catch-all route is shadowing it.
• Extension points: publish the config and views; subclass or bind over the package's asset resolver if you need to swap in S3 presigned URLs (Storage::temporaryUrl() works on S3, so the private path generalises). Avoid editing vendor/ — the 6.x cadence will overwrite it.
• Keep an eye on the changelog. 6.2.0 is a feature addition with no stated breaking changes, but the asset layer is now doing disk abstraction — check any custom code that assumed public URLs are permanent before the next minor.
• Blade component naming collisions. If you've hand-rolled Fuse-style components under similar names, alias the package's components in a service provider rather than renaming yours; a rename ripple through every view is worse than one alias.