 |
VOOZH | about |
|
VOOZH | about |
This document covers the progress bar and spinner display components for visualizing long-running operations. Progress bars are used when operations have a known number of steps (countable iterations), while spinners indicate indeterminate operations of unknown duration.
These are non-interactive display components that extend the base Prompt class but do not accept user input. For interactive prompts that accept user choices, see Interactive Prompts. For other display utilities like tables and notes, see Tables and Notes and Messages.
Sources: src/Progress.php1-216 src/helpers.php135-254
The Progress class provides visual feedback for countable operations, rendering a progress bar that updates as work completes.
Sources: src/Progress.php12-216 src/helpers.php233-254
The Progress class uses PHP generics to preserve type information:
@template TSteps of iterable<mixed>|int
This allows two modes of operation:
Progress<int> iterates from 0 to N-1Progress<iterable<T>> iterates over collection itemsThe map() method's callback signature adapts accordingly:
Closure(int $index, Progress): TReturnClosure(T $item, Progress): TReturnSources: src/Progress.php13-14 src/Progress.php54-57
The map() method provides the simplest interface for progress bars, automatically managing the lifecycle while processing each item.
Sources: src/Progress.php59-95 src/helpers.php233-254
| Aspect | Implementation |
|---|---|
| Entry Point | map(Closure $callback): array src/Progress.php59 |
| Initialization | Calls start() to set state and hide cursor src/Progress.php61 |
| Integer Mode | for ($i = 0; $i < $this->steps; ++$i) src/Progress.php67 |
| Iterable Mode | foreach ($this->steps as $step) src/Progress.php72 |
| Callback Invocation | $result[] = $callback($item, $this) src/Progress.php68-73 |
| Progress Update | $this->advance() after each callback src/Progress.php69-74 |
| Error Handling | Catch Throwable, set error state, restore cursor src/Progress.php77-83 |
| Completion | Call finish() to restore terminal state src/Progress.php92 |
| Return Value | Array of callback return values src/Progress.php94 |
Sources: src/Progress.php59-95
When a hint is provided, the progress bar pauses briefly (250ms) after completion to ensure the final hint is visible before the display is cleared:
This prevents the hint from appearing to be skipped when operations complete rapidly.
Sources: src/Progress.php86-90
For scenarios requiring explicit control over progress updates, the Progress instance can be managed manually through its lifecycle methods.
Sources: src/Progress.php100-141
| Method | Signature | Purpose |
|---|---|---|
| start() | public function start(): void | Initializes display, hides cursor, sets up signal handlers src/Progress.php100-116 |
| advance() | public function advance(int $step = 1): void | Increments progress counter by specified amount src/Progress.php121-130 |
| finish() | public function finish(): void | Marks completion, restores cursor, cleans up signals src/Progress.php135-141 |
| label() | public function label(string $label): static | Updates the display label dynamically src/Progress.php154-159 |
| hint() | public function hint(string $hint): static | Updates the hint text dynamically src/Progress.php164-169 |
| render() | public function render(): void | Forces immediate re-render src/Progress.php146-149 |
Sources: src/Progress.php100-169
The fluent interface allows chaining updates:
The render() method is automatically called by advance(), label(), and hint() to ensure visual updates.
Sources: src/Progress.php121-169
The $total property is computed during construction based on the $steps parameter:
| Steps Type | Calculation | Code |
|---|---|---|
int | Direct assignment | $this->total = $this->steps src/Progress.php40 |
| Countable iterable | count($this->steps) | src/Progress.php41 |
| Non-countable iterable | iterator_count($this->steps) | src/Progress.php42 |
An exception is thrown if $total is zero, as progress bars require at least one step.
Sources: src/Progress.php37-48
The advance() method includes overflow protection:
This ensures the progress never exceeds 100%, even if advance() is called more times than expected.
Sources: src/Progress.php123-127
The completion percentage is calculated as a simple ratio:
This returns a decimal value (0.0 to 1.0) representing completion percentage.
Sources: src/Progress.php174-177
Progress bars register signal handlers to gracefully handle interruption (Ctrl+C).
Sources: src/Progress.php104-111 src/Progress.php200-206
The signal handler is registered in start():
This captures the original async signals state and sets up a handler that:
'cancel'Sources: src/Progress.php104-111
The resetSignals() method restores original signal handling:
This is called by both finish() and in the exception handler during map().
Sources: src/Progress.php200-206 src/Progress.php81 src/Progress.php140
Spinners provide visual feedback for indeterminate operations where the total duration or number of steps is unknown.
Sources: src/helpers.php135-148
The spin() function signature:
The function:
Spinner instance with optional message@template annotationSources: src/helpers.php135-148
| Aspect | Progress Bar | Spinner |
|---|---|---|
| Use Case | Known number of steps | Unknown duration |
| Visual | Bar filling 0-100% | Rotating animation |
| Updates | Incremental (advance()) | Continuous animation |
| Completion | Reaches 100% | Stops when callback returns |
| API | map() or manual control | Single spin() call |
| Return Value | Array of results (map mode) | Callback return value |
The Progress class explicitly disables the prompt() method inherited from the base Prompt class:
This is by design—progress bars are display-only components and do not accept user input. Calling prompt() on a Progress instance will throw an exception.
Sources: src/Progress.php180-187
The required value() abstract method from Prompt returns a meaningless boolean:
This exists only to satisfy the abstract method requirement. Progress bars do not have a "value" in the sense that interactive prompts do.
Sources: src/Progress.php192-195
Despite being non-interactive, Progress extends Prompt to leverage shared infrastructure.
Sources: src/Progress.php15 src/Progress.php146-149 src/Progress.php180-195 src/Prompt.php281-310
Benefits of inheritance:
Prompt::$state for lifecycle trackingTerminal and OutputInterfaceProgressRendererhideCursor() and restoreCursor() methodsDrawbacks mitigated:
prompt() throws exception to prevent misusevalue() provides meaningless stubSources: src/Progress.php15 src/Prompt.php15-449
The constructor calculates the total number of steps based on the type of the $steps parameter.
Sources: src/Progress.php37-48
| Parameter | Type | Purpose |
|---|---|---|
$label | string | Display text above progress bar |
$steps | int|iterable | Either count or collection to iterate |
$hint | string | Optional guidance text (default: '') |
The constructor uses a match expression to determine the total:
Sources: src/Progress.php37-44
Key Concepts:
| Component | Purpose | Primary Method | Return Type |
|---|---|---|---|
| Progress Bar | Visualize countable operations | map(Closure) or manual control | array or Progress instance |
| Spinner | Indicate indeterminate operations | spin(Closure) | Callback return value |
Usage Patterns:
progress('Label', $items, fn($item, $bar) => ...)$bar = progress('Label', 100); $bar->start(); ... $bar->finish();spin(fn() => someOperation(), 'Loading...')Architecture Notes:
Prompt but are not interactivelabel() and hint() methodsRefresh this wiki