Progress Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require moox/progress
   php artisan moox:install
   

   • The moox:install command publishes config files (if any) and sets up default progress bar configurations in config/moox-progress.php.

2. First Use Case: Use the ProgressBar facade to display a progress bar in a Laravel command:

   use Moox\Progress\Facades\ProgressBar;
   
   // Inside a command's handle() method
   $progress = ProgressBar::create('Processing items...', 100);
   for ($i = 0; $i <= 100; $i++) {
       $progress->advance();
       // Simulate work
       sleep(0.1);
   }
   

3. Where to Look First:

   • Facade: Moox\Progress\Facades\ProgressBar (primary entry point).
   • Config: config/moox-progress.php (customize appearance, formats, and behavior).
   • Documentation: User Guide for advanced usage (e.g., custom formats, async progress).

Implementation Patterns

Core Workflows

1. Basic Progress Bar:

   $progress = ProgressBar::create('Task Name', $totalItems);
   foreach ($items as $item) {
       $progress->advance();
       // Process $item
   }
   

2. Custom Formats: Override the default format in the config or dynamically:

   $progress = ProgressBar::create('Custom Format', 100)
       ->setFormat('|%current%/%max%| %bar% %percentage%');
   

3. Async Progress (e.g., Queues): Use the ProgressBar::async() method to track progress in background jobs:

   $progressId = ProgressBar::async('Queue Job', 100);
   // Later, update progress from a job:
   ProgressBar::update($progressId, $current);
   

4. Integration with Laravel Jobs: Attach progress to a job and update it in handle():

   class ProcessItemsJob implements ShouldQueue {
       protected $progressId;
   
       public function __construct() {
           $this->progressId = ProgressBar::async('ProcessItemsJob', 100);
       }
   
       public function handle() {
           foreach ($items as $item) {
               // Process $item
               ProgressBar::update($this->progressId, $current++);
           }
       }
   }
   

5. Nested Progress Bars: Use ProgressBar::createNested() for hierarchical progress:

   $parent = ProgressBar::create('Parent Task', 3);
   foreach ($tasks as $task) {
       $child = ProgressBar::createNested($parent, 'Child Task', 100);
       // Process child task
       $child->finish();
   }
   $parent->finish();
   

Integration Tips

• Artisan Commands: Use ProgressBar in handle() for CLI feedback.
• API Responses: Return progress IDs in responses and poll for updates via AJAX.
• Testing: Mock ProgressBar in unit tests:

  $progress = Mockery::mock('overload:Moox\Progress\Facades\ProgressBar');
  $progress->shouldReceive('create')->andReturnSelf();
  

Gotchas and Tips

Pitfalls

1. Async Progress Leaks:

   • Issue: Forgetting to call ProgressBar::finish() or ProgressBar::delete() for async bars can clutter memory.
   • Fix: Use try-catch-finally to ensure cleanup:

     try {
         $progressId = ProgressBar::async('Task', 100);
         // Work...
     } finally {
         ProgressBar::delete($progressId);
     }
     

2. Config Overrides:

   • Issue: Global config changes may not reflect in existing progress bars.
   • Fix: Recreate the progress bar or call ->setConfig() dynamically:

     $progress->setConfig(['format' => 'custom']);
     

3. Thread Safety:

   • Issue: Async progress bars are not thread-safe by default.
   • Fix: Use ProgressBar::async()->lock() for concurrent updates (if supported in future versions).

4. Performance Overhead:

   • Issue: Frequent advance() calls in tight loops may slow down processing.
   • Fix: Batch updates (e.g., advance(10) instead of 10 individual calls).

Debugging

• Missing Progress Bars:

  • Check if the moox:install command ran successfully (publishes config/blade views).
  • Verify the ProgressBar facade is properly aliased in config/app.php.

• Stuck Progress Bars:

  • Ensure advance() is called with values ≤ $max.
  • Check for unhandled exceptions in async updates.

Extension Points

1. Custom Formats: Extend the ProgressBar class to add new formats:

   class CustomProgressBar extends \Moox\Progress\ProgressBar {
       public function customFormat() {
           return $this->setFormat('|%elapsed%/%estimated| %bar%');
       }
   }
   

2. Event Listeners: Listen for progress events (e.g., progress.advanced):

   ProgressBar::listen('progress.advanced', function ($progress) {
       Log::info("Advanced to {$progress->current}");
   });
   

3. Blade Directives: Use the @progress directive in views to display async bars:

   @progress('queue-job-123')
   

4. Testing Hooks: Override the ProgressBar resolver in tests:

   ProgressBar::swap(new MockProgressBar());
   

Config Quirks

• Default Values: The package uses sensible defaults (e.g., format: "%current%/%max% [%bar%] %percentage%").
• Dynamic Updates: Async bars require a unique ID (e.g., job ID or UUID). Avoid collisions.
• Output Drivers: Supports CLI, Blade, and JSON (for APIs). Configure in config/moox-progress.php:

  'output' => [
      'driver' => 'cli', // or 'blade', 'json'
      'blade_view' => 'progress::bar',
  ],