Omniterm Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require pdphilip/omniterm
   

   Add the HasOmniTerm trait to any Artisan command:

   use OmniTerm\HasOmniTerm;
   
   class MyCommand extends Command
   {
       use HasOmniTerm;
   }
   

2. First Use Case: Display a success message:

   $this->omni->success('Task completed');
   

   This renders a green "GOOD" badge with the message.

Where to Look First

• Built-in Components: Check the README's "Built-in Components" section for ready-to-use UI elements like status messages, progress bars, and tables.
• Samples: Run the demo commands to see OmniTerm in action:

  php artisan omniterm:full-demo
  

• Tailwind-for-Terminal: Explore the Tailwind CSS classes supported by OmniTerm (e.g., text-sky-500, bg-gradient-to-r).

Implementation Patterns

Core Workflows

1. Status Messages: Use for one-line feedback or detailed status blocks:

   // One-liner
   $this->omni->warning('Check your config');
   
   // Detailed block
   $this->omni->statusError('Connection Failed', 'Could not reach database', ['Check .env', 'Ensure MySQL is running']);
   

2. Progress Bars: Fluent API for tracking progress with customizable styles:

   $bar = $this->omni->progressBar(100)->framed()->gradient('rose', 'sky');
   $bar->start();
   foreach ($items as $item) { $bar->advance(); }
   $bar->finish();
   

3. Live Tasks: Run async operations with real-time feedback:

   $result = $this->omni->task('Processing data...', fn() => sleep(3), Spinner::Sand);
   

4. Data Tables: Display structured data with status indicators:

   $this->omni->tableHeader('Setting', 'Value', 'Notes');
   $this->omni->tableRowSuccess('Connection', 'Active');
   

Integration Tips

• Blade Templates: Render reusable CLI views:

  $this->omni->view('cli.deploy-status', ['badge' => 'DEPLOY', 'color' => 'emerald']);
  

  Store templates in resources/views/cli/.

• Dynamic Content: Use liveView() for real-time updates:

  $live = $this->omni->liveView('<div>Starting...</div>');
  for ($i = 0; $i < 100; $i++) {
      $live->reRender("<div>Progress: {$i}%</div>");
  }
  

• Terminal Dimensions: Adapt layouts to screen size:

  $width = $this->omni->terminal()->getWidth();
  $this->omni->render('<div class="w-' . min($width, 80) . '">...</div>');
  

• Async Operations: Combine with Laravel queues for long-running tasks:

  $job = ProcessData::dispatch();
  $this->omni->task('Processing in queue...', fn() => $job->wait());
  

Common Patterns

Gotchas and Tips

Pitfalls

1. Terminal Compatibility:

   • Truecolor vs. 256-color: OmniTerm auto-detects but complex gradients may render poorly in older terminals (e.g., macOS Terminal). Test in iTerm2 or WezTerm for best results.
   • Fallback Colors: If RGB colors appear as blocks, your terminal lacks truecolor support. Use predefined Tailwind shades (text-sky-500) for reliability.

2. Performance:

   • Live Updates: Frequent reRender() calls can lag. Batch updates or use usleep() for delays:

     usleep(100000); // 100ms delay
     

   • Large Tables: Avoid rendering thousands of rows at once. Use pagination or lazy-loading.

3. Blade Caching:

   • Clear cached views if Blade templates don’t update:

     php artisan view:clear
     

4. Spinner Sync:

   • Async tasks (runTask) may desync if the callback completes faster than the spinner’s animation frame. Add small delays if needed:

     $this->omni->runTask('Slow task...', fn() => usleep(500000) || true);
     

5. Gradient Limits:

   • Gradients (bg-gradient-to-r) work best on single-line elements. Multi-line gradients may render unevenly.

Debugging Tips

1. ANSI Output Inspection: Pipe output to a file to debug ANSI sequences:

   php artisan my:command > output.ansi
   

   Use a tool like ANSI Escape to visualize.

2. Terminal Emulator:

   • WezTerm or Alacritty provide better debugging for ANSI issues than default terminal apps.

3. Logging Raw HTML: Log the HTML before rendering to verify classes:

   $html = '<div class="text-[255,0,0]">Test</div>';
   $this->info($html); // Log raw HTML
   $this->omni->render($html);
   

4. Component Isolation: Test components in isolation using the sample commands:

   php artisan omniterm:progress-bars
   

Extension Points

1. Custom Spinners: Extend the Spinner enum or create a custom animation by overriding the render() method in a subclass of OmniTerm\Async\Spinner.

2. New Components: Build reusable components by combining render() and Blade templates:

   // app/Console/Components/HealthCheck.php
   class HealthCheck {
       public function __invoke(OmniTerm $omni, array $services) {
           $omni->titleBar('Service Health');
           foreach ($services as $name => $status) {
               $omni->tableRow($name, $status['status'], $status['details'] ?? '');
           }
       }
   }
   

3. Color Palettes: Create a helper to generate consistent color schemes:

   function getThemeColors(string $theme): array {
       return match ($theme) {
           'dark' => ['bg-zinc-900', 'text-zinc-100'],
           'light' => ['bg-white', 'text-zinc-800'],
           default => ['bg-gray-100', 'text-gray-900'],
       };
   }
   

4. Event Listeners: Hook into OmniTerm’s lifecycle (e.g., after rendering) by extending the OmniTerm class and overriding methods like render().

5. Custom Terminal Detection: Override OmniTerm\Terminal::detect() to add support for niche terminals or enforce specific modes.

Configuration Quirks

1. No Config File: OmniTerm is zero-config. All settings are runtime-based (e.g., terminal detection, color fallback).

2. Global Defaults: Set defaults for all commands via a service provider:

   OmniTerm::setDefaultSpinner(Spinner::DotsCircle);
   OmniTerm::setDefaultProgressColor('indigo');
   

3. Environment-Specific Rendering: Use Laravel’s environment detection to adjust output:

   if (app()->environment('local')) {
       $this->omni->render('<div class="text-yellow-500">DEBUG MODE</div>');
   }
   

Pro Tips

1. Combine with Laravel Notifications: Render OmniTerm output in scheduled jobs or notifications:

   $notification = new OmniTermNotification($this->omni->parse('<div class="text-red-500">Alert!</div>'));
   

2. CI/CD Integration: Use OmniTerm in GitHub Actions