Auto Shell Laravel Package

Technical Evaluation

Architecture Fit

• CLI-Driven Workflows: Ideal for Laravel applications requiring structured CLI command execution (e.g., migrations, queues, custom admin tasks). Aligns with Laravel’s existing artisan CLI but offers declarative command definition via PHP classes instead of XML/YAML.
• Separation of Concerns: Encourages modular command design (e.g., Project\Cli\Command\* namespace) with type-safe parameters (scalars, arrays, custom Options classes), reducing boilerplate compared to Laravel’s Command trait.
• Dependency Injection (DI) Ready: Supports PSR-11 containers (e.g., Laravel’s Illuminate\Container) via the factory parameter, enabling testability and service binding (e.g., repositories, APIs).
• Help System: Built-in auto-generated manpages (help:command) reduce documentation overhead, unlike Laravel’s manual --help implementations.

Integration Feasibility

• Laravel Compatibility:
  • Pros:
    • Zero dependencies; integrates with Laravel’s autoloader (Composer).
    • Replaces or augments Laravel’s Artisan for custom commands without forking core logic.
    • Works alongside existing Artisan commands (e.g., migrate, queue:work).
  • Cons:
    • No native Laravel service provider: Requires manual bin/console.php setup (see Integration Approach).
    • No integration with Laravel’s Command trait: Commands must use __invoke() or a custom method (e.g., execute()).
    • Potential namespace conflicts: Laravel’s Artisan commands live in Illuminate\Console\Command; AutoShell requires a separate namespace (e.g., App\Cli\Command).
• PHP Version: Requires PHP 8.0+ (for attributes like #[Option]), which aligns with Laravel 9+/10+.

Technical Risk

Key Questions

1. Command Lifecycle:
   • How will AutoShell commands interact with Laravel’s service container (e.g., binding repositories, queues)?
   • Can AutoShell commands leverage Laravel’s events (e.g., CommandStarting, CommandFinished)?
2. Artisan Integration:
   • Should AutoShell commands be subcommands of artisan (e.g., artisan app:hello) or standalone (e.g., php bin/console.php hello)?
   • How to handle global options (e.g., --env, --verbose) shared with Laravel’s Artisan?
3. Testing:
   • How to mock AutoShell’s Console in PHPUnit for unit testing commands?
   • Can AutoShell commands use Laravel’s testing helpers (e.g., Artisan::call)?
4. Deployment:
   • How to ensure bin/console.php is executable and discoverable in Laravel’s deployment pipeline?
   • Should AutoShell commands be versioned alongside Laravel migrations?
5. Long-Term Maintenance:
   • What’s the upgrade path if AutoShell evolves (e.g., PHP 9.0+ features)?
   • How to handle deprecated commands (e.g., removing old Artisan commands)?

Integration Approach

Stack Fit

• Primary Use Cases:
  • Custom CLI Tools: Replace Laravel’s Command trait for internal tools (e.g., data imports, report generation).
  • Admin Interfaces: Build interactive CLI menus (e.g., app:setup) with rich options/help.
  • Automation: Integrate with CI/CD pipelines (e.g., deploy:verify) or cron jobs.
• Laravel Synergy:
  • Service Container: AutoShell’s factory parameter maps to Laravel’s app() helper.
  • Configuration: Store command namespaces/directories in config/console.php.
  • Events: Trigger Laravel events (e.g., command:executed) after AutoShell command completion.

Migration Path

1. Phase 1: Pilot Commands

   • Scope: Non-critical commands (e.g., app:generate-key, app:log-cleanup).
   • Implementation:
     • Add bin/console.php alongside Laravel’s artisan.
     • Define commands in app/Cli/Command/ with App\Cli\Command namespace.
     • Example:

       // app/Cli/Command/GenerateKey.php
       namespace App\Cli\Command;
       use AutoShell\Help;
       #[Help("Generates a new application key.")]
       class GenerateKey {
           public function __invoke(): int { ... }
       }
       

   • Testing: Verify commands work standalone (php bin/console.php generate-key).

2. Phase 2: Artisan Integration

   • Goal: Make AutoShell commands accessible via artisan.
   • Implementation:
     • Create a custom Artisan command that proxies to AutoShell:

       // app/Console/Commands/RunAutoShell.php
       namespace App\Console\Commands;
       use Illuminate\Console\Command;
       class RunAutoShell extends Command {
           protected $signature = 'app:{command} {arguments}';
           public function handle() {
               $console = app('console');
               return $console([...$_SERVER['argv']]);
           }
       }
       

     • Register in app/Console/Kernel.php:

       protected $commands = [
           Commands\RunAutoShell::class,
       ];
       

   • Usage: php artisan app:generate-key.

3. Phase 3: Full Replacement

   • Scope: Replace Laravel’s Command trait for new commands.
   • Implementation:
     • Migrate existing Command classes to AutoShell’s __invoke() pattern.
     • Use trait composition to hybridize old/new commands:

       use AutoShell\Options;
       use Illuminate\Console\Command as LaravelCommand;
       class HybridCommand extends LaravelCommand {
           public function __invoke(Options $options) { ... }
       }
       

Compatibility

Sequencing

1. Setup:
   • Install package: composer require pmjones/auto-shell.
   • Create bin/console.php (see README).
   • Configure namespace/directory in config/console.php:

     return [
         'namespace' => 'App\Cli\Command',
         'directory' => app_path('Cli/Command'),
         'factory' => fn(string $class) => app($class),
     ];
     

2. Bootstrap:
   • Register Console in a service provider:

     $this->app->singleton('console', fn() => Console::new(
         namespace: config('console.namespace'),
         directory: config('console.directory'),
         factory: config('console.factory'),
     ));
     

3. Command Development:
   • Follow AutoShell’s class-based pattern (e.g., Hello.php).
   • Use Laravel helpers inside commands (e.g., `app('cache