README

A Rich-class console toolkit for Laravel. One package, two namespaces:

• Console\Tools — terminal output: a fluent formatter, spinners, flavoured progress bars, boxes, trees, tables, banners, gauges, sparklines, charts (bar/column/line/scatter/heatmap/histogram/stacked), a typography + Markdown layer, a multi-task progress widget, plus an enhanced Artisan command base.
• Console\Prompter — terminal input: a fluent wrapper over laravel/prompts with a form builder and 26 validators.

Targets PHP ^8.4.1 (8.4.1–8.5) on Laravel ^13 (Symfony 8).

Install

composer require laranail/console

The service provider, the Console and Prompter facades, and the global prompter() helper are auto-discovered. Publish the config and language files if you want to customise them:

php artisan vendor:publish --tag=console-config
php artisan vendor:publish --tag=console-lang

Quick start

use Simtabi\Laranail\Console\Facades\Console;

// Inside an Artisan command you have $this->output; elsewhere use any
// Symfony OutputInterface (e.g. new ConsoleOutput()).

// Output — markup-bearing helpers go through the output:
$output->writeln(Console::status()->success('Build complete'));

// Plain renderers return finished strings and echo fine:
echo Console::box(['Name: app', 'Env:  prod'])->title('Config')->render();
echo Console::tree('project')->child('src', fn ($t) => $t->child('Console'))->render();
echo Console::gauge(72, 100)->label('Disk')->showValue()->render();

Console::spinner('Compiling…')->run(fn () => compile());

$bar = Console::progress($output, max: count($items))->format('detailed')->glyphs('blocks');
$bar->start();
foreach ($items as $item) { process($item); $bar->advance(); }
$bar->finish();

// Multi-task progress (exits non-zero if any task fails)
$tasks = Console::tasks($output);
$tasks->task('Compile', 100)->advance(100)->succeed();
exit($tasks->finish());

// Input
$name = Console::prompter()->text('Your name', required: true)->getResult();

Console::ui() returns the underlying fluent ConsoleUIFormatter; Console::prompter() returns a fresh Prompter per call. The two sub-domains are fully decoupled — they only meet in the Console aggregator. See the runnable examples for end-to-end demos.

Writing through an output

The package has three output styles — know which you're holding:

Security & portability

• All rendered text is stripped of terminal control characters (no ANSI/\r output spoofing); terminal hyperlinks are limited to an allow-list of URL schemes.
• Validators are total — non-string input returns an error rather than throwing.
• Unicode glyphs and colour degrade gracefully: capabilities are detected from the terminal and honour NO_COLOR, FORCE_COLOR, TERM and locale; ASCII fallbacks are used when Unicode is unavailable.
• Signal handling is guarded by ext-pcntl, so commands run on Windows too.

Documentation

Online docs: https://opensource.simtabi.com/console/docs/ · Changelog: CHANGELOG.md.

Requires PHP ^8.4.1 (Laravel ^13, Symfony 8). The core installs from stable releases — no minimum-stability change needed. The full-screen symfony/tui integration is optional: composer require symfony/tui (experimental, needs "minimum-stability": "dev") only if you want it.

Stability

laranail/console is 2.x stable and follows SemVer. The public API — the Console/Prompter facades and the documented Tools\*/Prompter\* classes — is stable; breaking changes only land in a major. Classes marked @internal, and the experimental full-screen TUI (Console::tui() / symfony/tui), are not covered by the BC guarantee. See Versioning & stability.

Local development

composer install
composer test                 # vendor/bin/pest --no-coverage (composer test-coverage for coverage)
composer lint                 # pint + phpstan + rector --dry-run
composer audit                # composer audit (security advisories)

Sister packages

• laranail/database-tools — standalone Laravel database utilities (traits, casts, schema macros, backup).
• laranail/package-tools — runtime base library for building Laravel packages.
• laranail/package-scaffolder — generator that scaffolds new packages.
• laranail/laranail — Simtabi's Laravel utility toolbox.

Roadmap & community

• ROADMAP.md — direction at a glance (community-driven, no dates).
• Discussions — ideas, questions, proposals.
• Issues — bug reports.

Contributing & security

• CONTRIBUTING.md — development guidelines and PR expectations.
• SECURITY.md — how to report a vulnerability (opensource@simtabi.com).
• CODE_OF_CONDUCT.md — community expectations.

License

MIT © Simtabi LLC. See LICENSE.