Console
Reference for the Console module: buffer and write text to the terminal with foreground and background colour, indentation, titles and blank lines, plus helpers that print an array of objects as TSV or a value as pretty JSON.
This page is a pure reference. For how the framework fits together, see the Guide.
ConsoleColour- set the text and background colour for a block of output.ConsoleOutput- buffer and write raw pieces of coloured output.ConsoleOutputItem- immutable piece of output text with its colours.ConsoleText- write lines, titles, gaps, indentation, TSV and JSON.
ConsoleColour
Set the text or background colour for the output produced by a callback, restoring the previous colour afterwards. The current colours are held in the static properties below.
Properties
| Name | Type | Description |
|---|---|---|
ConsoleColour::$textColour | ColourTransparentData|null | The current text colour, or null when none is set. |
ConsoleColour::$backgroundColour | ColourTransparentData|null | The current background colour, or null when none is set. |
Background
ConsoleColour::Background(ColourTransparentData $colour, callable $contentCallback): mixed
Set the background colour while the callback runs, restoring the previous background colour afterwards.
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The background colour to use. |
$contentCallback | callable | The callback that produces the output. |
Returns mixed The value returned by the callback.
Inverse
ConsoleColour::Inverse(callable $contentCallback): mixed
Swap the current text and background colours for the callback, defaulting to black and white when none are set.
| Name | Type | Description |
|---|---|---|
$contentCallback | callable | The callback that produces the output. |
Returns mixed The value returned by the callback.
Text
ConsoleColour::Text(ColourTransparentData $colour, callable $contentCallback): mixed
Set the text colour while the callback runs, restoring the previous text colour afterwards.
| Name | Type | Description |
|---|---|---|
$colour | ColourTransparentData | The text colour to use. |
$contentCallback | callable | The callback that produces the output. |
Returns mixed The value returned by the callback.
ConsoleOutput
Write raw pieces of text to the terminal, wrapped in ANSI colour codes from the current ConsoleColour, or gather them into a buffer instead of printing them.
Properties
| Name | Type | Description |
|---|---|---|
ConsoleOutput::$buffer | array | The output buffer. |
Gather
ConsoleOutput::Gather(callable $callback): array
Run the callback with output buffered rather than printed, and return the gathered pieces.
| Name | Type | Description |
|---|---|---|
$callback | callable | The callback whose output is gathered. |
Returns array The gathered output items.
Indented
ConsoleOutput::Indented(callable $content): void
Gather the callback's output, split it into lines, and reprint each line prefixed with four spaces.
| Name | Type | Description |
|---|---|---|
$content | callable | The callback whose output is indented. |
Returns void
Line
ConsoleOutput::Line(callable $callback): void
Gather the callback's output, print each piece with its colours, then print a newline.
| Name | Type | Description |
|---|---|---|
$callback | callable | The callback whose output makes up the line. |
Returns void
Raw
ConsoleOutput::Raw(string $text): void
Add a piece of text, wrapped in the current colours, to the active buffer, or print it straight to the terminal when there is no buffer.
| Name | Type | Description |
|---|---|---|
$text | string | The text to output. |
Returns void
ConsoleOutputItem
An immutable piece of output: the text, and the text and background colours it was written with.
Properties
| Name | Type | Description |
|---|---|---|
$text | string | The output text. |
$textColour | ColourTransparentData|null | The text colour, or null. |
$backgroundColour | ColourTransparentData|null | The background colour, or null. |
__construct
new ConsoleOutputItem(string $text = '', ColourTransparentData|null $textColour = null, ColourTransparentData|null $backgroundColour = null)
Create an output item with its text and colours.
| Name | Type | Description |
|---|---|---|
$text | string | The output text. |
$textColour | ColourTransparentData|null | The text colour, or null. |
$backgroundColour | ColourTransparentData|null | The background colour, or null. |
ConsoleText
Write whole lines of text through ConsoleOutput, with the current indent applied, plus titles, blank lines, nested indentation, and structured output as TSV or JSON.
Gap
ConsoleText::Gap(): void
Write a blank line.
Returns void
Indent
ConsoleText::Indent(): void
Write the current indent string, with no following text or newline.
Returns void
Indented
ConsoleText::Indented(callable $content): void
Run the callback with the indent increased by four spaces, restoring the previous indent afterwards.
| Name | Type | Description |
|---|---|---|
$content | callable | The callback to run at the deeper indent. |
Returns void
Json
ConsoleText::Json(mixed $data): void
Write a value as a pretty-printed JSON line.
| Name | Type | Description |
|---|---|---|
$data | mixed | The value to encode as JSON. |
Returns void
Line
ConsoleText::Line(string $text): void
Write the current indent, then the text, then a newline.
| Name | Type | Description |
|---|---|---|
$text | string | The line of text to write. |
Returns void
NewLine
ConsoleText::NewLine(): void
Write a newline character.
Returns void
Raw
ConsoleText::Raw(string $text): void
Write text with no indent and no trailing newline.
| Name | Type | Description |
|---|---|---|
$text | string | The text to write. |
Returns void
Title
ConsoleText::Title(string $text): void
Write the text as a centred title on a dashed 80-column line, in inverse colours.
| Name | Type | Description |
|---|---|---|
$text | string | The title text. |
Returns void
Tsv
ConsoleText::Tsv(array $objects, bool $includeHeader = true): void
Write an array of objects as tab-separated values. The fields are the union of every object's fields, in the order they first appear, with tabs, newlines and returns in values escaped.
| Name | Type | Description |
|---|---|---|
$objects | array | The objects to write, one per row. |
$includeHeader | bool | Whether to write a header row of field names. |
Returns void