The ProgressBar class allows you to display progress indicators in the application’s taskbar (Windows) or dock icon (macOS).
Creating a Progress Bar
use Native\Desktop\ProgressBar;
$progress = ProgressBar::create(100);
$progress->start();
// Update progress
for ($i = 0; $i < 100; $i++) {
performWork();
$progress->advance();
}
$progress->finish();
Methods
create()
Create a new progress bar with a maximum number of steps.
The total number of steps in the operation
Returns a new ProgressBar instance
$progress = ProgressBar::create(50);
start()
Start the progress bar at 0%.
advance()
Advance the progress bar by the specified number of steps.
Number of steps to advance (default: 1)
// Advance by 1 step
$progress->advance();
// Advance by multiple steps
$progress->advance(5);
setProgress()
Set the progress to a specific step.
$progress->setProgress(25); // 50% complete if maxSteps is 50
finish()
Mark the progress as complete and hide the indicator.
Complete Examples
File Processing
use Native\Desktop\ProgressBar;
$files = Storage::disk('documents')->files();
$progress = ProgressBar::create(count($files));
$progress->start();
foreach ($files as $file) {
processFile($file);
$progress->advance();
}
$progress->finish();
Database Migration
$records = User::all();
$total = $records->count();
$progress = ProgressBar::create($total);
$progress->start();
foreach ($records as $record) {
migrateRecord($record);
$progress->advance();
}
$progress->finish();
Download with Progress
use GuzzleHttp\Client;
use Native\Desktop\ProgressBar;
$client = new Client();
$url = 'https://example.com/large-file.zip';
$totalSize = 1024 * 1024 * 100; // 100MB
$progress = ProgressBar::create($totalSize);
$progress->start();
$client->get($url, [
'sink' => $destination,
'progress' => function ($total, $downloaded) use ($progress) {
$progress->setProgress((int) $downloaded);
},
]);
$progress->finish();
Batch Processing
$batches = array_chunk($items, 100);
$progress = ProgressBar::create(count($batches));
$progress->start();
foreach ($batches as $batch) {
processBatch($batch);
$progress->advance();
}
$progress->finish();
Throttling
The ProgressBar automatically throttles updates to prevent excessive rendering:
- Minimum interval: 0.1 seconds between updates
- Maximum interval: 1 second between updates
- Updates always occur when reaching 100% completion
// Even with rapid updates, the visual progress is throttled
$progress = ProgressBar::create(10000);
$progress->start();
for ($i = 0; $i < 10000; $i++) {
$progress->advance(); // Visual updates are throttled
}
$progress->finish(); // Always updates immediately
Progress is shown as a bar under the dock icon.// macOS shows progress in the dock
$progress = ProgressBar::create(100);
$progress->start();
Progress is shown on the taskbar button.// Windows shows progress in the taskbar
$progress = ProgressBar::create(100);
$progress->start();
Support varies by desktop environment. Unity shows progress in the launcher.// Linux support depends on DE
$progress = ProgressBar::create(100);
$progress->start();
Best Practices
Always call finish(): Make sure to call finish() when the operation completes, even if there’s an error. This removes the progress indicator.
Use try/finally: Wrap progress operations in try/finally blocks to ensure cleanup.
$progress = ProgressBar::create($total);
$progress->start();
try {
foreach ($items as $item) {
processItem($item);
$progress->advance();
}
} finally {
$progress->finish();
}
Don’t create multiple progress bars: Only one progress bar should be active at a time. Creating multiple instances will cause them to conflict.