README

Run artisan and shell commands in the background from your Filament admin panel.

Overview

filament-command-runner is a Filament plugin that allows users to run artisan and shell commands directly from the Filament admin panel. All commands are executed in the background so users don't have to wait for them to finish. They can return later to view the output or optionally terminate a running command midway.

The plugin also keeps a detailed history of past runs including:

• Command executed
• User who initiated the run
• Start time
• Duration
• Exit code
• Command output

Screenshots

1. Installation

1.1 Install Package

You can install the plugin via composer:

composer require binarybuilds/filament-command-runner

1.2 Publish Migrations

You should publish the migration for the package and adjust it to fit your project's structure:

php artisan vendor:publish --tag=command-runner-migrations

Before running the migrations, if you are using UUID or ULID, consider adjusting the ran_by field to store string instead of unsignedBigInteger. Feel free to adjust $table->id() field if needed. Once appropriate, run the migrations command:

php artisan migrate

Usage

Register the plugin in your Filament panel service provider:

use BinaryBuilds\CommandRunner\CommandRunnerPlugin;

$panel->plugin(CommandRunnerPlugin::make());

Customizations

1. Authorization

You can restrict access to this plugin using the authorize method. This accepts a boolean or a closure that returns a boolean.

CommandRunnerPlugin::make()->authorize(fn () => auth()->user()->can('view-command-runner'))

2. Navigation Group

You can change the navigation group using the navigationGroup method. This accepts a string, UnitEnum.

CommandRunnerPlugin::make()->navigationGroup('System')

3. Navigation Label

You can customize the navigation label using the navigationLabel method.

CommandRunnerPlugin::make()->navigationLabel('Command Runner')

4. Navigation Icon

You can change the navigation icon using the navigationIcon method. This accepts a Heroicon string or a Heroicon enum value.

CommandRunnerPlugin::make()->navigationIcon('heroicon-o-exclamation-triangle')

5. Navigation Sort Order

You can change the navigation sort order using the navigationSort method.

CommandRunnerPlugin::make()->navigationSort(10)

6. Command Validation

You can define custom validation logic using the validateCommand() method. This is useful for restricting which commands can be run:

use Illuminate\Support\Str;

$panel->plugin(
    CommandRunnerPlugin::make()->validateCommand(function (string $attribute, string $value, \Closure $fail) {
        if (!Str::startsWith($value, 'php artisan')) {
            $fail("You can only run artisan commands");
        }
    })
);

7. Delete Command History

Control who can delete command history entries using a boolean or closure with canDeleteCommandHistory():

$panel->plugin(
    CommandRunnerPlugin::make()->canDeleteCommandHistory(fn ($user) => $user->isAdmin())
);

8. Purge Old Command History

Schedule the following artisan command to purge command history entries daily:

php artisan command-runner:purge-history

By default, it removes command runs older than 30 days. You can specify a custom duration like this:

php artisan command-runner:purge-history 7

This example will purge command runs older than 7 days.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Srinath Reddy Dudi
• All Contributors

License

The MIT License (MIT). Please see License File for more information.