Nova Filemanager Laravel Package

Getting Started

1. Require the package alongside Nova (it is a Nova tool, so laravel/nova must already be installed and working):

   composer require webid/nova-filemanager
   

2. The service provider is typically auto-discovered via extra.laravel.providers in the package composer.json. If Nova's tool sidebar doesn't show it, register the tool manually in app/Providers/NovaServiceProvider.php:

   use Webid\NovaFilemanager\NovaFilemanager;
   
   public function tools()
   {
       return [
           new NovaFilemanager,
       ];
   }
   

3. Publish any config/assets the package ships:

   php artisan vendor:publish --provider="Webid\NovaFilemanager\NovaFilemanagerServiceProvider"
   

   Look first at config/nova-filemanager.php (or whatever the published config is named) — that's almost always where the disk, root path, and visibility settings live. Confirm a filesystems.disks.* entry exists for the disk you point the tool at.

4. First use case: point it at the public disk, open the Nova sidebar, and use the file manager to upload a hero image or PDF, then verify the file appears under storage/app/public/ and is reachable via php artisan storage:link. This gives you a sanity check that disk resolution, permissions, and URL generation all work before you wire it into any fields.

5. Because the repository has no dependents and minimal stars, treat this as a code-read-first package. Before integrating, open vendor/webid/nova-filemanager/src/ and note: the tool class, the controller handling uploads/deletes, and the JS bundle. Understanding the controller is the fastest way to know what's actually supported.

Implementation Patterns

Standalone tool in the sidebar. The typical workflow is purely UI-driven: upload assets for content editors, create folders, rename/delete. Keep this restricted to trusted admin roles via Nova's canSee gate in NovaServiceProvider rather than relying on Nova auth alone.

Disk-per-environment config. Define separate disks (local, public, s3) and point the tool at the one appropriate for each environment. In production you likely want S3/R2; locally the public disk is fine. Keep these in config/filesystems.php and reference them by name from the published config.

Wiring uploads into resource fields. If the tool writes into a folder you also reference from a File/Image field, normalize the path convention (e.g. always store the relative path like uploads/hero.jpg, never the full URL). A common pattern:

File::make('Image')
    ->disk('public')
    ->path('uploads')
    ->storeOriginalName('original_name');

And keep the file manager's root aligned with the field's path() so editors see the same directory tree they're uploading to.

Programmatic integration. For anything beyond browsing, don't shell into the UI — use Laravel's Storage facade directly in your own Nova actions:

Storage::disk('public')->putFile('uploads', $request->file('upload'));

This is usually cleaner than trying to automate the package's controller endpoints.

Extending via custom Nova tools/actions. If the built-in UI lacks an operation (e.g., move-between-disks, bulk tagging), add a Nova Action to the relevant resource rather than patching the vendor package. Vendor patches get lost on composer update, and with low maintenance you should assume you'll be on your own for fixes anyway.

Gotchas and Tips

• Maintenance risk. With 1 star and 0 dependents, expect no upstream bug triage. Pin the version in composer.json ("webid/nova-filemanager": "1.*" or an exact tag) and keep your own git history of any local patches — ideally via a fork or a Composer vcs repository entry so composer install on CI reproduces your fixes.
• Nova version compatibility. Nova tools break across major Nova versions (asset compilation, tool registration API, Nova::script/Nova::style calls). Verify the package's composer.json (require block) explicitly lists a Nova version you run; Nova ships as a private Composer repo, so a loose constraint is a red flag.
• Disk and root path resolution. The most common failure is the tool writing to one disk/path while your File field reads from another. Log Storage::disk($disk)->path('') in a Tinker session and compare it against the tool's configured root. Also confirm the configured disk's root exists and is writable by the PHP-FPM/queue user.
• Public URL vs relative path. Files uploaded to a public-disk subfolder are only reachable after php artisan storage:link. On S3, visibility => 'public' must be set on the disk and the bucket policy must allow public GET, or your url() calls will 403.
• Upload size and MIME limits. Nova tools frequently bypass your UploadedFile validation if the controller doesn't re-check. Enforce upload_max_filesize/post_max_size in PHP, and add a mimes/max rule in your own action or middleware if content editors are uploading arbitrary files.
• Debugging the tool. Because it's mostly a JS bundle + controller, use the browser Network tab when uploads fail silently — you'll usually see a 413 (PHP limits), 419 (CSRF/session), or 403 (Storage permissions) rather than a Nova-formatted error. Tail storage/logs/laravel.log in parallel.
• Extension points to prefer. Nova's own Nova::script(), custom Tool classes, and Nova Actions are stable extension points. The package's internals are not a public API — treat any method you call from application code as something you may need to re-fork on update.
• Fallback plan. Given the maturity signals, budget for a swap: alternatives like novafilemanager-style tools or a small custom Nova tool wrapping Storage are easy to build (a page + a controller + a couple of endpoints) and give you full control over validation, disk choice, and authorization.