README

A beautiful, secure, and feature-rich UI for executing Laravel Artisan commands with role-based access control, theme support, and comprehensive command management.

✨ Features

🎨 Beautiful Bootstrap-based UI with light and dark themes
🔐 Role-based access control with Spatie Laravel Permission
🌐 IP-based restrictions for enhanced security
👤 Custom login credentials or standard Laravel authentication
📊 Command grouping (Default, Custom, Dangerous, Database, Cache)
⚡ Real-time command execution with live output
📝 Command history with detailed logging
🚨 Dangerous command warnings and confirmation
🔍 Command search and filtering
📱 Responsive design for all devices
🎯 Parameter validation for all command arguments and options
📈 Execution statistics and performance metrics

🚀 Installation

Requirements

PHP: 8.2 or higher
Laravel: 10.x, 11.x, 12.x, or higher
Spatie Laravel Permission: 5.x or 6.x

1. Install the Package

composer require kozhinhikkodan-dev/artisan-playground

2. Publish Assets and Configuration

php artisan vendor:publish --tag=artisan-playground

3. Run Migrations

php artisan migrate

4. Install Permissions and Roles

php artisan artisan-playground:install

5. Configure Access Control

Edit the published configuration file at config/artisan-playground.php:

'access_control' => [
    'allowed_roles' => [
        'artisan-playground-super-admin',
        'artisan-playground-admin',
        'artisan-playground-user',
    ],
    'required_permissions' => [
        'artisan-playground.view',
    ],
    'allowed_ips' => [
        '127.0.0.1',
        '192.168.1.*',
        '10.0.0.0/24',
    ],
],

⚙️ Configuration

Authentication Settings

'auth' => [
    'enabled' => true,
    'guard' => 'web',
    'custom_credentials' => [
        'enabled' => false,
        'username' => env('ARTISAN_PLAYGROUND_USERNAME', 'admin'),
        'password' => env('ARTISAN_PLAYGROUND_PASSWORD', 'password'),
    ],
],

Command Groups

Commands are automatically grouped into categories:

Default: Standard Laravel commands
Custom: Your application's custom commands
Dangerous: Commands that can affect system stability
Database: Database-related commands
Cache: Cache management commands

Dangerous Commands

Configure which commands are considered dangerous:

'dangerous_commands' => [
    'migrate:fresh',
    'migrate:reset',
    'db:wipe',
    'config:clear',
    'cache:clear',
    // Add more as needed
],

UI Settings

'ui' => [
    'theme' => [
        'default' => 'light', // light, dark, auto
        'allow_switch' => true,
    ],
    'layout' => [
        'sidebar_position' => 'left',
        'sidebar_collapsible' => true,
        'show_command_history' => true,
        'max_history_items' => 50,
    ],
],

🔐 Security

Role-Based Access Control

The package creates three default roles:

artisan-playground-super-admin: Full access to all features
artisan-playground-admin: Can execute dangerous commands and manage history
artisan-playground-user: Can execute safe commands only

Permissions

artisan-playground.view: View the dashboard
artisan-playground.execute: Execute commands
artisan-playground.execute-dangerous: Execute dangerous commands
artisan-playground.delete: Delete command history
artisan-playground.restore: Restore deleted commands
artisan-playground.force-delete: Permanently delete commands

IP Restrictions

Configure allowed IP addresses in the configuration:

'allowed_ips' => [
    '127.0.0.1',           // Single IP
    '192.168.1.*',         // Wildcard pattern
    '10.0.0.0/24',         // CIDR notation
    '*',                    // Allow all IPs
],

🎨 Usage

Accessing the Interface

Visit /artisan-playground in your browser after installation.

Executing Commands

Browse Commands: Navigate through command groups in the sidebar
Select Command: Click on any command to view its details
Configure Parameters: Fill in required arguments and optional parameters
Execute: Click "Execute Command" to run the command
View Output: See real-time output and execution time

Command History

View all executed commands with details
Filter by command name, user, status, or type
Re-execute commands with the same parameters
View full command output in modals

Theme Switching

Click the theme toggle button in the top-right corner to switch between light and dark themes.

🔧 Customization

Adding Custom Command Groups

'command_groups' => [
    'my-custom-group' => [
        'name' => 'My Custom Commands',
        'description' => 'Custom application commands',
        'icon' => 'fas fa-star',
        'color' => 'warning',
    ],
],

Customizing Dangerous Commands

'dangerous_commands' => [
    // Add your custom dangerous commands
    'my-app:reset-data',
    'my-app:clear-cache',
],

Custom Styling

Override the default styles by publishing the assets and modifying:

public/vendor/artisan-playground/css/app.css
public/vendor/artisan-playground/js/app.js

📊 API Endpoints

The package provides several API endpoints:

GET /artisan-playground - Dashboard
GET /artisan-playground/command/{name} - Command details
POST /artisan-playground/execute - Execute command
GET /artisan-playground/history - Command history
GET /artisan-playground/login - Login page
POST /artisan-playground/login - Authenticate
POST /artisan-playground/logout - Logout

🧪 Testing

# Run the package tests
composer test

# Run with coverage
composer test -- --coverage

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the Repository

Fork the repository on GitHub.

2. Create a Feature Branch

git checkout -b feature/amazing-feature

3. Make Your Changes

Follow PSR-12 coding standards
Add tests for new features
Update documentation as needed
Ensure all tests pass

4. Commit Your Changes

git commit -m 'Add amazing feature'

5. Push to the Branch

git push origin feature/amazing-feature

6. Create a Pull Request

Submit a pull request with a clear description of your changes.

Development Setup

Clone the repository
Install dependencies: composer install
Copy .env.example to .env and configure
Run migrations: php artisan migrate
Install the package: php artisan artisan-playground:install

Code Style

Follow PSR-12 coding standards
Use meaningful variable and function names
Add proper PHPDoc comments
Keep functions small and focused

Testing Guidelines

Write unit tests for all new features
Ensure test coverage is maintained
Test both success and failure scenarios
Mock external dependencies

📝 Changelog

v1.0.0

Initial release
Bootstrap-based UI with theme support
Role-based access control
Command execution and history
IP-based restrictions
Custom authentication support

📄 License

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

🙏 Acknowledgments

Laravel - The PHP framework
Bootstrap - CSS framework
Font Awesome - Icons
Spatie Laravel Permission - Permission management

📞 Support

GitHub Issues: Report bugs or request features
Documentation: Full documentation
Buy me a coffee: Support the project

⭐ Star the Repository

If you find this package useful, please consider starring the repository on GitHub!

Made with ❤️ by Salih Kozhinhikkodan

kozhinhikkodan-dev / artisan-playground

Maintainers

Details