Input and output

Every command can read and write from and to the terminal by injecting the Console interface. You don't have to configure anything, Tempests takes care of injecting the right dependencies for you behind the scenes:

// app/Package.php

use Tempest\Console\Console;
use Tempest\Console\ConsoleCommand;

final readonly class Package
{
    public function __construct(
        private Console $console,
    ) {}
    
    #[ConsoleCommand]
    public function all(): void {}
}

The Console interface has a bunch of methods you can use:

• readln(): string — read one line
• read(int $bytes): string — read a specific amount of bytes
• write(string $contents): Console — write some text to the terminal
• writeln(string $line = ''): Console — write a line to the terminal
• ask(string $question, ?array $options = null, bool $multiple = false, array $validation = []): string — interactively ask a question
• confirm(string $question, bool $default = false): bool — confirm with yes or no
• password(string $label = 'Password', bool $confirm = false): string — retrieve a password, only works on terminals that support interactive components
• progressBar(iterable $data, Closure $handler): array — show a progress bar while doing some work
• info(string $line): Console — write an info styled line to the terminal
• error(string $line): Console — write an error styled line to the terminal
• success(string $line): Console — write a success styled line to the terminal
• when(mixed $expression, callable $callback): Console — only perform an action when a condition is met. The console is passed to the callable.
• component(ConsoleComponent $component, array $validation = []): mixed — render a console component.

HasConsole#

Instead of manually injecting the Console in your console command classes, you can also use the HasConsole trait. This trait will inject Console for you, and also provides shorthand methods on the class itself, instead of having to call $this->console manually:

// app/Package.php

use Tempest\Console\HasConsole;
use Tempest\Console\ConsoleCommand;

final readonly class Package
{
    use HasConsole;
    
    #[ConsoleCommand]
    public function all(): void 
    {
        $answer = $this->ask('Please give your name');
        
        $this->writeln('Hello');
    }
}

Output styling#

This packages uses tempest/highlight to style console output. You can use HTML-like tags to style the output like so:

$this->console->writeln("<success>{$line}</success>");

The following tags are available:

• <em>Emphasize</em> results in Emphasize
• <strong>Strong</strong> results in Strong
• <u>Underline</u> results in Underline
• <h1>Header 1</h1> results in Header 1
• <h2>Header 2</h2> results in Header 2
• <question>Question</question> results in Question
• <error>Error</error> results in Error
• <success>Success</success> results in Success
• <comment>Comment</comment> results in /* Comment */
• <style="bg-red fg-blue underline">Styled</style> results in Styled

Exit codes#

Console commands may return an exit code if they wish to, but that's optional. By default, Tempest will infer the correct exit code for you.

// app/Package.php

use Tempest\Console\ConsoleCommand;
use Tempest\Console\ExitCode

final readonly class Package
{
    #[ConsoleCommand]
    public function all(): void 
    {
        if (! $this->hasBeenSetup()) {
            // Tempest will infer 1 as the exit code, indicating an error occurred
            throw new HasNotBeenSetupException(); 
        }
        
        // …
     
        // Nothing is returned, meaning the command executed successfully   
    }
}

If you want more control over which exit code is returned, you can return any integer between 0 and 255, the meaning of a specific exit code will depend on your application.

#[ConsoleCommand]
public function all(): int 
{
    if (! $this->hasBeenSetup()) {
        return 12; // custom exit code
    }
    
    // …
    
    return 0; // always means success
}

For your convenience, Tempest comes with an ExitCode enum that has a handful of predefined exit codes, which are generally accepted to be "standard exit codes".

#[ConsoleCommand]
public function all(): ExitCode 
{
    if (! $this->hasBeenSetup()) {
        return ExitCode::ERROR;
    }
    
    // …
    
    return ExitCode::SUCCESS;
}