laravelplus/commander

Command execution tracking and management for Laravel applications

v1.0.0 2025-07-24 12:14 UTC

This package is not auto-updated.

Last update: 2025-07-25 07:14:46 UTC


README

Tests Latest Version on Packagist Total Downloads Monthly Downloads License PHP Version Laravel Version Code Style Coverage PHP 8.4+ Vue 3 Tailwind CSS

A modern Laravel package for tracking and managing command executions with detailed analytics, beautiful UI, and comprehensive command management features.

๐Ÿ“‹ Requirements

  • PHP: 8.4 or higher
  • Laravel: 12.x or higher
  • Vue.js: 3.x (included via CDN)
  • Tailwind CSS: 3.x (included via CDN)

๐Ÿ“ฆ Installation

Production Installation

For production projects, install via Composer:

composer require laravelplus/commander

Development Installation

For development or local projects, add to your composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "packages/laravelplus/commander"
        }
    ],
    "require": {
        "laravelplus/commander": "*"
    }
}

Then run:

composer install

Setup Steps

  1. Publish migrations and config:
php artisan vendor:publish --tag=commander-migrations
php artisan vendor:publish --tag=commander-config
  1. Run migrations:
php artisan migrate
  1. Access the interface:
    • Visit: http://your-app.com/admin/commander
    • Default URL can be configured in config/commander.php

โš™๏ธ Configuration

The package is highly configurable through the config/commander.php file:

Basic Configuration

return [
    'enabled' => env('COMMANDER_ENABLED', true),
    
    // Interface Configuration
    'url' => env('COMMANDER_URL', 'admin/commander'),
    'route_prefix' => env('COMMANDER_ROUTE_PREFIX', 'admin'),
    'route_name_prefix' => env('COMMANDER_ROUTE_NAME_PREFIX', 'commander'),
    'middleware' => env('COMMANDER_MIDDLEWARE', ['auth', 'web']),
    
    // Tracking Configuration
    'track_output' => env('COMMANDER_TRACK_OUTPUT', true),
    'track_arguments' => env('COMMANDER_TRACK_ARGUMENTS', true),
    'track_options' => env('COMMANDER_TRACK_OPTIONS', true),
    'track_execution_time' => env('COMMANDER_TRACK_EXECUTION_TIME', true),
    'track_user' => env('COMMANDER_TRACK_USER', true),
    
    // Storage Configuration
    'max_output_length' => env('COMMANDER_MAX_OUTPUT_LENGTH', 10000),
    'retention_days' => env('COMMANDER_RETENTION_DAYS', 90),
];

Command Management Configuration

// Commands to ignore from tracking (still appear in interface)
'ignored_commands' => [
    'schedule:run',
    'queue:work',
    'queue:listen',
    'migrate:*',
    'db:seed',
    'config:cache',
    'route:cache',
    'view:cache',
],

// Commands to exclude from interface (completely hidden)
'excluded_commands' => [
    'vendor:*',
    'package:*',
    'tinker',
    'serve',
    'test:*',
    'dusk:*',
    'make:*',
    'stub:*',
    'clear-compiled',
    'down',
    'up',
    'env',
    'key:generate',
    'optimize',
    'optimize:clear',
    'config:clear',
    'route:clear',
    'view:clear',
    'cache:clear',
    'cache:forget',
    'cache:table',
    'session:table',
    'queue:table',
    'queue:failed-table',
    'queue:batches-table',
    'notifications:table',
    'event:generate',
    'listener:generate',
    'mail:make',
    'middleware:make',
    'provider:make',
    'request:make',
    'resource:make',
    'rule:make',
    'seeder:make',
    'test:make',
    'channel:make',
    'command:make',
    'component:make',
    'controller:make',
    'event:make',
    'exception:make',
    'factory:make',
    'job:make',
    'listener:make',
    'mail:make',
    'middleware:make',
    'model:make',
    'notification:make',
    'observer:make',
    'policy:make',
    'provider:make',
    'request:make',
    'resource:make',
    'rule:make',
    'seeder:make',
    'test:make',
],

// Commands that appear but cannot be executed (read-only)
'disabled_commands' => [
    'migrate:fresh',
    'migrate:refresh',
    'migrate:reset',
    'db:wipe',
    'config:clear',
    'route:clear',
    'view:clear',
    'cache:clear',
    'optimize:clear',
    'event:clear',
    'queue:restart',
    'queue:flush',
    'queue:forget',
    'queue:retry',
    'queue:retry-batch',
    'queue:work',
    'queue:listen',
    'schedule:run',
    'schedule:list',
    'schedule:test',
    'schedule:work',
    'vendor:publish',
    'vendor:install',
    'vendor:update',
    'package:discover',
    'package:clear-cache',
    'package:optimize',
    'package:cache',
    'package:config',
    'package:route',
    'package:view',
    'package:lang',
    'package:migrate',
    'package:seed',
    'package:publish',
    'package:install',
    'package:update',
    'package:uninstall',
    'package:list',
    'package:show',
    'package:outdated',
    'package:update',
    'package:install',
    'package:remove',
    'package:require',
    'package:require-dev',
    'package:update',
    'package:install',
    'package:remove',
    'package:require',
    'package:require-dev',
],

๐Ÿงช Testing

The package includes comprehensive test coverage with 54 tests and 166 assertions:

# Run all tests
php vendor/bin/phpunit

# Run specific test suites
php vendor/bin/phpunit --testsuite=Unit
php vendor/bin/phpunit --testsuite=Feature

# Run with coverage report
php vendor/bin/phpunit --coverage-html coverage/

Test Coverage

  • โœ… Unit Tests: 51 tests covering all action classes, controllers, and services
  • โœ… Feature Tests: 3 tests covering API endpoints and dashboard functionality
  • โœ… Database Tests: Full database testing with SQLite in-memory database
  • โœ… Mock Testing: Comprehensive mocking of dependencies
  • โœ… Error Handling: Tests for all error scenarios and edge cases
  • โœ… PHPUnit 11: Latest testing framework with improved performance

Test Structure

tests/
โ”œโ”€โ”€ Feature/
โ”‚   โ””โ”€โ”€ DashboardTest.php          # API endpoint tests
โ”œโ”€โ”€ Unit/
โ”‚   โ”œโ”€โ”€ Http/
โ”‚   โ”‚   โ”œโ”€โ”€ Actions/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ BaseActionTest.php
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ GetCommandsActionTest.php
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ RunCommandActionTest.php
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ GetDashboardStatsActionTest.php
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ RetryCommandActionTest.php
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ ShowDashboardActionTest.php
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ GetRecentExecutionsActionTest.php
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ SearchCommandsActionTest.php
โ”‚   โ”‚   โ””โ”€โ”€ Controllers/
โ”‚   โ”‚       โ””โ”€โ”€ CommandsControllerTest.php
โ”‚   โ””โ”€โ”€ TestCase.php               # Base test case
โ””โ”€โ”€ phpunit.xml                    # Test configuration

๏ฟฝ๏ฟฝ URL Configuration

You can customize the commander interface URL by setting the COMMANDER_URL environment variable:

# Default: http://127.0.0.1:8000/admin/commander
COMMANDER_URL=admin/commander

# Custom URL examples:
COMMANDER_URL=admin/tools/commands
COMMANDER_URL=management/command-center
COMMANDER_URL=system/command-executor

โœจ Features

๐ŸŽฏ Core Functionality

  • โœ… Command Execution Tracking: Track when commands were last run with detailed metrics
  • โœ… Execution History: View detailed history of all command executions with search and filtering
  • โœ… Performance Analytics: Track execution times, success rates, and performance trends
  • โœ… User Tracking: Track which user executed each command with audit trail
  • โœ… Real-time Interface: Modern Vue 3 powered interface with real-time updates

๐ŸŽจ User Interface

  • โœ… Beautiful Modern UI: Clean, responsive design with Tailwind CSS
  • โœ… Command Arguments Support: Dynamic forms for commands with arguments and options
  • โœ… Confirmation Dialogs: Safety-first approach with confirmation before execution
  • โœ… Improved Modals: Better modal design that doesn't get cut off
  • โœ… Visual Indicators: Clear status indicators for command states
  • โœ… Responsive Design: Works perfectly on desktop, tablet, and mobile

๐Ÿ”ง Command Management

  • โœ… Disabled Commands: Mark commands as disabled (read-only) in the interface
  • โœ… Excluded Commands: Completely hide commands from the interface
  • โœ… Pattern Matching: Support for wildcard patterns in command filtering
  • โœ… Command Categories: Organize commands by namespace/category
  • โœ… Search & Filter: Powerful search and filtering capabilities

๐Ÿ“Š Analytics & Monitoring

  • โœ… Dashboard Statistics: Overview of command execution metrics
  • โœ… Activity Monitoring: Real-time activity feed with filtering
  • โœ… Failed Command Tracking: Dedicated interface for failed commands
  • โœ… Retry Functionality: Retry failed commands with original parameters
  • โœ… Schedule Management: Interface for managing scheduled commands

โš™๏ธ Configuration & Security

  • โœ… Highly Configurable: Extensive configuration options
  • โœ… Security Features: CSRF protection, user authentication
  • โœ… Output Storage: Store command output with configurable limits
  • โœ… Retention Policy: Automatic cleanup of old execution records
  • โœ… Environment Support: Different settings for different environments

๐ŸŽฏ Usage

Accessing the Interface

Once installed, you can access the commander interface at:

http://your-app.com/admin/commander

Interface Features

๐Ÿ“‹ Command List

  • View all available commands with their descriptions
  • See last execution time and status
  • Filter by category or search by name
  • Execute commands with confirmation dialog

โš™๏ธ Command Arguments

  • Dynamic forms for commands with arguments
  • Support for required and optional arguments
  • Default value handling
  • Option flags and values

๐Ÿ”„ Execution History

  • Detailed execution history for each command
  • Success/failure status tracking
  • Execution time and output storage
  • User tracking for audit purposes

๐Ÿ“Š Analytics Dashboard

  • Overview of command execution metrics
  • Success rate statistics
  • Popular commands tracking
  • Recent activity feed

โŒ Failed Commands

  • Dedicated interface for failed commands
  • Retry functionality with original parameters
  • Error analysis and debugging
  • Bulk retry operations

โฐ Schedule Management

  • Interface for managing scheduled commands
  • Next run time calculations
  • Schedule status monitoring
  • Manual execution of scheduled commands

Helper Functions

The package provides helper functions for easy access:

// Generate commander URL
$url = commander_url(); // http://127.0.0.1:8000/admin/commander
$url = commander_url('list'); // http://127.0.0.1:8000/admin/commander/list

// Generate commander routes
$route = commander_route('index'); // commander.index
$route = commander_route('run', ['command' => 'test']); // commander.run

// Check if commander is enabled
if (commander_enabled()) {
    // Commander functionality is available
}

Manual Tracking

You can also manually track command executions:

use LaravelPlus\Commander\Traits\TracksCommandExecution;

class YourController extends Controller
{
    use TracksCommandExecution;

    public function runCommand(Request $request)
    {
        $commandName = 'check:password-expiry';
        $arguments = ['--batch-size=10'];
        $options = ['--delay=2'];

        // Start tracking
        $this->startTracking($commandName, $arguments, $options);

        try {
            // Execute your command
            $result = $this->executeCommand($commandName, $arguments, $options);
            
            // Complete tracking with success
            $this->completeTracking(true, 0, $result['output']);
            
            return response()->json($result);
        } catch (Exception $e) {
            // Complete tracking with failure
            $this->completeTracking(false, 1, $e->getMessage());
            throw $e;
        }
    }
}

Querying Execution Data

use LaravelPlus\Commander\Models\CommandExecution;

// Get last execution time for a command
$lastExecution = CommandExecution::getLastExecutionTime('check:password-expiry');

// Get execution statistics
$stats = CommandExecution::getCommandStats('check:password-expiry', 30);

// Get recent executions
$recentExecutions = CommandExecution::recent(7)->get();

// Get failed executions
$failedExecutions = CommandExecution::failed()->get();

๐Ÿ”Œ API Endpoints

The package provides several API endpoints for managing command executions:

Get Commands with History

GET /admin/commander/api/list

Returns all commands with their last execution time and statistics.

Get Command History

GET /admin/commander/api/{commandName}/history

Returns paginated history of executions for a specific command.

Get Command Statistics

GET /admin/commander/api/{commandName}/stats

๐Ÿค Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/laravelplus/commander.git

# Install dependencies
composer install

# Run tests
php vendor/bin/phpunit

# Run code style checks
./vendor/bin/pint

Pull Request Process

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass (php vendor/bin/phpunit)
  6. Commit your changes (git commit -m 'Add some amazing feature')
  7. Push to the branch (git push origin feature/amazing-feature)
  8. Open a Pull Request

๐Ÿ“„ License

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

๐Ÿ™ Acknowledgments

๐Ÿ“ž Support

Made with โค๏ธ by the LaravelPlus Team