Auto Shell Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require pmjones/auto-shell
   

2. Create bin/console.php:

   <?php
   use AutoShell\Console;
   
   require dirname(__DIR__) . '/vendor/autoload.php';
   
   $console = Console::new(
       namespace: 'App\\Cli\\Command',
       directory: __DIR__ . '/../src/Cli/Command',
   );
   
   exit($console($_SERVER['argv']));
   

3. Create a command class (e.g., src/Cli/Command/Greet.php):

   <?php
   namespace App\Cli\Command;
   
   class Greet
   {
       public function __invoke(string $name): int
       {
           echo "Hello, {$name}!\n";
           return 0;
       }
   }
   

4. Run it:

   php bin/console.php greet Alice
   

First Use Case: CLI Command with Arguments

• Goal: Create a command that accepts a name and greets it.
• Steps:
  1. Define a class with __invoke() (or custom method) in the configured namespace.
  2. Type-hint parameters (e.g., string $name).
  3. Run the command via php bin/console.php <command> <args>.

Implementation Patterns

1. Command Structure

• Convention: Place commands in src/Cli/Command/ (or configured directory).
• Naming: Class names map to command names (e.g., UserCreate → user:create).
• Method: Defaults to __invoke(), but customizable via method in Console::new().

2. Options Handling

• Pattern: Use Options interface + #[Option] attributes.

  class UserCreateOptions implements Options
  {
      public function __construct(
          #[Option('f,force')]
          public readonly ?bool $force = false,
      ) {}
  }
  

• Usage: Inject Options as a parameter to __invoke().

  public function __invoke(UserCreateOptions $options, string $name): int
  {
      if ($options->force) { ... }
  }
  

3. Dependency Injection

• Factory Pattern: Pass a closure to Console::new() to resolve dependencies.

  $console = Console::new(
      namespace: 'App\\Cli\\Command',
      directory: __DIR__ . '/../src/Cli/Command',
      factory: fn(string $class) => app()->make($class),
  );
  

4. Help Documentation

• Class-Level Help: Use #[Help] on the class.

  #[Help("Creates a new user.")]
  class UserCreate {}
  

• Parameter Help: Add help to #[Option] or #[Help] on parameters.

  #[Help("The user's name.", "The name of the user to create.")]
  string $name,
  

5. Advanced Argument Types

• Arrays: Use array type-hint with CSV input (e.g., --tags=tag1,tag2).
• Booleans: Auto-cast y/n, 1/0, etc.
• Variadic Args: Use ...string $args for catch-all arguments.

6. Composing Options

• Global + Local Options: Inject multiple Options classes.

  public function __invoke(
      GlobalOptions $global,
      UserCreateOptions $local
  ): int { ... }
  

• Conflict Handling: Avoid duplicate option names across Options classes.

Gotchas and Tips

1. Common Pitfalls

• Namespace Mismatch: Ensure the namespace in Console::new() matches your command classes.
• Non-Public Methods: Only public methods are auto-detected. Use __invoke() or explicitly set method.
• Option Conflicts: Duplicate option names (e.g., -v in both GlobalOptions and UserCreateOptions) throw OptionAlreadyDefined.
• Case Sensitivity: Command names are case-sensitive (e.g., user:create ≠ User:Create).

2. Debugging Tips

• Verbose Output: Enable debug mode via Console::new(..., debug: true).
• Help Generation: Test help with php bin/console.php help <command>.
• Type Casting: Ensure #[Option] values match parameter types (e.g., bool for flags).

3. Configuration Quirks

• Directory Scanning: Only .php files in the configured directory are scanned.
• Suffix Handling: Use suffix in Console::new() if commands don’t follow PascalCase (e.g., suffix: 'Command').
• Factory Exclusions: The factory is not used for help classes (they’re instantiated directly).

4. Extension Points

• Custom Help Rendering: Override Console to modify help output (e.g., add colors).
• Pre/Post-Processing: Wrap $console($_SERVER['argv']) in logic for logging or metrics.
• Option Validation: Add validation in __invoke() and return non-zero exit codes for errors.

5. Performance Notes

• Reflection Overhead: AutoShell uses reflection to parse commands. For large suites, consider caching the Shell instance.
• Lazy Loading: Commands are loaded on-demand; no upfront scanning.

6. Edge Cases

• Empty Arguments: Handle null or empty strings in __invoke().
• Boolean Options: Default to null if the option isn’t provided (e.g., ?bool $verbose).
• Multi-Word Arguments: Use quotes in CLI (e.g., php bin/console.php greet "Alice Bob").