Download the PHP package henzeb/laravel-console-facade without Composer

Console Output

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.

Installation

Just install with the following command.

Usage

Under the hood it uses the InteractsWithIO trait, so everything you can do with the output inside a command, you can use through the facade.

console helper

Instead of using the Console facade, you can also use the console helper method.

``

Note: Throughout the documentation the facade is used, but everything can be accessed with the helper method as well.

Laravel's components factory

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.

Section management

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.

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:

``

delayed rendering

Delayed 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.

replace

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

watch is a method that mimics the watch command in Linux. By default, it will execute the given callback every 2 seconds.

You can specify the refresh rate to speed up or slow down the loop.

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.

tail

tail can be used to 'scroll' through added lines. Just like the linux command, tail shows you the last n lines.

``

Inside 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

Exit allows you to call exit anywhere in your code while making it easy to test.

exit hooks

You can also add hooks that will execute when you call exit. Be aware that it does not register them as shutdown functions.

trap

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.

Retrapping

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.

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.

untrap

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.

Merging options and arguments

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.

When an option or argument is set through command line, that value will take precedence.

optionGiven and argumentGiven

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

Validation

Whether 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:

Inside the configure method you simply define the following:

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.

Messages

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:

``

attribute names

Laravel allows you to rename attributes.

``

value names

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.

``

before validation callback

When you need access to the Validator instance before execution, you can use the beforeValidation method.

``

Closure based commands

When running ClosureCommands defined with Artisan::command() it does not validate automatically. Instead, you can do the following:

``

Verbosity

Console gives you an easy-to-use interface for handling verbosity insid your application.

``

These methods are using the following styles for coloring, which you can override if you wish.

Advanced Verbosity

Next to simple lines, Console also allows you to use any available output methods.

``

Note: 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.

Verbosity and sections

The verbosity interface is also supported with sections.

``

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

Silence is a handy way to hide elements like progressbars based on a boolean.

``

You can even chain silence so output will only be shown when a combination of parameters is given:

``

unsilence

Unsilence is the direct opposite of silence.

``

Note: Whatever you can do with silence, you can do with unsilence. You can even mix them up in chaining commands.

Macros

The Console facade and Henzeb\Console\Output\ConsoleSectionOutput are Macroable using Laravel's Macroable trait.

See documentation

Conditions

You can use when and unless just like you are used to on the facade as well as inside sections. See documentation

Testing

Next to the usual Facade test options, I have added some convenient methods for use inside your tests.

Testing this package

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Henze Berkheij

License

The GNU AGPLv. Please see License File for more information.