PHP Classes
elePHPant
Icontem

File: doc/8_tools.table_tool.md

Recommend this page to a friend!
  Classes of Alexandre  >  PHP Commands  >  doc/8_tools.table_tool.md  >  Download  
File: doc/8_tools.table_tool.md
Role: Auxiliary data
Content type: text/markdown
Description: Auxiliary data
Class: PHP Commands
Run commands for CLI programs using class packages
Author: By
Last change:
Date: 3 months ago
Size: 6,764 bytes
 

 

Contents

Class file image Download

The table tool

Basics

Creating a simple table

You can use the table tool to display content organized in rows and columns. Use the table method to create a table. Then define every table row in an array. You can also insert a table with a line item.

// In the "handle" method of your command class ...
$this->table([
    ['<cs style="bold">Animal</cs>', '<cs style="bold">Classification</cs>'],
    'line',
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])->display();

table command


Width & height


You can control the column width and row height. Let's set the first column width to 30 characters and the second row height to 3 characters :

// In the "handle" method of your command class ...
$this->table([
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])
->setColumnWidth(1, 30)
->setRowHeight(2, 3)
->display();

table command size

You can also set the maximum column width and maximum row height :

// In the "handle" method of your command class ...
$this->table([
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])
->setMaxColumnWidth(1, 30)
->setMaxRowHeigh(1, 2)
->display();

Header & footer

Use the setHeader and setFooter methods to display header and footer messages :

// In the "handle" method of your command class ...
$this->table([
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])
->setHeader('header')
->setFooter('footer')
->display();

table command header and footer

Spanning cells

If you want a cell to span over multiple rows and columns, this is done by defining cell parameters :


// In the "handle" method of your command class ...
$this->table([
    ['elephant', 'mammal'],
    ['parrot', 'bird'],
    ['{colspan = 2}...']
])->display();

table colspan

// In the "handle" method of your command class ...
$this->table([
    ['{colspan = 2; rowspan = 2}...', 'item1'],
    [null, null, 'item2'],
    ['item3', 'item4', 'item5']
])->display();

table rowspan

Styling

Customizing a table

Every aspect of the table is customizable. You can either use predefined styles or change table characters individually.

Here are the available predefined styles :


// In the "handle" method of your command class ...
$this->table([
    ['<cs style="bold">Animal</cs>', '<cs style="bold">Classification</cs>'],
    'line',
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])
->setStyle('box')
->display();

table command box

// In the "handle" method of your command class ...
$this->table([
        ['<cs style="bold">Animal</cs>', '<cs style="bold">Classification</cs>'],
        'line',
        ['elephant', 'mammal'],
        ['parrot', 'bird']
    ])
    ->setStyle('minimal')
    ->display();

table command minimal


// In the "handle" method of your command class ...
$this->table([
    ['<cs style="bold">Animal</cs>', '<cs style="bold">Classification</cs>'],
    'line',
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])
->setStyle('transparent')
->display();

table command transparent

Here are the available methods to customize your table display :


// In the "handle" method of your command class ...
$this->table([
    ['<cs style="bold">Animal</cs>', '<cs style="bold">Classification</cs>'],
    'line',
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])
->setTopBorderChars('=', '*')
->setBottomBorderChars('=', '*')
->setLeftBorderChars('|', '%')
->setRightBorderChars('|', '%')
->setLineChars('.', '+')
->setCornerChars('#','#', '#', '#')
->display();

table command style

Creating a custom style


If you are using your own command application, you can also create a table style with the table manager.


// In your command application file ...
$command_manager->getTableBuilder()
    ->buildStyle('your_style')
    ->setCornerChars('#','#', '#', '#');
    

And then simply apply it to your table like this :


// In the "handle" method of your command class ...
$this->table([
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])
->setStyle('your_style')
->display();  


Styling lines

You can also create a fully customized line with the \SitPHP\Commands\Tools\Table\Line class.


use SitPHP\Commands\Tools\Table\Line;

// In the "handle" method of your command class ...
$line = new Line();
$line
    ->setTitle('and')
    ->setLineChar('=')
    ->setSeparationChar('o')
    ->setBorderChar('$');

$this->table([
    ['elephant', 'mammal'],
    $line,
    ['parrot', 'bird']
])
->display();

table line

If you are using your own command application, you can also create line styles with the table manager tool :

// ...
$command_manager->getTableBuilder()
    ->buildLineBreak('your_line')
    ->setSeparationChar('|');
    

And simply use it in your table like this :

// In the "handle" method of your command class ...
$this->table([
    ['elephant', 'mammal'],
    'your_line',
    ['parrot', 'bird']
])
->display();
    

Sticky table

You can "stick" your table to the same position with the placeHere method. You can then add or remove rows as you wish and re-display your table at the same place. Try this for example :

// In the "handle" method of your command class ...
$this->table([
    ['<cs style="bold">Animal</cs>', '<cs style="bold">Classification</cs>'],
    'line',
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])
->placeHere()
->display();

sleep(1);
$table->addRow(['crocodile', 'reptile'])->display();
sleep(1);
$table->removeRow(0)->display();

table sticky


Verbosity

A table can be displayed or not depending on the verbosity. You can also decide to add, remove or set rows or not depending on the verbosity.

In the following example, the table will only be displayed with the "--verbose", or the "--debug" options.


// In the "handle" method of your command class ...
$this->table([
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])->display(self::VERBOSITY_VERBOSE);

In the following example, the row "['crocodile','reptile']" will only be added with the "--debug" option.

// In the "handle" method of your command class ...
$this->table([
    ['elephant', 'mammal'],
    ['parrot', 'bird']
])
->addRow(['crocodile','reptile'], self::VERBOSITY_DEBUG)
->display();