Nova Filemanager Laravel Package

Getting Started

• Version positioning: v5.0.0 is primarily a Nova 5 compatibility release. The notes do not advertise new end-user features, so treat it as an upgrade/compatibility line rather than a feature release. Use ^5.0 with Nova 5; stay on ^4.1 for Nova 4.
• Install: composer require clevyr/nova-filemanager:^5.0, then confirm the package’s PHP/Laravel/Nova constraints before upgrading an existing app.
• Register the Nova tool: add the package tool to tools() in app/Nova/NovaServiceProvider.php using the class named in the package README (commonly Clevyr\NovaFileManager\NovaFileManager—confirm the exact class for your installed version).
• Configure first: publish the package config/assets per the README, then point the tool at a dedicated Laravel filesystem disk in config/filesystems.php. Keep the configured root narrow, e.g. an assets disk rooted at assets/, not the whole app or storage root.
• First use case: give content editors a Nova sidebar “File Manager” for uploading and organizing images/documents on a dedicated disk, then reference the stored relative path from Nova File/Image fields or your own resource fields. Run php artisan storage:link if using the public disk.

Implementation Patterns

• Disk-per-domain: create separate disks/roots for distinct content areas (assets, documents, tenant-{id}) rather than one broad manager. This limits blast radius and makes permissions, backups, and URLs easier to reason about.
• Tool visibility as authorization: register the tool conditionally or override canSee()/use Nova gates so only trusted admins/editors see it. The file manager generally grants access to the configured disk/root, not per-model policies.
• Resource workflow: upload through the tool → copy/select the relative path → save that path on the Eloquent model → resolve URLs with Storage::disk(...)->url($path) or your existing accessor. If the package version exposes a file-selection field, use it; otherwise keep a simple path field and validate it server-side.
• Asset replacement: prefer versioned or timestamped filenames for replaced assets so cached URLs and published content do not break. Treat the file manager as storage, not as a model-aware asset library.
• Multi-tenant separation: avoid a single global root. Use per-tenant disks/roots where possible. If the package does not support dynamic roots per user, use a custom tool subclass/config or separate tool registrations rather than relying on UI restrictions alone.
• Deployment/upgrade workflow: stage the Nova 5 upgrade, publish and diff config, clear caches, rebuild/publish Nova assets if needed, then smoke-test upload, preview, rename, delete, and URL generation on the target disk.

Gotchas and Tips

• Major-version coupling: v5 targets Nova 5. Do not install it on a Nova 4 app. The release notes are deliberately terse; read the full changelog and test since “general house-keeping” can include dependency/asset/config changes without feature callouts.
• Not per-file ACL: tool access typically means access to the configured disk/root. Restrict the root, use canSee/gates, and consider filesystem-level permissions or a read-only disk where deletes should not be possible.
• Public URL pitfalls: public-disk previews require storage:link and correct visibility. On S3/private disks, previews can fail because of signed URLs, CORS, or visibility settings—test preview and download behavior, not just upload.
• Deletes are real: assume no recycle bin. Back up the disk, restrict delete access, and remember the tool does not know which Eloquent records reference a file.
• Large directories: huge roots and S3 listing can be slow/costly. Keep roots organized and test pagination/listing behavior before pointing it at a large bucket.
• Path safety: never configure /, the app root, or a broad storage root. Watch symlinks and path traversal assumptions; verify the resolved disk root in staging.
• Upload limits: failures are often PHP/webserver limits (upload_max_filesize, post_max_size, proxy body limits, timeouts), not the package. Check browser network responses and Laravel logs.
• Debugging: verify disk behavior independently with Storage::disk('...')->allFiles() in Tinker; inspect the tool’s network requests in the browser; after config changes run php artisan config:clear and, if assets are stale, the appropriate Nova/package publish command.
• Extension point: prefer a small custom Nova tool subclass for menu label, canSee, or config overrides; use custom filesystem disks/drivers for storage behavior. Avoid patching vendor files.