Repository navigation
Console
Blink ships a console entry at core/blink. It boots the same setup.php a web request does, minus the request handling, then dispatches to a command.
php core/blink list
php core/blink help ticker:run
php core/blink terra:apply --force
php core/blink --root=/var/www/site ticker:run
Hosts that only run .php files can use core/cli.php in its place.
The site a command belongs to is found from, in order: --root=, the BLINK_ROOT environment variable, the working directory when it holds config.define.php, and finally the directory above blink.
namespace App\Console;
use App\Model\Order;
use Blink\Console;
use Blink\Console\Command;
class ImportOrders extends Command {
public static string $usage = "orders:import {file : Path to the CSV} {--dry-run : Parse without writing} {--c|chunk=500 : Rows per insert}";
public static string $description = "Import orders from a CSV export";
public function run(Importer $importer) {
$path = $this -> argument("file");
$chunk = (int) $this -> option("chunk");
if (!file_exists($path)) {
$this -> error("No such file: {$path}");
return Console::EXIT_FAILURE;
}
if (!$this -> option("dry-run") && !$this -> confirm("Import into " . Order::$table . "?", true))
return Console::EXIT_OK;
$count = $importer -> import($path, $chunk, dryRun: (bool) $this -> option("dry-run"));
$this -> success("Imported {$count} order(s).");
return Console::EXIT_OK;
}
}A module lists it in commands(), and it is available at once.
$usage names the command and everything it takes in one line:
| Token | Meaning |
|---|---|
{name} |
A required argument |
{name?} |
An optional argument |
{name=default} |
An argument with a default |
{name*} |
The last argument swallows everything remaining |
{--flag} |
A boolean option |
{--opt=} |
An option that takes a value, no default |
{--opt=10} |
An option with a default |
{--o|opt} |
An option with a short form |
{... : text} |
A description shown by help
|
$usage and $description are static so list and help never instantiate a command whose constructor touches the database.
run() is called through Essence, so it can type-hint services. Its return value is the exit code; nothing means 0.
| Helper | Does |
|---|---|
argument($name), option($name)
|
Read the parsed input; without a name, everything |
line(), info(), success(), warning(), comment()
|
Write to stdout, colored when it is a terminal |
error() |
Write to stderr, so real output stays pipeable |
heading($text) |
A title with a rule under it |
table($headers, $rows) |
An aligned table |
confirm($question, $default) |
A yes/no prompt; returns the default when stdin is not a terminal |
| Constant | Value | Meaning |
|---|---|---|
Console::EXIT_OK |
0 | Done |
Console::EXIT_FAILURE |
1 | The command failed |
Console::EXIT_USAGE |
2 | Bad arguments, or no such command |
Console::EXIT_MEMORY |
12 | Stopped at the memory ceiling |
Console::EXIT_INTERRUPTED |
130 | Stopped by a signal |
Console::EXIT_FATAL |
255 | PHP died |
An unknown command exits 2 and suggests near matches. A command that throws exits 1: the exception is stored as an error report, the same one a failed web request would get, and its summary, stack trace and report id are printed to stderr. error:list finds it later.
Console::call("terra:apply", array( "--force" ));Returns the exit code and writes to the console's output, or to an Output you pass as the third argument.
| Group | Commands |
|---|---|
list, help, about, cache:clear, route:list
|
|
| errors |
error:list, error:purge
|
| locks |
lock:list, lock:release
|
| terra |
terra:apply, terra:status, terra:revert, terra:reset, terra:rebuild, terra:make
|
| ticker |
ticker:run, ticker:tick, ticker:orbits, ticker:status, ticker:failed, ticker:retry, ticker:forget, ticker:clear, ticker:restart
|
| lightrail |
lightrail:listeners, lightrail:dispatch, lightrail:retry, lightrail:flush, lightrail:purge
|
| trace |
trace:list, trace:purge
|
help <command> prints any command's arguments and options.
Under the console, setup.php skips path parsing, output buffering, session start and routing; it sets set_time_limit(0) and ignore_user_abort(true), raises the memory limit to CONFIG::$CLI_MEMORY_LIMIT when the current one is lower, and swaps the HTML error page for a text renderer on stderr. Terra's auto-apply does not run under the console: the operator can run terra:apply and read what it says.