laravelplus / commander
Command execution tracking and management for Laravel applications
Installs: 34
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Language:Blade
Requires
- php: ^8.4
- illuminate/support: ^12.0
- laravel/framework: ^12.0
Requires (Dev)
- laravel/pint: ^1.24
- orchestra/testbench: ^10.0
- phpunit/phpunit: ^11.0
This package is not auto-updated.
Last update: 2025-07-25 07:14:46 UTC
README
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
- Publish migrations and config:
php artisan vendor:publish --tag=commander-migrations php artisan vendor:publish --tag=commander-config
- Run migrations:
php artisan migrate
- Access the interface:
- Visit:
http://your-app.com/admin/commander
- Default URL can be configured in
config/commander.php
- Visit:
โ๏ธ 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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Make your changes
- Add tests for new functionality
- Ensure all tests pass (
php vendor/bin/phpunit
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
๐ License
This package is open-sourced software licensed under the MIT license.
๐ Acknowledgments
- Built with Laravel 12+
- UI powered by Vue 3
- Styled with Tailwind CSS
- Testing with PHPUnit
- Requires PHP 8.4+
๐ Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Wiki
Made with โค๏ธ by the LaravelPlus Team