This package allows you to manage console output from places that are not directly inside the command classes.
As my applications require the logic not to be directly inside the command classes, I found myself adding the output to the constructors, creating real ugly not reusable code. This simplifies the process for me, and now for you.
Just install with the following command.
composer require henzeb/laravel-console-facadeUnder the hood it uses the InteractsWithIO trait, so everything you can do
with the output inside a command, you can
use through the facade.
use Henzeb\Console\Facades\Console;
class MyClass {
public function writeMessage(): void
{
Console::ask('Would you like to be able to do this?');
Console::info('This message was brought to you by Henzeb');
}
}Instead of using the Console facade, you can also use the console
helper method.
use function Henzeb\Console\Functions\console;
console('hello'); // outputs hello
console()->info('hello'); // outputs hello
console()->ask('Want an answer?'); // asks you a questionNote: Throughout the documentation the facade is used, but everything can be accessed with the helper method as well.
Laravel released a new style for their commands, and they use a special Factory for that. With this method, you can use them within your own classes.
use Henzeb\Console\Facades\Console;
class MyClass {
public function writeMessage(): void
{
Console::components()->ask('Would you like to be able to do this?');
Console::components()->info('This message was brought to you by Henzeb');
Console::components()->bulletList(['this one', 'Another one']);
}
}The facade also allows you to manage and use sections. Inside the section you
can only use the output methods from
InteractsWithIO like table, progressbar or info, so that means asking
questions cannot be done.
use Henzeb\Console\Facades\Console;
class MyClass {
public function useSection(): void
{
Console::section()->table(['header'=>'title'], [[]]);
Console::section('section2')->withProgressBar(100, fn()=>true);
Console::section('section1')->components()->bulletList(['this one', 'Another one']);
Console::section('section1')->clear();
Console::section('section3')->info('This message was brought to you by Henzeb');
}
}When you do not pass a name, a uniqid will be given each time you call section. You can retrieve the name of
this section by doing the following:
$section = Console::section();
$section->name(); //returns string similar to 64350abe27355
$section = Console::section('section1');
$section->name(); //returns section1Delayed rendering is useful when you have to rebuild things from scratch, like a table, that takes a lot of time. With this, everything is generated first before outputting it to the console.
use Henzeb\Console\Facades\Console;
use Henzeb\Console\Output\ConsoleSectionOutput;
class MyClass {
public function renderWhenReady(): void
{
Console::section()->render(
function(ConsoleSectionOutput $section){
$section->table(['header'=>'title'], [[]]);
}
);
Console::section(
'section2',
function(ConsoleSectionOutput $section){
$section->table(['header'=>'title'], [[]]);
}
);
}
}The default overwrite method of Symfony is kinda slow when it comes to
repeated rendering.
If you find your console application is flickering, replace is a
good replacement.
Note: render, watch, tail and the callback method on section are all using replace
under the hood.
watch is a method that mimics the watch command in Linux. By default, it
will execute the given callback every 2 seconds.
Console::watch(
function (ConsoleSectionOutput $output) {
$output->info(now()->toDateTimeString());
},
);You can specify the refresh rate to speed up or slow down the loop.
Console::watch(
function (ConsoleSectionOutput $output) {
$output->info(now()->toDateTimeString());
},
1
);It is also possible to specify the name for the section yourself. That way
you can manipulate the section inside for example a trap signal.
Console::watch(
function (ConsoleSectionOutput $output) {
$output->info(now()->toDateTimeString());
},
sectionName: 'yourName'
);tail can be used to 'scroll' through added lines. Just like the
linux command, tail shows you the last n lines.
Console::tail(); // returns a scrollable section with 10 lines
Console::tail(5); // returns a scrollable section with 5 lines
Console::tail(10, 'mySection'); // returns a scrollable mySection section
Console::section('mySection')->tail(10);
Console::section('mySection')->tail(10)->tail(5);//downgrades height to 5
Console::section('mySection')->setMaxHeight(10); // uses Symfony's implementation
Console::tail()->setMaxHeight(15); // upgrades height to 15Inside Symfony's ConsoleSectionOutput, there is already a way of doing this, but there are numerous issues with. This implementation fixes them, and allows you to use any output, like progress bars and tables with ease.
You can still use Symfony's implementation on regular sections.
Exit allows you to call exit anywhere in your code while making it easy to test.
Console::exit();
Console::exit(1);You can also add hooks that will execute when you call exit. Be aware that it
does not register them as shutdown functions.
Console::onExit(
function(int $exitcode) {
Console::info('exited with code '.$exitcode);
}
);
Console::onExit(
function() {
Console::info('exited with code 123');
},
123
);Just like Laravel, there is a trap method to register signals. Under the hood,
this is not using the logic created by
Laravel and Symfony for backwards compatibility reasons, but it's similar.
See #43933 for more
information.
In below scenario, all three will run when a SIGINT signal is given and the
second will also run when a SIGTERM signal
is given. The first handler returns true. This means that when all handlers are
executed, an exit is given.
Console::trap(
function () {
print('first handler');
return true;
},
SIGINT
);
Console::trap(
function () {
print('second handler');
var_dump(func_get_args());
return false;
},
SIGINT,
SIGTERM
);
Console::trap(
function () {
print('third handler');
},
SIGINT
);trap allows you to trap a new signal handler. This is useful when you want
to be able to press CTRL+C twice. In the example below the next time the
signal is received, the application will forcibly exit.
Console::trap(
function () {
print('first handler');
Console::trap(
function () {
print('second handler');
return true;
},
SIGINT
);
},
SIGINT
);Tip: When a handler was already registered the normal way or trough
Laravel's implementation, you can use pcntl_signal_get_handler to pass
this in to trap
Note: This was previously onSignal, but I have deprecated that method as
Laravel is using trap.
Just like laravel, there is an untrap method. This method is automatically
called just like the Laravel implementation, so you can use Artisan::call
within your command and not execute the wrong signal handlers.
Console::untrap();In some cases you may want to merge options or arguments, like resuming a process with specific options or arguments stored in cache, or to reconfigure a running daemon process.
Console::mergeOptions(['env'=>'production']);
Console::mergeArguments(['yourArgument'=>true]);When an option or argument is set through command line, that value will take precedence.
In Laravel's Command, it can get pretty confusing to figure out if the user
has specified an option or an argument. An option with optional parameter
returns null either when set or not set. When you set a default, you could
figure it out, but it is not really userfriendly and feels hacky instead of
clean code.
The following methods tells you if a user has added the option or argument to the commandline
// artisan your:command --check --test=false
Console::optionGiven('check'); // returns true
Console::optionGiven('test'); // returns true
Console::optionGiven('verify'); // returns false
// artisan your:command verify
Console::argumentGiven('check'); //returns false
Console::argumentGiven('verify'); //returns trueWhether you build a console application that is going to be distributed, or just want to make sure no one can derail your application, you want to use validation. Laravel Console Facade makes that very easy to do.
Suppose you want to validate the input from the following signature:
{id?} {--name=} {--age=*} {--birth=}
Inside the configure method you simply define the following:
Console::validateWith(
[
'id' => 'bail|int|exists:users',
'--name'=>'string|min:2',
'--age.*' => 'bail|int|between:0,150',
'--birth' => 'bail|prohibits:--age|date'
]
);When running your command, the validation will automatically execute.
Under the hood, this uses Laravel's validation engine, so everything that the validation engine accepts, you can use here.
Caveat: When you want to validate options against arguments or options that
may not be passed, you may need to write your own Rule or closure.
Since the translations are mainly based upon input coming from HTTP requests, you may want to give them different translations. Just add a second array like you would do with Laravel's validation engine:
Console::validateWith(
[
'id' => 'bail|int|exists:users',
'--name' => 'string|min:2',
'--age.*' => 'bail|exclude_with:--birth|int|between:0,150',
'--birth' => 'bail|prohibits:--age|date',
],
[
'exists' => 'User with given id does not exist!'
'prohibits' => 'Cannot be used together with :other'
]
);Laravel allows you to rename attributes.
Console::validateWith(
[
'id' => 'bail|int|exists:users',
'--name' => 'string|min:2'
],
attributes: [
'id' => 'user id',
'--name' => 'name'
]
);Just like attributes, you can also give certain values names.
Below we see an example where the accepted flag must be a form of true
when any gender is specified.
Console::validateWith(
[
'--gender' =>'required|in:x,f,m',
'--accepted' => 'accepted_if:--gender,x,--gender,f,--gender,m',
],
valueNames: [
'--gender' => [
'm' => 'male',
'f' => 'female',
'x' => 'other gender'
]
]
);When you need access to the Validator instance before execution, you can use the
beforeValidation method.
Console::beforeValidation(
function(Illuminate\Validation\Validator $validator){
// your logic
}
);When running ClosureCommands defined with Artisan::command() it does not
validate automatically. Instead, you can do the following:
Artisan::command(
'your:command {id?} {--name=} {--age=*} {--birth=}',
function () {
Console::validateWith(
[
//
]
);
Console::validate();
//
}
);Console gives you an easy-to-use interface for handling verbosity insid your application.
Console::verbose('verbose'); // only prints `verbose` when -v or higher is passed.
Console::veryVerbose('very verbose'); // only prints `very verbose` when -vv or higher is passed.
Console::debug('debug'); // only prints `debug` when -vvv is passed.These methods are using the following styles for coloring, which you can override if you wish.
| Style | Color |
|---|---|
| henzeb.console.verbose | cyan |
| henzeb.console.very.verbose | yellow |
| henzeb.console.debug | magenta |
Next to simple lines, Console also allows you to use any available output methods.
Console::verbose()->info('info'); // only prints `info` when -v or higher is passed.
Console::debug()->ask('debug?'); // only asks when -vvv is passed, returns null otherwise
Console::veryVerbose()->ask('very verbose?', 'no'); // only asks when -vv or higher is passed, returns 'no' otherwise
Console::verbose()->withProgressbar(2, fn() => true); // only shows the progressbar when -v or higher is passedNote: While the progressbar is not shown due to verbosity, the given callable is still executed. Also note that the watch will not run at all when the verbosity does not match.
The verbosity interface is also supported with sections.
Console::section('mySection')->debug('debug'); // only prints `debug` when -vvv is passed.
Console::section('mySection')->debug()->info('info');// only prints `info` when -vvv is passed.
Console::debug()->section('mySection')->info('info');// only prints `info` when -vvv is passed.Note: be aware that verbose sections are the same as the non-verbose section. This means you can't
just clear the verbose output inside a section as it will clear the entire section.
Silence is a handy way to hide elements like progressbars based on a boolean.
Console::silence(false)->info('test'); // prints test
Console::silence(true)->info('test'); // prints nothing
Console::silence(false)->debug('test'); // prints test when -vvv is passed.
Console::silence(true)->debug('test'); // prints nothing, even when -vvv is passed.
Console::section('section')->silence(true)->info('test'); // prints nothing
Console::section('section')->silence(false)->info('test'); // prints test
Console::silence(true)->withProgressBar(5, fn()=>true); // runs the callback, but won't show progress
Console::silence(false)->withProgressBar(5, fn()=>true); // runs the callback, and shows progressYou can even chain silence so output will only be shown when a combination of parameters is given:
Console::silence(false)->silence(false); // shows output
Console::silence(true)->silence(false); // shows no output
Console::silence(false)->silence(true); // shows no output
Console::silence(true)->silence(true); // shows no outputUnsilence is the direct opposite of silence.
Console::unsilence(true)->info('test'); // prints test
Console::unsilence(false)->info('test'); // prints nothing
Console::unsilence(true)->debug('test'); // prints test when -vvv is passed.
Console::unsilence(false)->debug('test'); // prints nothing, even when -vvv is passed.
Console::section('section')->unsilence(false)->info('test'); // prints nothing
Console::section('section')->unsilence(true)->info('test'); // prints test
Console::unsilence(false)->withProgressBar(5, fn()=>true); // runs the callback, but won't show progress
Console::unsilence(true)->withProgressBar(5, fn()=>true); // runs the callback, and shows progressNote: Whatever you can do with silence, you can do with unsilence.
You can even mix them up in chaining commands.
The Console facade and Henzeb\Console\Output\ConsoleSectionOutput are
Macroable using Laravel's Macroable trait.
Console::macro(...)
Henzeb\Console\Output\ConsoleSectionOutput::macro(...)See documentation
You can use when and unless just like you are used to on the facade as
well as inside sections.
See documentation
Next to the usual Facade test options, I have added some convenient methods for use inside your tests.
Console::shouldExit();
Console::shouldNotExit();
Console::shouldExitWith(int $seconds);
Console::shouldSleep();
Console::shouldNotSleep();
Console::shouldSleepWith(int $seconds);
Console::watchShouldLoop(int $times, int $sleep = null);composer testPlease see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email henzeberkheij@gmail.com instead of using the issue tracker.
The GNU AGPLv. Please see License File for more information.