Nova Filemanager Laravel Package

Getting Started

Install and register the tool

composer require stepanenko3/nova-filemanager

Because the package is small (16 stars, single maintainer, last release March 2024), verify compatibility before committing:

composer show stepanenko3/nova-filemanager   # check nova/framework constraints
php artisan about                            # confirm Nova + Laravel versions

Then publish whatever the package exposes and inspect what landed:

php artisan vendor:publish --provider="Stepanenko3\NovaFileManager\ToolServiceProvider"

Open config/nova-filemanager.php (name may vary — check src/ if the publish command produces nothing). This is the first place to look: it defines which filesystem disks are browsable and the tool's path prefix.

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

use Stepanenko3\NovaFileManager\FileManager; // confirm actual class from src/

public function tools()
{
    return [
        new FileManager(),
    ];
}

Then php artisan optimize:clear and reload /nova. You should see a File Manager entry in the sidebar.

First use case: admin-only asset triage

The highest-value first use is not "let users upload files" — it's giving a small group of admins a GUI over the public disk so they can:

1. Upload a replacement hero image without a deploy.
2. Browse to uploads/2024/ and confirm what's actually there.
3. Copy the relative path and paste it into a model field that uses Nova's built-in File/Image field on the same disk.

Start there, not with a broad rollout. Scope the disk ('root' => storage_path('app/public/uploads')) so the tool can only ever see the directory you intend.

Implementation Patterns

Tool vs. resource integration

The package is fundamentally a tool (a standalone Nova screen), not a field. Don't try to force it into a form. The idiomatic split:

• File Manager tool — operational/browse/cleanup surface for admins.
• Nova File / Image fields — the actual model-attached upload path in resource forms.
• A shared disk config — both point at the same filesystems.disks entry so paths line up.

The common workflow is: upload via the File Manager, copy the path, store it on a model. Document that convention for your team, because there's no automatic linkage between a file-manager upload and a database row.

Gate access explicitly

Never rely on "you need Nova to get in." Add a gate in AuthServiceProvider and wrap the tool:

Gate::define('browseFiles', fn ($user) => $user->hasRole('admin'));

Then guard the tool registration with ->canSee(...) or a canSee check inside the tool class. Anyone with Nova access can otherwise read/write the entire configured disk.

Disk-per-context configuration

Model your disks around intent, not around storage:

// config/filesystems.php
'media'      => ['driver' => 'local', 'root' => storage_path('app/media'), 'url' => '/storage/media'],
'tenant-{$id}' => [...],  // resolved per-tenant at runtime if the package supports a resolver
'private'    => ['driver' => 'local', 'root' => storage_path('app/private')],

Prefer several narrowly-rooted disks over one local disk rooted at storage/app. It's the cheapest security control you have with this package.

Operational cleanup pattern

Use it as a read-mostly inspection tool: verify orphaned uploads, rename inconsistent folders, delete test artifacts before a release. Pair with a nightly job that diffs referenced paths in the DB against files on disk so the manual cleanup is rare — the File Manager has no trash/undo, so bulk deletes are permanent.

Download/preview for private disks

Preview and download links depend on the disk's visibility/url settings. For non-public disks, confirm the package issues signed/temporary URLs rather than raw paths — test by opening a preview while logged out of the storage domain.

Gotchas and Tips

Compatibility is the real risk. Low star count plus an older last release means Nova 5 support is not guaranteed. Pin the exact version in composer.json, install on staging first, and diff the package's composer.json constraints against your Nova version. Don't let composer update silently swap it.

Authorization is on you. No package-level ACL is implied by the description. Treat an ungated File Manager as equivalent to shell access to storage/. Scope disk roots, gate the tool, and audit who has the Nova role.

Path scoping beats path validation. Relying on the tool to reject ../ is fragile. Set root on the filesystem disk itself — Laravel's local driver then refuses to escape it. Do this even if the package advertises traversal protection.

S3/remote disks behave differently. Rename and move become copy-then-delete — slow on large objects, non-atomic, and can leave orphans if interrupted. Directory listing may be eventually consistent. Budget for this if you point the tool at S3.

Upload limits are PHP-level, not Nova-level. Symptoms: the upload spinner hangs on files >2MB. Fix in php.ini/php-fpm:

upload_max_filesize = 64M
post_max_size = 66M
max_execution_time = 120

Check upload_max_filesize, post_max_size, and any reverse-proxy body limits (nginx client_max_body_size) — the proxy is a frequent culprit and doesn't appear in Laravel logs.

Debugging the tool's AJAX calls. The File Manager talks to Nova endpoints via XHR. When a listing is empty or an upload fails silently:

1. Browser devtools → Network → inspect the failing request and its JSON error body.
2. storage/logs/laravel.log for disk exceptions (UnableToWriteFile, permission denied).
3. Verify the disk's root exists and is writable by the web user (www-data, not your SSH user). This is the #1 cause of "upload works locally, fails on the server."
4. php artisan optimize:clear after any config change — cached config will hide edits.

No undo. Assume delete and overwrite are destructive and immediate. Take a snapshot/backup of the disk root before any bulk operation. Consider making the tool read-only for most admins and granting write to a smaller group.

Extension points to look for in src/: the tool class (subclass to override canSee, menu label, or disk list), published Blade views/assets (brand or constrain the UI), and the config's disk mapping (swap in a resolver if you need per-tenant roots). Since docs are thin, src/ is your actual documentation — read it before adding a workaround.

Don't expose it to end users. This is an admin back-office tool. If customers need to upload files, build that with Nova fields or a dedicated endpoint, with per-user directories and proper validation — not by handing them a directory browser over your storage disk.

Keep storage out of git. Uploads land in storage/app/...; confirm .gitignore covers it and that your deploy pipeline creates the directory tree with correct ownership.