Task
class Task extends Prompt
Traits
Track bounded incremental output owned by a Task operation.
Constants
| protected OUTPUT_CONTEXT_KEY |
Context key for the output instance override. |
| protected VALIDATE_USING_CONTEXT_KEY |
Context key for the custom validation callback override. |
| protected LOGGER_WRITE_TIMEOUT_SECONDS |
How long a Logger write may make no progress. This must remain well above the public render interval. |
| protected RENDERER_SETTLEMENT_MARGIN_MILLISECONDS |
Scheduling margin added to one complete renderer frame interval. Reset can arrive while the renderer is sleeping between frames. |
| protected RENDERER_ACKNOWLEDGEMENT |
The raw reverse-channel acknowledgement byte. Parent-to-renderer messages use TaskFrame; this single byte travels in the opposite direction only after the renderer has settled completely. |
Properties
| static protected bool | $cursorHidden | Indicates if the cursor has been hidden. |
from Cursor |
| protected Closure>> | $listeners | The registered event listeners. |
from Events |
| static protected bool | $shouldFallback | Whether to fallback to a custom implementation. |
from Fallback |
| static protected array<class-string, Closure(static): mixed> | $fallbacks | The fallback implementations. |
from Fallback |
| static protected bool|null | $interactive | Whether to render the prompt interactively. |
from Interactivity |
| static protected string | $theme | The name of the active theme. |
from Themes |
| static protected Prompt>, class-string<callable&object>>> | $themes | The available themes. |
from Themes |
| string | $state | The current state of the prompt. |
from Prompt |
| string | $error | The error message from the validator. |
from Prompt |
| string | $cancelMessage | The cancel message displayed when this prompt is cancelled. |
from Prompt |
| protected string | $prevFrame | The previously rendered frame. |
from Prompt |
| protected int | $newLinesWritten | How many new lines were written by the last output. |
from Prompt |
| bool|string | $required | Whether user input is required. |
from Prompt |
| Closure|null | $transform | The transformation callback. |
from Prompt |
| mixed | $validate | The validator callback or rules. |
from Prompt |
| static protected Closure|null | $cancelUsing | The cancellation callback. |
from Prompt |
| protected bool | $validated | Indicates if the prompt has been validated. |
from Prompt |
| protected bool | $terminalStateRestored | Indicates whether this prompt's terminal state has been restored. |
from Prompt |
| static protected Closure|null | $validateUsing | The custom validation callback. |
from Prompt |
| static protected Closure|null | $revertUsing | The revert handler from the StepBuilder. |
from Prompt |
| static protected OutputInterface|null | $output | The output instance. |
from Prompt |
| static protected Terminal|null | $terminal | The terminal instance. |
from Prompt |
| protected int|null | $partialStartIndex | The log index where the current partial started, or null if not streaming. |
from TracksTaskOutput |
| protected int | $minWidth | The minimum width for the longest line calculation. |
|
| int | $interval | How long to wait between rendering each frame. |
|
| int | $count | The number of times the task has been rendered. |
|
| bool | $static | Whether the task can only be rendered once. |
|
| protected int|null | $pid | The process ID after forking. |
|
| protected null|resource | $socket | The socket for IPC communication. |
|
| protected mixed | $originalSignalHandler | The signal handler replaced by the process renderer. |
|
| protected bool|null | $originalAsync | The async-signal mode replaced by the process renderer. |
|
| array<int, string> | $logs | Pre-wrapped log lines for the scrolling output area. |
|
| list<array{type: string, message: string}> | $stableMessages | Stable status messages (success, warning, error). |
|
| int | $maxStableMessages | The maximum number of stable messages to display. |
|
| string | $identifier | The identifier retained for Laravel-compatible Task and Logger extension state. |
|
| bool | $finished | Whether the task has finished. |
Methods
Erase the given number of lines downwards from the cursor position.
Fake the terminal and queue key presses to be simulated.
Implementation of the looping mechanism for simulating key presses.
Assert that the output contains the given string.
Assert that the output doesn't contain the given string.
Assert that the stripped output contains the given string.
Assert that the stripped output doesn't contain the given string.
Get the buffered console output, stripped of escape sequences.
Whether the prompt should fallback to a custom implementation.
Get the current value of the prompt.
Validate rules intrinsic to the prompt type.
Disable prompting for input.
Capture the number of new lines written by the last output.
Write output directly, bypassing newline capture.
Write a rendered frame using the output's decoration setting.
Determine whether the given value is invalid when the prompt is required.
Clean up after the task.
Multi-byte version of wordwrap.
Word wrap text while preserving ANSI escape sequences.
Truncate visible ANSI text without cutting a control sequence.
Parse text into segments with their associated ANSI codes.
Update the bounded set of active SGR attributes.
Get the length of the longest line.
Pad text ignoring ANSI escape sequences.
Replace the last visible grapheme while preserving trailing formatting.
Strip ANSI escape sequences from the given text.
Replace the in-progress partial with a complete supplied prefix.
Create a new Task instance.
Receive and process messages from the parent process.
Apply one decoded Task message.
Recompute the stable-message budget based on the current sub-label state.
Trim stable messages to the current display budget.
Reset state owned by one task operation.
Determine whether the final task summary should remain visible.
Finish rendering the task and clear it unless the summary should remain.
Reset the terminal after process rendering.
Print a single-line completion indicator after the task has finished.
Create the process renderer socket pair.
Fork the process renderer.
Run the child process renderer.
Capture and replace the process renderer's signal state.
Restore signal state replaced by the process renderer.
Wait for the child renderer to close its socket.
Close the parent process socket.
Terminate the owned child renderer.
Reap the owned child renderer.
Clear the lines rendered by the task.
Details
in
Colors at line 12
string
reset(string $text)
Reset all colors and styles.
in
Colors at line 20
string
bold(string $text)
Make the text bold.
in
Colors at line 28
string
dim(string $text)
Make the text dim.
in
Colors at line 36
string
italic(string $text)
Make the text italic.
in
Colors at line 44
string
underline(string $text)
Underline the text.
in
Colors at line 52
string
inverse(string $text)
Invert the text and background colors.
in
Colors at line 60
string
hidden(string $text)
Hide the text.
in
Colors at line 68
string
strikethrough(string $text)
Strike through the text.
in
Colors at line 76
string
black(string $text)
Set the text color to black.
in
Colors at line 84
string
red(string $text)
Set the text color to red.
in
Colors at line 92
string
green(string $text)
Set the text color to green.
in
Colors at line 100
string
yellow(string $text)
Set the text color to yellow.
in
Colors at line 108
string
blue(string $text)
Set the text color to blue.
in
Colors at line 116
string
magenta(string $text)
Set the text color to magenta.
in
Colors at line 124
string
cyan(string $text)
Set the text color to cyan.
in
Colors at line 132
string
white(string $text)
Set the text color to white.
in
Colors at line 140
string
bgBlack(string $text)
Set the text background to black.
in
Colors at line 148
string
bgRed(string $text)
Set the text background to red.
in
Colors at line 156
string
bgGreen(string $text)
Set the text background to green.
in
Colors at line 164
string
bgYellow(string $text)
Set the text background to yellow.
in
Colors at line 172
string
bgBlue(string $text)
Set the text background to blue.
in
Colors at line 180
string
bgMagenta(string $text)
Set the text background to magenta.
in
Colors at line 188
string
bgCyan(string $text)
Set the text background to cyan.
in
Colors at line 196
string
bgWhite(string $text)
Set the text background to white.
in
Colors at line 204
string
gray(string $text)
Set the text color to gray.
in
Cursor at line 19
void
hideCursor()
Hide the cursor.
in
Cursor at line 35
void
showCursor()
Show the cursor.
in
Cursor at line 51
void
restoreCursor()
Restore the cursor if it was hidden.
in
Cursor at line 61
void
moveCursor(int $x, int $y = 0)
Move the cursor.
in
Cursor at line 87
void
moveCursorToColumn(int $column)
Move the cursor to the given column.
in
Cursor at line 99
void
moveCursorUp(int $lines)
Move the cursor up by the given number of lines.
in
Cursor at line 114
static void
resetCursor()
Reset cursor state to defaults.
Clears worker-wide cursor visibility tracking; concurrent prompts may restore cursor state differently depending on timing.
in
Erase at line 12
void
eraseLines(int $count)
Erase the given number of lines downwards from the cursor position.
in
Erase at line 31
void
eraseDown()
Erase from cursor until end of screen.
in
Events at line 29
void
emit(string $event, mixed ...$data)
Emit an event.
in
Events at line 39
void
clearListeners()
Clean the event listeners.
in
FakesInputOutput at line 25
static void
fake(array $keys = [])
Fake the terminal and queue key presses to be simulated.
Swaps prompt terminal and output state for the worker lifetime.
in
FakesInputOutput at line 63
static void
fakeKeyPresses(array $keys, callable $callable)
Implementation of the looping mechanism for simulating key presses.
By ignoring the $callable parameter which contains the default logic
for simulating fake key presses, we can use a custom implementation
to emit key presses instead, allowing us to use different inputs.
in
FakesInputOutput at line 73
static void
assertOutputContains(string $string)
Assert that the output contains the given string.
in
FakesInputOutput at line 81
static void
assertOutputDoesntContain(string $string)
Assert that the output doesn't contain the given string.
in
FakesInputOutput at line 89
static void
assertStrippedOutputContains(string $string)
Assert that the stripped output contains the given string.
in
FakesInputOutput at line 97
static void
assertStrippedOutputDoesntContain(string $string)
Assert that the stripped output doesn't contain the given string.
in
FakesInputOutput at line 105
static string
content()
Get the buffered console output.
in
FakesInputOutput at line 117
static string
strippedContent()
Get the buffered console output, stripped of escape sequences.
in
Fallback at line 40
static void
fallbackWhen(bool $condition)
Enable the fallback implementation.
in
Fallback at line 53
static bool
shouldFallback()
Whether the prompt should fallback to a custom implementation.
in
Fallback at line 70
static void
fallbackUsing(Closure $fallback)
Set the fallback implementation.
in
Fallback at line 84
mixed
fallback()
Call the registered fallback implementation.
in
Fallback at line 107
static void
resetFallback()
Reset fallback state to defaults.
Clears worker-wide prompt fallback configuration; concurrent prompts may render with different fallback behavior depending on timing.
in
Interactivity at line 29
static void
interactive(bool $interactive = true)
Set interactive mode.
in
Interactivity at line 41
static bool|null
isInteractive()
Determine if the prompt is interactive.
in
Interactivity at line 57
static void
resetInteractivity()
Reset interactivity state to defaults.
Clears worker-wide prompt interactivity configuration; concurrent prompts may render with different interactivity depending on timing.
in
Interactivity at line 67
protected mixed
default()
Return the default value if it passes validation.
in
Themes at line 118
static string
theme(string|null $name = null)
Get or set the active theme.
A given theme persists in a static property for the worker lifetime and applies to every subsequent prompt render.
in
Themes at line 140
static void
addTheme(string $name, array $renderers)
Add a new theme.
Themes persist in a static property for the worker lifetime and are available to every subsequent prompt render.
in
Themes at line 153
protected callable
getRenderer()
Get the renderer for the current prompt.
in
Themes at line 168
protected string
renderTheme()
Render the prompt using the active theme.
in
Themes at line 181
static void
resetTheme()
Reset theme state to defaults.
Clears worker-wide prompt theme configuration; concurrent prompts may render with different themes depending on timing.
at line 838
mixed
value()
Get the current value of the prompt.
in
Prompt at line 141
string|null
validateIntrinsic(mixed $value)
Validate rules intrinsic to the prompt type.
at line 829
mixed
prompt()
Disable prompting for input.
in
Prompt at line 241
mixed
runLoop(callable $callable)
Implementation of the prompt looping mechanism.
in
Prompt at line 264
static void
cancelUsing(Closure|null $callback)
Register a callback to be invoked when a user cancels a prompt.
The callback persists in a static property for the worker lifetime and runs on every subsequent prompt cancellation.
in
Prompt at line 273
int
newLinesWritten()
How many new lines were written by the last output.
in
Prompt at line 281
protected void
capturePreviousNewLines()
Capture the number of new lines written by the last output.
in
Prompt at line 291
static void
setOutput(OutputInterface $output)
Set the output instance.
in
Prompt at line 303
static protected OutputInterface
output()
Get the current output instance.
in
Prompt at line 315
static protected void
writeDirectly(string $message)
Write output directly, bypassing newline capture.
in
Prompt at line 335
protected void
restoreTerminalState()
Restore terminal state changed by the prompt operation.
in
Prompt at line 370
static void
validateUsing(Closure $callback)
Set the custom validation callback.
in
Prompt at line 382
static protected Closure|null
getValidateUsing()
Get the custom validation callback.
in
Prompt at line 396
static void
revertUsing(Closure $callback)
| internal |
Revert the prompt using the given callback.
in
Prompt at line 406
static void
preventReverting()
| internal |
Clear any previous revert callback.
in
Prompt at line 414
protected void
render()
Render the prompt.
in
Prompt at line 448
protected void
writeFrame(string $frame)
Write a rendered frame using the output's decoration setting.
in
Prompt at line 467
protected void
submit()
Submit the prompt.
in
Prompt at line 540
protected mixed
transformedValue()
Get the transformed value of the prompt.
in
Prompt at line 588
protected bool
isInvalidWhenRequired(mixed $value)
Determine whether the given value is invalid when the prompt is required.
in
Prompt at line 606
static void
flushState()
Flush all static state.
at line 856
__destruct()
Clean up after the task.
in
InteractsWithAnsi at line 16
protected string
mbWordwrap(string $string, int $width = 75, string $break = "\n", bool $cut_long_words = false)
Multi-byte version of wordwrap.
in
InteractsWithAnsi at line 109
protected array
ansiWordwrap(string $text, int $width, bool $cutLongWords = false)
Word wrap text while preserving ANSI escape sequences.
in
InteractsWithAnsi at line 134
protected string
truncateAnsi(string $text, int $width)
Truncate visible ANSI text without cutting a control sequence.
in
InteractsWithAnsi at line 246
protected array
parseAnsiText(string $text)
Parse text into segments with their associated ANSI codes.
in
InteractsWithAnsi at line 358
protected void
updateSgrState(array $activeSgr, string $escape)
Update the bounded set of active SGR attributes.
in
InteractsWithStrings at line 19
protected int
longest(array $lines, int $padding = 0)
Get the length of the longest line.
in
InteractsWithStrings at line 30
protected string
pad(string $text, int $length, string $char = ' ')
Pad text ignoring ANSI escape sequences.
in
InteractsWithStrings at line 40
protected string
replaceLastVisibleGrapheme(string $line, string $replacement)
Replace the last visible grapheme while preserving trailing formatting.
in
InteractsWithStrings at line 71
protected string
stripEscapeSequences(string $text)
Strip ANSI escape sequences from the given text.
in
TracksTaskOutput at line 94
protected void
addLogLines(string $line)
Add a complete logical log message.
in
TracksTaskOutput at line 109
protected void
replacePartialLines(string $text)
Replace the in-progress partial with a complete supplied prefix.
at line 124
__construct(string $label = '', int $limit = 10, bool $keepSummary = false, string|null $subLabel = null)
Create a new Task instance.
at line 144
mixed
run(Closure $callback)
Render the task and execute the callback.
at line 190
protected void
receiveMessages(resource $socket)
Receive and process messages from the parent process.
at line 210
void
applyMessage(string|null $type, string $payload)
| internal |
Apply one decoded Task message.
at line 268
protected void
recalculateMaxStableMessages()
Recompute the stable-message budget based on the current sub-label state.
at line 278
protected void
trimStableMessages()
Trim stable messages to the current display budget.
at line 288
protected void
resetOperationState()
Reset state owned by one task operation.
at line 304
protected bool
shouldKeepSummary()
Determine whether the final task summary should remain visible.
at line 312
protected void
finishRendering(bool $renderFinalFrame = false, bool $success = true)
Finish rendering the task and clear it unless the summary should remain.
at line 334
protected void
resetTerminal(bool $originalAsync, bool $success = true)
Reset the terminal after process rendering.
at line 348
protected void
printCompletionLine()
Print a single-line completion indicator after the task has finished.
at line 363
protected mixed
renderInProcess(Closure $callback)
Render the task using a child process for the animation loop.
at line 489
protected array|false
createSocketPair()
Create the process renderer socket pair.
Subclasses and tests override this seam to exercise socket setup failures without replacing the process-rendering lifecycle.
at line 500
protected int
forkProcess()
Fork the process renderer.
Subclasses and tests override this seam to exercise fork and reaping failures without injecting a process abstraction.
at line 515
protected never
runRendererProcess(resource $socket)
Run the child process renderer.
When the caller ignores SIGCHLD or sets SA_NOCLDWAIT, the parent cannot obtain an exit status. Subclasses that complete settlement must write static::RENDERER_ACKNOWLEDGEMENT before closing their socket or the renderer will be reported as failed in that configuration.
at line 558
protected void
captureSignalState()
Capture and replace the process renderer's signal state.
at line 571
protected void
restoreSignalState()
Restore signal state replaced by the process renderer.
at line 610
protected bool
awaitRendererClosure()
Wait for the child renderer to close its socket.
at line 637
protected void
closeSocket()
Close the parent process socket.
at line 648
protected void
terminateRenderer()
Terminate the owned child renderer.
at line 658
protected RuntimeException|null
reapRenderer(bool $requireSuccess, bool $acknowledged = false)
Reap the owned child renderer.
at line 708
protected mixed
renderStatically(Closure $callback)
Render a static version of the task.
at line 749
protected mixed
renderInCoroutine(Closure $callback)
Render the task using a coroutine for the animation loop.
Uses the same in-process Task instance instead of socket IPC.
at line 846
protected void
eraseRenderedLines()
Clear the lines rendered by the task.