Nova File Manager Laravel Package

Getting Started

The package is a Nova tool, not a storage driver. It gives you a full-page file browser backed by any Laravel filesystem disk, and it talks to its own Nova vendor endpoints. The fastest path:

composer require oneduo/nova-file-manager

Register the tool in app/Providers/NovaServiceProvider.php:

use Oneduo\NovaFileManager\NovaFileManager;

public function tools()
{
    return [
        NovaFileManager::make(),
    ];
}

Publish and review the config:

php artisan vendor:publish --tag=nova-file-manager-config

The important settings are the disk, the base path inside that disk, allowed extensions, max upload size, and which operations are permitted. For a typical local setup:

// config/nova-file-manager.php
return [
    'disk' => 'public',
    'base_path' => 'uploads',
    // ...
];

Make sure the disk is usable:

php artisan storage:link

The web server user needs write access to storage/app/public (or the equivalent for your disk). After that, open Nova and look for the File Manager entry in the sidebar. The tool route is typically /nova/file-manager.

First use case: use it as a central asset library. Upload a logo under uploads/branding, copy the relative path (uploads/branding/logo.svg), and store that path in a resource column. Resolve the URL in your model or Nova field with Storage::disk('public')->url($path).

Implementation Patterns

Asset library + path column. The most common production pattern is to treat the tool as a CMS-style media library and store only relative paths in your models:

// migration
$table->string('hero_image')->nullable();

// model
public function getHeroImageUrlAttribute(): ?string
{
    return $this->hero_image
        ? Storage::disk('public')->url($this->hero_image)
        : null;
}

Then display it in Nova with a standard image/file field or a custom Text field. Avoid storing absolute URLs; the disk, domain, and CDN will change between environments.

Resource-level file picking. Recent versions ship a field wrapper so users can pick a file directly from a resource form instead of jumping to the tool. The shape is:

use Oneduo\NovaFileManager\Fields\FileManager;

FileManager::make('Attachment')
    ->disk('public')
    ->path('attachments');

Check the src/Fields directory of the installed version for the exact class name and supported chain methods. If your version does not include the field, use the tool as a separate tab and a normal Text field for the path.

One disk per environment, configured centrally. The config is the source of truth. Local can point at public, staging/production at S3 or another disk. Because the tool is global, every Nova user who can see it browses the same configured disk and base path. For role separation, gate the tool itself:

NovaFileManager::make()
    ->canSee(fn ($request) => $request->user()->isAdmin());

If you need separate roots for different teams, prefer separate disks (e.g. tenant-assets) or separate Nova installations over trying to make one static base path dynamic at runtime.

Directory conventions instead of database relations. The tool has no concept of your Eloquent models. Use a naming convention to keep things sane: uploads/{type}/{id}/... or uploads/{model}/{uuid}/.... Store the relative path in the model and treat the file manager as a dumb bucket. This keeps cleanup scripts and S3 lifecycle rules straightforward.

Programmatic operations stay in Laravel. For imports, jobs, and migrations, do not call the Nova tool's HTTP endpoints. Use Storage directly against the same disk and base path:

Storage::disk('public')->putFileAs(
    'uploads/imports',
    $uploadedFile,
    $filename
);

The package is a UI over Storage; mixing the two is unnecessary and brittle.

Upload constraints. Set max_upload_size and allowed_extensions in config, but also align PHP and the web server. A 20 MB config limit is meaningless if upload_max_filesize, post_max_size, or Nginx's client_max_body_size are lower. Put the lowest limit in the config so the UI fails fast with a validation error instead of a generic 413.

S3/private disk previews. Public disks work out of the box. Private S3 disks need signed/temporary URLs for previews and downloads. Configure the correct visibility and URL generation, and test previews for PDFs and videos specifically; those often fail when image previews succeed.

Gotchas and Tips

• Blank or broken UI after install/upgrade. Run php artisan nova:publish and php artisan config:clear. Nova caches assets and config aggressively.
• 403 versus 422 versus 500. A 403 from /nova-vendor/nova-file-manager/... usually means the tool's canSee/authorization denied the request. A 422 is validation (extension, size, path). A 500 is almost always storage permissions, a missing directory, or bad S3 credentials.
• The base path must be sane. The manager can create subfolders, but the configured root should exist and be writable. Leading/trailing slashes and empty-string base paths are a common source of "file not found" errors.
• Deletion is permanent. There is no trash or undo. Back up the disk, or use S3 versioning, before letting non-admins delete directories. A mistaken folder delete takes the whole subtree.
• Do not expose private disks casually. The tool's UI is not a per-file authorization layer. If a disk contains private documents, gate the tool with canSee, and consider a separate disk or a dedicated tool instance with a restricted base path.
• Store relative paths, not URLs. This is the single biggest integration mistake. Full URLs break when you switch to a CDN, change domains, or move between local and S3.
• Upload limits are layered. Check all four: the package config, php.ini (upload_max_filesize, post_max_size), the web server body limit, and any proxy/CDN limit. The smallest one wins.
• Filename edge cases. Spaces, unicode, and very long names can produce encoded URLs or truncated previews. Sanitize names on upload if you generate public links, or use UUID-based paths and keep the original name in the database.
• Nova version compatibility. The package tracks Nova 4/5. Pin the package version in composer.json and test after Nova upgrades; tool APIs and asset compilation occasionally shift.
• Multiple disks are a config/extension concern. If your version's UI lacks a disk switcher, don't fight the config at runtime. Register the disk you need or extend the tool/controller rather than mutating config per request.
• External uploads bypass the UI. If another process writes into the same disk, remember the file manager has no cache invalidation contract. Refresh the browser; if you add your own caching around listings, bust it after external writes.