Custom Command Styles With Laravel Artisan

Since Laravel's console application and commands are built on top of the Symfony console component, we can use Symfony's console style system within our Laravel commands. Styles are used to control the background and foreground colors of text that is displayed in the console window. Other options exist to further change the appearance of text (such as bold or underscore).

There are two ways to define styles. One is to define styles in-line using a special syntax enclosed in angle brackets similar to HMTL. The following example would write a line to the console window with red text. It is important to note that when defining styles in-line that the style tags need to be closed with the </> closing tag.

<?php

// ...

function handle()
{
    $this->line('<fg=red>A simple line.</>');
}

// ...

To set the foreground color when styling command text set the fg property to a valid foreground color value. The background color can also be styled by setting the bg property to a valid background color value. The following example would also set the background color to yellow. Note that each property is separated by a semicolon.

<?php

// ...

$this->line('<fg=red;bg=yellow>A simple line.</>');

// ...

It is also possible to only style certain sections of the message (line breaks have been added to improve readability of the code sample):

<?php

// ...

$this->line('<fg=black>Black <fg=red>Red <fg=green>Green <fg=yellow>Yellow
             <fg=blue>Blue <fg=magenta>Magenta <fg=cyan>Cyan
             <fg=white;bg=black>White <fg=default;bg=black>Default</>');

// ...

It should also be noted that only one </> closing tag was added to the previous code sample. This is a feature that makes it simpler to add many styles in one message without having to clutter it with numerous closing tags. The previous example might generate a line similar to the following image:

The following table lists the valid foreground and background colors:

Color	Value	Example
Black	black	fg=black;bg=black
Red	red	fg=red;bg=red
Green	green	fg=green;bg=green
Yellow	yellow	fg=yellow;bg=yellow
Blue	blue	fg=blue;bg=blue
Magenta	magenta	fg=magenta;bg=magenta
Cyan	cyan	fg=cyan;bg=cyan
White	white	fg=white;bg=white
Default	default	fg=default;bg=default

Options can also be used to change various aspects of the text as it is displayed. The following table lists each of the various options and a description of each:

Option	Value	Description
Bold	bold	Causes the formatted text to display more brightly than the surrounding text.
Underscore	underscore	Underlines the styled text.
Blink	blink	Causes the styled text to blink within the console terminal. Note: most modern terminals do not support blink.
Reverse	reverse	Swaps the foreground and background colors for the styled text.
Conceal	conceal	Sets the foreground color to transparent. This effectively makes the typed text invisible.

Styles can also be created by creating an instance of Symfony\Component\Console\Formatter\OutputFormatterStyle class. The signature for the OutputFormatterStyle constructor is:

<?php

// ...

/**
 * Initializes output formatter style.
 *
 * @param string|null $foreground The style foreground color name
 * @param string|null $background The style background color name
 * @param array       $options    The style options
 */
 public function __construct(
    $foreground = null,
    $background = null,
    array $options = array()
){}

The OutputFormatterStyle class can accept the foreground and background colors as well as an array of options. Each parameter is optional and not setting any values will cause the style to use the default values. When styles are created using the OutputFormatterStyle class they generally need to be registered with the console applications output formatter. The following example creates a new style, registers it and then uses it to produce some output.

<?php

// ...

use Symfony\Component\Console\Formatter\OutputFormatterStyle;

// ...

function handle()
{
    $style = new OutputFormatterStyle('white', 'blue', ['bold']);
    $this->output->getFormatter()->setStyle('bigBlue', $style);

    // Notice that we use the name of our new style inside the tags.
    $this->line('<bigBlue>Hello, there</bigBlue>');
}

// ...

Table Styles

The way tabular data is rendered in your commands can be customized extensively. Customizing the way table cells, dividers and headers are rendered is not as simple as passing an array of data to a method, but it is not incredibly difficult. To create customized tables you will need to work with the following classes from the Symfony console component:

• Symfony\Component\Console\Helper\Table
• Symfony\Component\Console\Helper\TableSeparator
• Symfony\Component\Console\Helper\TableCell

The Table class is the starting point to creating any table (Laravel's table method internally creates an instance of Table). When creating a new instance of the Table class we must supply an instance of Symfony\Component\Console\Output\OutputInterface to the constructor as the only argument. Luckily there is an instance of that interface stored in each commands $output property. Creating a new Table instance within a Laravel command might look like this:

<?php

// ...

use Symfony\Component\Console\Helper\Table;

// ...

function handle()
{
    // Create a new Table instance.
    $table = new Table($this->output);

    // Set the table headers.
    $table->setHeaders([
        'Site', 'Description'
    ]);

    // Set the contents of the table.
    $table->setRows([
        ['https://laravel.com',        'The official Laravel website'],
        ['https://forge.laravel.com/', 'Painless PHP Servers'],
        ['https://envoyer.io/',        'Zero Downtime PHP Deployment']
    ]);

    // Render the table to the output.
    $table->render();

}

// ...

After a command similar to the previous example has executed the user might see something similar in their console window:

+----------------------------+------------------------------+
| Site                       | Description                  |
+----------------------------+------------------------------+
| https://laravel.com        | The official Laravel website |
| https://forge.laravel.com/ | Painless PHP Servers         |
| https://envoyer.io/        | Zero Downtime PHP Deployment |
+----------------------------+------------------------------+

So far the table looks similar to the output generated by Laravel's table method. However, since we are working directly with the Table class we can use Symfony features to customize how the table is generated and rendered. The following example adds a separator between each of the table rows:

<?php

// ...

use Symfony\Component\Console\Helper\Table;
use Symfony\Component\Console\Helper\TableSeparator;

// ...

function handle()
{
    // Create a new Table instance.
    $table = new Table($this->output);

    // Set the table headers.
    $table->setHeaders([
        'Site', 'Description'
    ]);

    // Create a new TableSeparator instance.
    $separator = new TableSeparator;

    // Set the contents of the table.
    $table->setRows([
        ['https://laravel.com',        'The official Laravel website'],
        $separator,
        ['https://forge.laravel.com/', 'Painless PHP Servers'],
        $separator,
        ['https://envoyer.io/',        'Zero Downtime PHP Deployment']
    ]);

    // Render the table to the output.
    $table->render();

}

// ...

After the previous example has executed the user might see something similar to the following output (notice the new separators between the table rows):

+----------------------------+------------------------------+
| Site                       | Description                  |
+----------------------------+------------------------------+
| https://laravel.com        | The official Laravel website |
+----------------------------+------------------------------+
| https://forge.laravel.com/ | Painless PHP Servers         |
+----------------------------+------------------------------+
| https://envoyer.io/        | Zero Downtime PHP Deployment |
+----------------------------+------------------------------+

Managing TableSeparator Instances

In the previous example we created an instance of TableSeparator before adding the table data. Most examples demonstrate the table separator feature by creating a new instance of TableSeparator each time one is needed. On smaller datasets, this is not an issue, but on extremely large datasets this could cause issues in low memory environments. Each method is fine, but be aware of the intended data set size and memory considerations of the running environment.

Table cells can also be set to span multiple columns and rows, much like in HTML. To do this, table cells must be created explicitly by creating an instance of the TableCell class. The following example combines the previous example and column spanning to create a more interesting table:

<?php

// ...

use Symfony\Component\Console\Helper\Table;

// ...

function handle()
{
    // Create a new Table instance.
    $table = new Table($this->output);

    // Set the table headers.
    $table->setHeaders([
        'Site', 'Description'
    ]);

    // Create a new TableSeparator instance.
    $separator = new TableSeparator;

    // Set the contents of the table.
    $table->setRows([

        // Create a row with only one table cell.
        [new TableCell('First Party', ['colspan' => 2])],
        $separator,

        ['https://laravel.com',        'The official Laravel website'],
        ['https://forge.laravel.com/', 'Painless PHP Servers'],
        ['https://envoyer.io/',        'Zero Downtime PHP Deployment'],

        $separator,

        // Create a row with only one table cell.
        [new TableCell('Useful Resources', ['colspan' => 2])],
        $separator,

        ['https://laracasts.com/', 'The Best Laravel and PHP Screencasts'],
        ['https://laracasts.com/discuss', 'Laracasts Web Development Forum']
    ]);

    // Render the table to the output.
    $table->render();

}

// ...

After the previous command has executed the user would see a table similar to the following output:

+-------------------------------+--------------------------------------+
| Site                          | Description                          |
+-------------------------------+--------------------------------------+
| First Party                                                          |
+-------------------------------+--------------------------------------+
| https://laravel.com           | The official Laravel website         |
| https://forge.laravel.com/    | Painless PHP Servers                 |
| https://envoyer.io/           | Zero Downtime PHP Deployment         |
+-------------------------------+--------------------------------------+
| Useful Resources                                                     |
+-------------------------------+--------------------------------------+
| https://laracasts.com/        | The Best Laravel and PHP Screencasts |
| https://laracasts.com/discuss | Laracasts Web Development Forum      |
+-------------------------------+--------------------------------------+

Having table cells span multiple rows is very similar to setting cells to span multiple columns. Instead of setting the colspan option, simply set the rowspan option on the table cell. The colspan and rowspan options can be combined to have cells span multiple rows and columns to create more complicated table layouts.

Text styles can also be used when rendering tables (such as info and error) to further customize how tables are rendered. The following example will build on all of the previous examples to add a new "Status" column to our sites table. This column could be used to display the status of the website or status.

<?php

// ...

use Symfony\Component\Console\Helper\Table;

// ...

function handle()
{
    // Create a new Table instance.
    $table = new Table($this->output);

    // Set the table headers.
    $table->setHeaders([
        'Site', 'Description', 'Status'
    ]);

    // Create a new TableSeparator instance.
    $separator = new TableSeparator;

    // Set the contents of the table.
    $table->setRows([
        [new TableCell('First Party', ['colspan' => 3])],
        $separator,
        [
            'https://laravel.com',
            'The official Laravel website',
            '<info>Online</info>'
        ],
        [
            'https://forge.laravel.com/',
            'Painless PHP Servers',
            '<info>Online</info>'
        ],
        [
            'https://envoyer.io/',
            'Zero Downtime PHP Deployment',
            '<info>Online</info>'
        ],
        $separator,
        [new TableCell('Useful Resources', ['colspan' => 3])],
        $separator,
        [
            'https://laracasts.com/',
            'The Best Laravel and PHP Screencasts',
            '<info>Online</info>'
        ],
        [
            'https://laracasts.com/discuss',
            'Laracasts Web Development Forum',
            '<info>Online</info>'
        ],
        $separator,
        [new TableCell('Other', ['colspan' => 3])],
        $separator,
        [
            'example.org',
            'An example experiencing issues.',
            '<bg=yellow;fg=black>Experiencing Issues</>']
        ,
        ['example.org', 'An example offline site.', '<error>Offline</error>']
    ]);

    // Render the table to the output.
    $table->render();

}

// ...

The previous example would generate a table similar to the following figure. Notice that the values in the Status column have been styled to provide additional information to the end user.