BackgroundJob
An immutable snapshot of one background job's state, as tracked by a {@see \Milpa\Live\Contracts\Tui\BackgroundJobManagerInterface}. `$status` MUST be one of `'running'`, `'done'`, `'failed'`, or `'canceled'`; every `with*()` method returns a new instance rather than mutating this one, so callers can never observe a job partway through a transition.
BackgroundJob::__construct()
public function __construct(string $id, string $label, string $status, string $command = '', float $progress = 0, array $output = [], ?int $exitCode = null, ?string $error = null, array $meta = []):Parameters
| Name | Type | Description |
|---|---|---|
| $id | string | A unique job id; MUST NOT be empty. |
| $label | string | Human-readable job description. |
| $status | string | One of `'running'`, `'done'`, `'failed'`, `'canceled'`. |
| $command | string | The command/operation this job represents, if applicable. |
| $progress | float | Fractional completion in `[0.0, 1.0]`. |
| $output | array<int, array{stream: string, line: string}> | Captured output lines in emission order. |
| $exitCode | (int | null) | Process exit code, once the job has finished/failed/been canceled. |
| $error | (string | null) | Failure reason, when `$status` is `'failed'`. |
| $meta | array<string, mixed> | Caller-defined extra context beyond the fields above. |
Throws
\InvalidArgumentException If `$id` is empty.
BackgroundJob::withOutput()
public function withOutput(string $line, string $stream = 'stdout'): selfReturns a copy with one more output line appended.
Parameters
| Name | Type | Description |
|---|---|---|
| $line | string | |
| $stream | string |
BackgroundJob::withProgress()
public function withProgress(float $progress): selfReturns a copy with progress updated, clamped to `[0.0, 1.0]`.
Parameters
| Name | Type | Description |
|---|---|---|
| $progress | float |
BackgroundJob::withStatus()
public function withStatus(string $status, ?int $exitCode = null, ?string $error = null): selfReturns a copy transitioned to a new status. Forces `$progress` to `1.0` when `$status` is one of the terminal statuses (`'done'`, `'failed'`, `'canceled'`), so a finished job is never left showing partial progress.
Parameters
| Name | Type | Description |
|---|---|---|
| $status | string | |
| $exitCode | ?int | |
| $error | ?string |