README

The purpose of this laravel package is to easily make console outputs less boring, and to be able to quickly style the content and add various icons at any time. Plus a couple more helpers like time and duration outputs, including laps splitting.

Methods with typical predefined formats are included: success, info, warning, error.

Installation
Display All Options
Available Parameters
Basic Usage
Defaults and Config
Timestamps and Duration
Colors
Icons
Inline Use

Installation

composer require deerdama/console-zoo-laravel

❕ Laravel versions: There shouldn't be any issues on >= 5.0 (used and tested on a bunch of versions from 5.X, 6.X, 7.X and 8.x and everything worked normally on all of those)

Just keep in mind that on versions older than 5.5: the service providers need to be registered manually, so you'll need to add the Deerdama\ConsoleZoo\ConsoleZooServiceProvider into your config/app.php providers
And in case someone wants to try this on 4.2... the basic output methods zoo() and surprise() actually work, but forget about registering the service provider, using the preview command or using the default methods like zooSuccess()

❗ If you'll want to change some default parameters then you'll need to publish the config file:

php artisan vendor:publish --provider=Deerdama\\ConsoleZoo\\ConsoleZooServiceProvider

Display All Options

To see all the available colors and icons and to check how they'll look in your console you can run the artisan command php artisan zoo:options

❕ Keep in mind that the icons/colors might not look exactly the same as the screenshots, and some might not even work for you, this depends on the console used (plus some other circumstances) and can't be controlled by the package itself. If you want to know more about the behind the scenes reason, and about the limitations, then you can find some info for example here... or just google it

Available Parameters

All parameters are optional.

Basic Usage

Once installed you can use the package in any artisan command by including the ConsoleZoo trait, eg::

class TestZoo extends Command
{
    use \Deerdama\ConsoleZoo\ConsoleZoo;

    //etc.......
}

You can pass the message and the parameters to all output methods. The second argument$parameters has to be an array, but it's always optional, you can skip it completely if you want to. Check the Available parameters section for more details.
The main flexible output method that you can use for any message is $this->zoo($messageString, $parameters), eg:

    $this->zoo("Let's take it slow...", [
        'color' => 'light_blue_bright_2',
        'icons' => ['turtle'],
        'bold',
        'italic',
    ]);

Other general methods can be found in the Defaults section. Plus the Inline usage section contains details about how to apply multiple styles within one message and add icons anywhere
Empty Line: to add some line breaks you can use $this->br();, this will simply output one empty line, if you want a bigger gap, you can just pass the number of lines you want, eg. $this->br(4);
Surprise If you want to keep it random then you can use $this->surprise($messageString, $optionalParam)
- The icons will be always random, but they can be limited to a certain category.
- Available categories: animals, nature, emoticons, food, transport, others
- All other parameters are allowed, default parameters will be used if none are passed
- Text color will be random if none is set as default nor explicitly passed, eg:

    $this->surprise("message", [
        'category' => 'animals'
    ]);

Defaults And Config

Config: All the default styles and formats can be changed in the configuration file config\zoo.php. (The config file needs to be published!).
There are some default message types with pre-defined formats, that can be changed in the config or overwritten by passing parameters.
- $this->zooInfo($message, $optionalParam);
- $this->zooSuccess($message, $optionalParam);
- $this->zooWarning($message);
- $this->zooError($message);
One time defaults: if you want to setup a default style for the current command, then you can setup the defaults through $this->zooSetDefaults($parameters) at the beginning of your command without having to pass the same parameters with every output.
- These defaults won't affect the pre-defined methods like info, error etc.., it will affect the main $this->zoo() and the $this->surprise() methods only!! (Won't affect the icon of the latter).
- Passing a parameter later on in a specific output will overwrite the default for that specific output. Example:

    $this->zooSetDefaults([
        'color' => 'cyan',
        'icons' => 'wolf',
        'bold'
    ]);

    // And then..
    $this->zoo("Meh, I'm just default..");

Whatever parameter you explicitly pass later on will overwrite the default. To overwrite default parameters that don't have a value, you can just add a no_ in front of them. For example underline and bold can be cancelled with no_underline, no_bold.

    $this->zoo("I'm the chosen one!!", [
        'icons' => 'pig_face',
        'swap',
        'italic'
    ]);

If you don't want any icons at all in an output that has them as default then you can just pass (or set it in the config) ['icons' => false], eg:

    $this->zooError("You are kind of boring..", [
        'icons' => false
    ]);

Timestamps and Duration

A timestamp can be added in front of each output by either passing the timestamp parameter,

   $this->zooInfo("How about some sleep??", [
       'timestamp' => true
   ]);

or it can be setup as default behaviour by changing the 'timestamp' => false to true in the published config zoo.php.

In the config's time array you can also change the default timezone and the timestamp's format plus its output style. Default timezone is the tz set in your config/app.php.
To just output the current time only, there is the time() function which accepts extra parameters to overwrite the defaults, couple of examples..

    $this->time();
    $this->br();
    $this->time(['format' => 'H:i:s T', 'color' => 'blue']);
    $this->br();
    $this->time([
        'tz' => 'pst',
        'format' => 'jS \o\f F, Y H:i:s',
        'icons' => 'alarm_clock',
        'color' => 'green_bright_3'
    ]);

Duration: you can get the current/total duration with $this->duration();, but you need to start the timer first! to set the starting time call $this->start();. The duration has a default format and style that can be changed in the config or passed as parameter in $this->duration($param), eg:

    $this->duration();

    $this->duration([
        'format' => 'Total duration %s.%f seconds',
        'color' => 'pink_bright_2',
        'icons' => 'snail'
    ]);
    
    $this->duration([
        'timestamp' => true,
        'format' => '%i min and %s sec',
        'icons' => false
    ]);

Lap: You can add laps to the timer with $this->lap();, the format and style of the output have the same options as duration(), plus two extra options prepend_text or append_text where you can add the current lap number through {lap_number} (brackets included).
Defaults can be changed in the config zoo.php through the lap_duration attribute.
To add a lap without outputting its duration use $this->lap(false);. To overwrite the default styling/formatting pass the parameters as second argument.

    $this->lap();
    
    $this->lap(true, ['prepend_text' => 'Lap {lap_number} duration: ']);

To format the durations use the DateInterval formatting

Changing Colors

Text and background colors can be changed through the color and background parameters.

There are multiple predefined colors that can be displayed through the artisan command. There are all the basic colors and each of them has few lighter/darker/bright options. For example blue also has blue_light_1, blue_dark_2, blue_bright_2 etc... Most colors fo up to xxx_light_4, xxx_dark_4 and xxx_bright_3

The colors can be passed in multiple ways:

string - name of the color: ['color' => 'red', 'background' => 'blue_dark_1']
array - Use array to pass any color as rgb: ['color' => [255, 0, 0], 'background' => [0, 0, 255]]
integer - You can pass the ANSI color codes directly as int: ['color' => 1, 'background' => 4]
mix - If you want to take advantage of your IDE then you can always use the defined constants in \Deerdama\ConsoleZoo\Color directly ['color' => Color::RED, 'background' => Color::BLUE]

Check the Inline usage section for details about how to change colors only to some part of the text

Use the artisan command to see all the predefined colors...

and so on....

Using Icons

To display some icon in front of your message you can pass the icons parameter as string or array for multiple icons

    $this->zoo("We want nuts...", [
        'color' => 'teal_light_1',
        'icons' => ['squirrel', 'squirrel', 'squirrel'],
        'bold',
    ]);

As with the colors, you can use the \Deerdama\ConsoleZoo\Icon class constants directly eg: ['icons' => Icon::SQUIRREL]
Passing parameter icons_right will add the specified icons to the end of the message
To add different icons to the end of the default outputs (success, error, etc..), pass or add to the config ['icons_right' => {icon/s}].
To have icons only at the start of the default messages pass or setup in the config ['icons_right' => false]

    $this->zooInfo("Tutturuuu...", ['icons_right' => 'dog']);

    $this->zooInfo("Tutturuuu...", ['icons_right' => false]);

If you want to use an icon that is not available, you can always pass the raw utf-8 code of whatever icon you need, eg ['icons' => "\xF0\x9F\x90\xBF\xEF\xB8\x8F"] _{^{(Still a squirrel)}}. The raw utf-8 icon must be inside double quotes
Check the Inline usage section for details about adding icons anywhere inside the text

There are over 700 predefined icons, Use the artisan command to display all the available icons... (Tip: You can filter by category if you choose the option to show "icons" only)

and so on...

Inline usage

Inline Style: To modify just just part of the text you can pass inline attributes within the <zoo {PARAMETERS}></zoo> tag
- Parameters requiring a value (color/background) must have the value within quotes (doesn't matter if single or double)
- Other parameters should be unquoted and separated by a space

    $this->zoo("Main style <zoo color='magenta' italic>inline style</zoo>, main again <zoo swap bold> 2nd inline </zoo>... 
                <zoo color='pink_bright_2' underline bold>it's not rocket science..</zoo> ", [
        'icons' => ['baby_chick'],
        'color' => 'blue'
    ]);

Inline Icons: To add icons inside the text you can use the <icon>{icon}</icon> tag.
- Each tag can contain ONLY ONE icon
- The message can contain multiple icon tags

    $this->zoo("I'm actually a fluffy <icon>unicorn</icon>, really!!! <icon>face_with_sunglasses</icon>", [
        'color' => 'pink_bright_2',
        'icons' => ['horse'],
        'bold'
    ]);

deerdama / console-zoo-laravel

Maintainers

Details