Nova File Artisan Laravel Package

Getting Started

mostafaznv/nova-file-artisan adds an Artisan console to the Nova UI so operators can run whitelisted commands without SSH. Version 2.4.0 adds Laravel 13 support (no other changes) — the wiring below is unchanged from 2.3.x.

1. composer require mostafaznv/nova-file-artisan
2. Publish the config: php artisan vendor:publish --tag=nova-file-artisan-config (or publish by provider if the tag has changed — check vendor/mostafaznv/nova-file-artisan).
3. Register the tool in app/Providers/NovaServiceProvider.php → tools():

   public function tools(): array
   {
       return [
           new \Mostafaznv\NovaFileArtisan\NovaFileArtisan(),
       ];
   }
   

4. Open config/nova-file-artisan.php, set the enable flag, and add your first command entry.
5. First use case: expose a handful of safe operational commands (cache:clear, queue:restart, migrate --force behind a stricter gate) to a small admin group, rather than the whole artisan surface.

If the tool doesn't appear in the sidebar, the two usual culprits are a cached config (php artisan config:clear) and a cached Nova permission set.

Implementation Patterns

Treat the config file as the allowlist. Every command you want available should be declared explicitly with a display name, group, and its own can callback. Don't rely on enabled alone to protect a production instance — layer Nova's Gate on top of per-command authorization so the same rules apply to API and UI.

Group by operator intent, not by Symfony namespace. Groups like Caches, Queues, Maintenance read better than laravel/framework namespaces and make the tool usable for support staff who don't know Artisan.

Arguments and options as declared fields. Expose only the flags you actually need (--force, --queue=, a tenant id). Declaring arguments in config turns free-form shell access into a form with validated inputs — this is the single biggest safety lever the package gives you.

Wrap risky operations in a review path. For anything destructive (migrate:fresh, db:wipe), pair the tool with a Nova Action or a confirmation step, and consider pointing those entries at a maintenance-enabled gate that is off in normal operation.

Use it as the "last mile" of a deploy/ops runbook. Commands like storage:link, optimize:clear, horizon:terminate, and queue:restart are exactly the ones you want one click away after a deploy — the ones with no arguments, idempotent output, and short runtimes.

Audit alongside Nova's own logging. Hook Nova's action/event listeners or a middleware on the tool to record who ran what and when; the package executes the command but doesn't give you a durable audit trail by default.

Version constraint hygiene. With 2.4.0 you can allow laravel/framework:^13.0 in composer.json. If you're still on 10/11/12, pin ^2.3 so a future major doesn't surprise a composer update in CI.

Gotchas and Tips

• It runs inside an HTTP request, not a shell. max_execution_time, PHP-FPM request_terminate_timeout, and any proxy timeout apply. Long commands will be killed mid-flight with no useful error — keep entries short or push real work onto a queue.
• The PHP binary and environment may differ from your terminal. The subprocess often inherits the web user's PATH and a different APP_ENV. If a command works via SSH but fails in Nova, compare php -v, the working directory, and $_ENV first.
• Interactive prompts will hang or fail. Commands that ask for confirmation (migrate without --force, db:seed confirmations) need those flags set in the config entry.
• Output is buffered and often truncated. Very chatty commands (composer, npm, verbose migrations) can exceed what the UI renders. Prefer commands whose output is a summary line.
• Config caching bites authorization changes. After editing can callbacks, run php artisan config:clear — and remember Nova caches its own service provider state, so restart workers.
• Permissions are enforced in two places. The tool-level enabled/gate check and per-command can callbacks are independent; forgetting one leaves a command visible to users who shouldn't see it.
• Disable locally. Set the enable flag to false in local so the tool doesn't pollute the dev sidebar and doesn't become a habit — the point is to remove the SSH dependency in environments where you have none.
• Debugging failures: check storage/logs/laravel.log and the Nova log first; if the command produces no output and no error, drop to a temporary equivalent entry that runs php artisan <cmd> with --no-interaction and a Process timeout to surface the real exit code.
• Extension points are thin by design. Beyond the config allowlist and the can closures, expect to extend via a custom Nova tool if you need streaming output, history, or queued execution — don't bend the config past what it's for.
• Laravel 13 note: 2.4.0's only change is the framework constraint. If you upgrade to Laravel 13, verify Nova itself supports it before bumping — the tool is the easy part.