README

Laravel Nova tool for running Artisan & Shell commands

Description

This Nova tool lets you run artisan and bash commands directly from nova.

This is an extended version of the original package Nova Command Runner by guratr

Requirements

php: >=8.0
laravel/nova: ^4.0

Features

⌨️ Run predefined artisan and shell commands
📝 Run custom artisan and shell commands
📄 Use variables while running commands
🙋‍♂️ Prompt the user to specify optional flags while running commands
📄 Use predefined values for variables using a select box or prompt the user to enter a value for the variable.
📖 Keep track of command run history
💾 No database changes required. Everything is managed from a single config file.
🕔 Queue long running commands
✅ Support command progressbar
📱 Responsive
🕶 Dark mode

Installation

You can install the nova tool in to a Laravel app that uses Nova via composer:

composer require stepanenko3/nova-command-runner

Next up, you must register the tool with Nova. This is typically done in the tools method of the NovaServiceProvider.

// in app/Providers/NovaServiceProvder.php

// ...

public function tools()
{
    return [
        // ...
        new \Workup\Nova\CommandRunner\CommandRunnerTool,
    ];
}

Publish the config file:

php artisan vendor:publish --provider="Workup\Nova\CommandRunner\ToolServiceProvider"

Add your commands to config/nova-command-runner.php

Usage

Click on the "Command Runner" menu item in your Nova app to see the tool.

Configuration

All the configuration is managed from a single configuration file located in config/nova-command-runner.php

Adding Commands

All the commands which needs to be easily accessible should be defined in the commands array in the configuration file.

Command Options

run : command to run (E.g. route:cache)
type : button class (primary, secondary, success, danger, warning, info, light, dark, link)
group: Group name (optional)
variables : Array of variables used in the command(optional)
command_type : Type of the command.(artisan or bash. Default artisan)
flags : Array of optional flags for the command(optional)
output_size: crops output of the given command to the specified number of lines
timeout: updates the timeout limit for the given queued command

Examples

'commands' => [

    // Basic command
    'Clear Cache' => [
        'run' => 'cache:clear', 
        'type' => 'danger', 
        'group' => 'Cache',
    ],
     
    // Bash command
    'Disk Usage' => [
        'run' => 'df -h', 
        'type' => 'danger', 
        'group' => 'Statistics',
        'command_type' => 'bash'
    ],

    // Command with variable   
    'Clear Cache' => [
        'run' => 'cache:forget {cache key}', 
        'type' => 'danger', 
        'group' => 'Cache'
    ],

    // Command with advanced variable customization
    'Clear Cache' => [
        'run' => 'cache:forget {cache key}', 
        'type' => 'danger', 
        'group' => 'Cache',
        'variables' => [
            [
                'label' =>  'cache key' // This needs to match with variable defined in the command,
                'field' => 'select' // Allowed values (text,number,tel,select,date,email,password),
                'options' => [
                    'blog-cache' => 'Clear Blog Cache', 
                    'app-cache' => 'Clear Application Cache'
                ],
                'placeholder' => 'Select An Option'
            ]
        ]
    ],

    // Command with flags
    'Run Migrations' => [
        'run' => 'migrate --force', 
        'type' => 'danger', 
        'group' => 'Migration',
    ],

    // Command with optional flags
    'Run Migrations' => [
        'run' => 'migrate', 
        'type' => 'danger', 
        'group' => 'Migration',
        'flags' => [ 
            // These optional flags will be prompted as a checkbox for the user
            // And will be appended to the command if the user checks the checkbox

            '--force' => 'Force running in production' 
        ]
    ],

    // Command with help text
    'Run Migrations' => [
        'run' => 'migrate --force', 
        'type' => 'danger', 
        'group' => 'Migration',

        // You can also add html for help text.
        'help' => 'This is a destructive operation. Proceed only if you really know what you are doing.'
    ],

    // Queueing commands
    'Clear Cache' => [
        'run' => 'cache:clear --should-queue',
        'type' => 'danger',
        'group' => 'Cache',
    ],

    // Queueing commands on custom queue and connection
    'Clear Cache' => [
        'run' => 'cache:clear --should-queue --cr-queue=high --cr-connection=database',
        'type' => 'danger',
        'group' => 'Cache',
    ],
],

Command with Progress bar

Create Artisan command with progress bar. For example:

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Workup\Nova\CommandRunner\Console\HasNovaProgressBar;

class LongCommand extends Command
{
    use HasNovaProgressBar;

    protected $signature = 'command:long';

    public function handle()
    {
        $bar = $this->createProgressBar(10);

        foreach (range(1, 10) as $i) {
            sleep(1);

            $bar->advance();
        }

        $bar->finish();

        return Command::SUCCESS;
    }
}

Add your command to config commands list

'commands' => [
    ...

    // Queueing long-running commands with custom timeout limit and output size
    'Long Command' => [ 
        'run' => 'command:long --should-queue',  // '--should-queue' is a required option to display the progressbar

        'type' => 'primary', 
        'group' => 'Application', 
        'timeout' => 120, // Updates the timeout limit for the given queued command
        'output_size' => 3, // The number of last lines to be displayed in the output
    ],
]

Other Customizations

// Limit the command run history to latest 10 runs
'history'  => 10,

// Tool name displayed in the navigation menu
'navigation_label' => 'Command Runner',

// Any additional info to display on the tool page. Can contain string and html.
'help' => '',

// Groups whose commands should not be running simultaneously, ['*'] to apply this globally to all commands
'unique_command_groups' => [],

// Allow running of custom artisan and bash(shell) commands
'custom_commands' => ['artisan','bash'],

// Allow running of custom artisan commands only(disable custom bash(shell) commands)
'custom_commands' => ['artisan'],

// Allow running of custom bash(shell) commands only(disable custom artisan commands)
'custom_commands' => ['bash'],

// Disable running of custom commands.
'custom_commands' => [],

'without_overlapping' => [
    // Blocks running commands simultaneously under the given groups. Use '*' for block all groups
    'groups' => [],

    // Blocks running commands simultaneously. Use '*' for block all groups
    'commands' => [],
],

Screenshots

Credits

Contributing

Thank you for considering contributing to this package! Please create a pull request with your contributions with detailed explanation of the changes you are proposing.

License

This package is open-sourced software licensed under the MIT license.

workup / nova-command-runner

Maintainers

Details