Cli Tools Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require code-lts/cli-tools
   

   Ensure your project uses PHP 8.1+, PHPUnit 12, and Symfony Console v8 (or later).

2. Basic Error Formatting:

   use CodeLts\CliTools\Error;
   use CodeLts\CliTools\AnalysisResult;
   use CodeLts\CliTools\OutputFormat;
   
   $errors = [new Error("Test error", __FILE__, 10)];
   $result = new AnalysisResult($errors, [], [], []);
   
   OutputFormat::displayUserChoiceFormat(
       OutputFormat::OUTPUT_FORMAT_TABLE,
       $result,
       base_path(),
       new \Symfony\Component\Console\Output\ConsoleOutput()
   );
   

3. Key Classes to Know:

   • Error: Represents file-specific errors with messages, paths, and line numbers.
   • AnalysisResult: Aggregates errors, warnings, and internal issues.
   • OutputFormat: Handles output formatting (JUnit, GitLab, TeamCity, etc.).
   • SymfonyOutput: Laravel-friendly output wrapper (extend \Symfony\Component\Console\Output\OutputInterface).

4. First Use Case: Format PHPStan/PHPUnit errors for CI/CD pipelines (e.g., GitLab, GitHub Actions) or local development with colored tables.

Implementation Patterns

Core Workflows

1. Error Collection and Formatting

• Pattern: Centralize error handling in a service class.

  class StaticAnalysisService {
      public function analyze(string $file): AnalysisResult {
          $errors = $this->detectIssues($file);
          return new AnalysisResult($errors, [], [], []);
      }
  
      public function outputResults(AnalysisResult $result): void {
          OutputFormat::displayUserChoiceFormat(
              OutputFormat::OUTPUT_FORMAT_GITHUB,
              $result,
              base_path(),
              app('console.output')
          );
      }
  }
  

• Laravel Integration: Use Laravel’s app('console.output') for seamless CLI output.

2. CI-Specific Outputs

• GitLab CI:

  OutputFormat::displayUserChoiceFormat(
      OutputFormat::OUTPUT_FORMAT_GITLAB,
      $result,
      base_path()
  );
  

• GitHub Actions:

  OutputFormat::displayUserChoiceFormat(
      OutputFormat::OUTPUT_FORMAT_GITHUB,
      $result,
      base_path()
  );
  

• TeamCity/JUnit:

  OutputFormat::displayUserChoiceFormat(
      OutputFormat::OUTPUT_FORMAT_TEAMCITY,
      $result,
      base_path()
  );
  

3. Dynamic Format Selection

• User Input:

  $format = $this->getUserInput('Select format: [table/gitlab/github]');
  OutputFormat::checkOutputFormatIsValid($format);
  

• CI Detection:

  if (\CodeLts\CliTools\Utils::isCiDetected()) {
      $format = OutputFormat::OUTPUT_FORMAT_GITLAB;
  } else {
      $format = OutputFormat::OUTPUT_FORMAT_TABLE;
  }
  

4. File Operations

• Write/Read Files:

  \CodeLts\CliTools\File\FileWriter::write('report.xml', $xmlContent);
  $content = \CodeLts\CliTools\File\FileReader::read('report.xml');
  

• Laravel Filesystem:

  use Illuminate\Support\Facades\Storage;
  
  Storage::put('report.xml', $xmlContent);
  $content = Storage::get('report.xml');
  

5. ANSI Escape Sequences

• Clear Line:

  $this->output->writeFormatted(\CodeLts\CliTools\File\AnsiEscapeSequences::ERASE_TO_LINE_END);
  

• Laravel Artisan Commands:

  $this->output->writeln('<comment>Processing...</comment>');
  $this->output->writeFormatted(AnsiEscapeSequences::ERASE_TO_LINE_END);
  $this->output->writeln('<info>Done!</info>');
  

Laravel-Specific Patterns

1. Artisan Commands

• Extend \Illuminate\Console\Command and inject SymfonyOutput:

  use CodeLts\CliTools\Symfony\SymfonyOutput;
  
  class AnalyzeCommand extends Command {
      protected $output;
  
      public function __construct() {
          parent::__construct();
          $this->output = new SymfonyOutput($this->getOutput());
      }
  
      protected function execute(InputInterface $input, OutputInterface $output): int {
          $result = $this->analyze();
          OutputFormat::displayUserChoiceFormat(
              OutputFormat::OUTPUT_FORMAT_TABLE,
              $result,
              base_path(),
              $this->output
          );
          return Command::SUCCESS;
      }
  }
  

2. Service Providers

• Register a facade or bind the package’s OutputFormat:

  $this->app->bind(\CodeLts\CliTools\OutputFormat::class, function () {
      return new \CodeLts\CliTools\OutputFormat();
  });
  

3. Testing

• Mock SymfonyOutput in tests:

  $mockOutput = $this->createMock(\Symfony\Component\Console\Output\OutputInterface::class);
  $output = new \CodeLts\CliTools\Symfony\SymfonyOutput($mockOutput);
  

4. Event Listeners

• Trigger formatting on events (e.g., jobs.failed):

  public function handle(JobFailed $event) {
      $errors = [$event->exception->getMessage()];
      $result = new AnalysisResult($errors, [], [], []);
      OutputFormat::displayUserChoiceFormat(
          OutputFormat::OUTPUT_FORMAT_TABLE,
          $result,
          base_path(),
          app('console.output')
      );
  }
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch

• Error: Class 'CodeLts\CliTools\Error' not found or PHP Fatal Error: Required parameter $message follows optional.
• Fix: Ensure PHP 8.1+ is used. Update composer.json:

  "require": {
      "php": "^8.1"
  }
  

2. Symfony Console Version Conflict

• Error: Class 'Symfony\Component\Console\Output\ConsoleOutput' not found.
• Fix: Upgrade Symfony Console to v8+:

  composer require symfony/console:^8.0
  

• Workaround: Use symfony/console:^5|^6 (but this violates the package’s requirements).

3. PHPUnit Version Issues

• Error: PHPUnit\Framework\TestSuite not found.
• Fix: Upgrade PHPUnit to v12:

  composer require phpunit/phpunit:^12.0
  

4. Line Number Nullability

• Gotcha: The Error class’s line property is nullable (PHP 8.1+ feature). Older code may throw:

  $error = new Error("Message", __FILE__, null); // Valid in v1.5.0+
  

• Fix: Ensure line numbers are int|null.

5. CI Detection Quirks

• Gotcha: Utils::isCiDetected() may return false in local Docker environments or custom CI setups.
• Fix: Extend the detection logic:

  if (\CodeLts\CliTools\Utils::isCiDetected() || getenv('CI') === 'true') {
      // CI logic
  }
  

6. ANSI Escape Sequence Incompatibility

• Gotcha: Some terminals (e.g., Windows CMD) may not support ANSI codes.
• Fix: Check isDecorated() before using ANSI sequences:

  if ($this->output->isDecorated()) {
      $this->output->writeFormatted(AnsiEscapeSequences::ERASE_TO_LINE_END);
  }
  

Debugging Tips

1. Validate Output Formats

• Always validate formats before use:

  try {
      OutputFormat::checkOutputFormatIsValid('invalid-format');
  } catch (\CodeLts\CliTools\Exceptions\FormatNotFoundException $e) {
      $this->error($e->getMessage());
  }
  

• Valid formats: OUTPUT_FORMAT_TABLE, OUTPUT_FORMAT_GITHUB, OUTPUT_FORMAT_GITLAB, etc. (see OutputFormat::VALID_OUTPUT_FORMATS).

2. Inspect AnalysisResult

• Dump the result to debug: