Command Builder Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require digipolisgent/command-builder
   

   Add to composer.json under require if not using Composer directly.

2. First Use Case: Build a simple command chain:

   use DigipolisGent\CommandBuilder\CommandBuilder;
   
   $builder = CommandBuilder::create('ls')
       ->addArgument('path/to/dir')
       ->pipeOutputTo('grep')
       ->addArgument('pattern');
   
   echo $builder; // Outputs: `ls path/to/dir | grep pattern`
   

3. Where to Look First:

   • CommandBuilder class: Core builder methods (create(), addArgument(), addFlag(), etc.).
   • README.md: Example workflows (e.g., success/failure handling).
   • tests/: Real-world usage patterns (if tests exist).

Implementation Patterns

Core Workflows

1. Basic Command Chaining:

   CommandBuilder::create('git')
       ->addArgument('pull')
       ->pipeOutputTo('grep')
       ->addArgument('error');
   

   Use case: Log parsing or error detection.

2. Conditional Execution:

   CommandBuilder::create('phpunit')
       ->onSuccess('notify')
           ->addArgument('--success')
       ->onFailure('notify')
           ->addArgument('--failure');
   

   Use case: CI/CD notifications or rollback triggers.

3. Nested Commands:

   CommandBuilder::create('mkdir')
       ->addArgument('temp')
       ->onSuccess(CommandBuilder::create('cp')
           ->addArgument('file.txt')
           ->pipeOutputTo('temp/')
       );
   

   Use case: Multi-step operations (e.g., setup + action).

4. Flag/Option Handling:

   CommandBuilder::create('docker')
       ->addFlag('rm')
       ->addFlag('f') // Force
       ->addArgument('container');
   

   Use case: CLI tools with optional flags (e.g., docker-compose).

5. Environment Integration: Combine with Laravel’s Artisan or Process facade:

   $command = CommandBuilder::create('php')
       ->addArgument('artisan')
       ->addArgument('migrate')
       ->getCommand(); // Returns raw string
   Process::run($command);
   

Gotchas and Tips

Pitfalls

1. Output Escaping:

   • Arguments with spaces/special chars (e.g., addArgument("file path")) may break.
   • Fix: Use addArgument('file path') (single quotes in output) or escape manually:

     ->addArgument("file\\ path"); // Escaped for shell
     

2. Nested Command Delimiters:

   • Deeply nested onSuccess/onFailure can confuse shell parsing.
   • Fix: Limit nesting depth or flatten logic.

3. No Direct Process Execution:

   • The package builds strings, not executes commands. Pair with Laravel’s Process or exec().

4. Deprecated Methods:

   • Check for undocumented changes (last release: 2019). Test edge cases.

Debugging Tips

1. Inspect Raw Output:

   echo $builder->getCommand(); // Debug the generated shell string.
   

2. Validate Syntax:

   • Test commands in a shell first, then integrate.
   • Example: echo "ls -a | grep test" | bash (sanity check).

3. Logging:

   Log::debug('Generated command:', ['command' => $builder->getCommand()]);
   

Extension Points

1. Custom Command Classes: Extend CommandBuilder for domain-specific methods:

   class ArtisanCommandBuilder extends CommandBuilder {
       public function migrate(): self {
           return $this->addArgument('migrate');
       }
   }
   

2. Dynamic Argument Injection: Use Laravel’s Str or Arr helpers to build arguments dynamically:

   $args = collect(['--env=local', '--force']);
   $builder->addArguments($args->toArray());
   

3. Integration with Laravel Tasks: Wrap in a service class for reusability:

   class DeploymentCommand {
       public function build(): CommandBuilder {
           return CommandBuilder::create('deploy')
               ->addFlag('prod')
               ->onFailure('slack')
                   ->addArgument('--alert');
       }
   }
   

4. Environment Variables: Replace placeholders with Laravel’s .env:

   ->addArgument(env('APP_STORAGE_PATH'));