Running PHP from the command line? CLImate is your new best bud.

CLImate allows you to easily output colored text, special formats, and more.

Table of Contents

• Installation
• Basic Usage
• Colors
• Backgrounds
• Style Combinations
• Tags
• Custom Colors
• Commands
• Custom Commands
• Tables
• Borders
• Progress Bar
• JSON
• Dump
• Flanking
• Breaks
• Draw
• Credits

Installation

Using composer:

{
    "require": {
        "joetannenbaum/climate": "~1.0"
    }
}

Basic Usage

The out method simply receives a string that will output on a new line:

require_once('vendor/autoload.php');

$climate = new CLImate\CLImate;

$climate->out('This prints to the terminal.');
$climate->out('This prints to the terminal.')->out('This will be on a new line');

And you can do that. But that's not very fun.

Colors

There are many pre-defined colors at your disposal:

• Black
• Red
• Green
• Yellow
• Blue
• Magenta
• Cyan
• Light Gray
• Dark Gray
• Light Red
• Light Green
• Light Yellow
• Light Blue
• Light Magenta
• Light Cyan
• White

$climate->red('Whoa now this text is red.');
$climate->blue('Blue? Wow!');
$climate->lightGreen('It\'s not easy being (light) green.');

If you prefer, you can also simply chain the color method and continue using out:

$climate->red()->out('Whoa now this text is red.');
$climate->blue()->out('Blue? Wow!');
$climate->lightGreen()->out('It\'s not easy being (light) green.');

Backgrounds

To to apply a color as a background, simply prepend the color method with background:

$climate->backgroundRed('Whoa now this text is red.');
$climate->backgroundRed()->out('Whoa now this text is red.');
$climate->backgroundBlue()->out('Blue? Wow!');
$climate->backgroundLightGreen()->out('It\'s not easy being (light) green.');

Formatting

You have several formatting options:

• Bold
• Dim
• Underline
• Blink
• Invert
• Hidden

To apply a format:

$climate->bold('Bold and beautiful.');
$climate->underline('I have a line beneath me.');

$climate->bold()->out('Bold and beautiful.');
$climate->underline()->out('I have a line beneath me.');

You can apply multiple formats by chaining them:

$climate->bold()->underline()->out('Bold (and underlined) and beautiful.');
$climate->blink()->dim('Dim. But noticeable.');

Style Combinations

You can chain any of the above to get what you want:

$climate->backgroundBlue()->green()->blink()->out('This may be a little hard to read.');

Feeling wild? Just throw them all into one method:

$climate->backgroundBlueGreenBlink('This may be a little hard to read.');
$climate->backgroundBlueGreenBlinkJson([
    'this' => 'is some colorful json output'
]);

You can apply more than one format to an output, but only one foreground and one background color. Unless you use...

Tags

You can also just apply a color/background color/format to part of an output:

$climate->blue('Please <light_red>remember</light_red> to restart the server.');
$climate->out('Remember to use your <blink><yellow>blinker</yellow></blink> when turning.');

You can use any of the color or formatting keywords (snake cased) as tags.

To use a background color tag, simply prepend the color with background_:

$climate->blue('Please <bold><background_light_red>remember</background_light_red></bold> to restart the server.');

Custom Colors

You can add your own custom colors:

$climate->style->addColor('lilac', 38);

Once you've added the color, you can use it like any of the other colors:

$climate->lilac('What a pretty color.');
$climate->backgroundLilac()->out('This background is a pretty color.');
$climate->out('Just this <lilac>word</lilac> is a pretty color.');
$climate->out('Just this <background_lilac>word</background_lilac> is a pretty color.');

Commands

Commands are simply pre-defined styles for specific output:

$climate->error('Ruh roh.');
$climate->comment('Just so you know.');
$climate->whisper('Not so important, just a heads up.');
$climate->shout('This. This is important.');
$climate->info('Nothing fancy here. Just some info.');

Custom Commands

You can add your own command, just make sure that the style is defined already.

$climate->style->addCommand('rage', 'cyan');
$climate->rage('SOMETHING IS MESSED UP.');

$climate->style->addCommand('holler', [
  'underline',
  'green',
  'bold',
]);
$climate->holler('Yo what up.');

You can also override any command;

$climate->style->addCommand('error', 'light_blue');
$climate->error('Whelp. That did not turn out so well.');

Tables

The table method can receive any of the following:

• Array of arrays
• Array of associative arrays
• Array of objects

Array of Arrays

$climate->table([
    [
      'Walter White',
      'Father',
      'Teacher',
    ],
    [
      'Skyler White',
      'Mother',
      'Accountant',
    ],
    [
      'Walter White Jr.',
      'Son',
      'Student',
    ],
]);

------------------------------------------
| Walter White     | Father | Teacher    |
------------------------------------------
| Skyler White     | Mother | Accountant |
------------------------------------------
| Walter White Jr. | Son    | Student    |
------------------------------------------

Array of (Associative Arrays | Objects)

$climate->table([
    [
  		'name'       => 'Walter White',
  		'role'       => 'Father',
  		'profession' => 'Teacher',
    ],
    [
  		'name'       => 'Skyler White',
  		'role'       => 'Mother',
  		'profession' => 'Accountant',
    ],
    [
  		'name'       => 'Walter White Jr.',
  		'role'       => 'Son',
  		'profession' => 'Student',
    ],
]);

------------------------------------------
| name             | role   | profession |
==========================================
| Walter White     | Father | Teacher    |
------------------------------------------
| Skyler White     | Mother | Accountant |
------------------------------------------
| Walter White Jr. | Son    | Student    |
------------------------------------------

As with other methods, you can style a table as well. So all of the following works:

$climate->redTable([
    [
      'name'       => 'Walter White',
      'role'       => 'Father',
      'profession' => 'Teacher',
    ],
    [
      'name'       => 'Skyler White',
      'role'       => 'Mother',
      'profession' => 'Accountant',
    ],
]);

$climate->red()->table([
    [
      'name'       => 'Walter White',
      'role'       => 'Father',
      'profession' => 'Teacher',
    ],
    [
      'name'       => 'Skyler White',
      'role'       => 'Mother',
      'profession' => 'Accountant',
    ],
]);

$climate->table([
    [
      'name'       => 'Walter White',
      'role'       => '<light_blue>Father</light_blue>',
      'profession' => 'Teacher',
    ],
    [
      'name'       => 'Skyler White',
      'role'       => 'Mother',
      'profession' => '<red>Accountant</red>',
    ],
]);

Borders

If you want to insert a border to break up output, simply use the border method. By default, border outputs a dashed border with 100 characters in it

$climate->border();
// ----------------------------------------------------------------------------------------------------

The border method takes two arguments:

• Character(s) to be repeated
• Length of the border

$climate->border('*');
// ****************************************************************************************************

$climate->border('-*-');
// -*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--

$climate->border('-*-', 50);
// -*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*--*

As with the other methods, feel free to style the border:

$climate->red()->border();

$climate->redBorder();

$climate->bold()->backgroundBlue()->border();

Progress Bar

Easily add a progress bar to your output:

$progress = $climate->progress()->total(100);

for ( $i = 0; $i <= 100; $i++ )
{
  $progress->current( $i );
  usleep(80000);
}

Which will result in:

If you'd like a more exact indicator of where you are in the process, pass a label into the current method:

$languages = [
    'php',
    'javascript',
    'python',
    'ruby',
    'java',
];

$progress = $climate->progress()->total(count($languages));

foreach ($languages as $key => $language)
{
  $progress->current( $key + 1, $language );
  usleep(80000);
}

You can also shorthand it a bit if you'd like and pass the total right into the progress method:

$climate->progress(100);

As with everything else, style it however you like:

$climate->redProgress(100);
$climate->redBoldProgress(100);

JSON

The json method outputs some pretty-printed JSON to the terminal:

$climate->json([
  'name' => 'Gary',
  'age'  => 52,
  'job'  => 'Engineer',
]);

{
    "name": "Gary",
    "age": 52,
    "job": "Engineer"
}

As with the other method, you can style this output as well:

$climate->redJson([
  'name' => 'Gary',
  'age'  => 52,
  'job'  => 'Engineer',
]);

$climate->red()->json([
  'name' => 'Gary',
  'age'  => 52,
  'job'  => '<blink>Engineer</blink>',
]);

$climate->underline()->json([
  'name' => 'Gary',
  'age'  => 52,
  'job'  => 'Engineer',
]);

Dump

The dump method allows you to var_dump variables out to the terminal:

$climate->dump([
  'This',
  'That',
  'Other Thing',
]);

Which results in:

array(3) {
  [0]=>
  string(4) "This"
  [1]=>
  string(4) "That"
  [2]=>
  string(11) "Other Thing"
}

But why not make it look cool:

$climate->errorDump([
  'This',
  'That',
  'Other Thing',
]);

$climate->blinkDump([
  'This',
  'That',
  'Other Thing',
]);

Flanking

The flank method allows you to bring a little more attention to a line:

$climate->flank('Look at me. Now.');
/// ### Look at me. Now. ###

You can specify the flanking characters:

$climate->flank('Look at me. Now.', '!');
/// !!! Look at me. Now. !!!

And how many flanking characters there should be:

$climate->flank('Look at me. Now.', '!', 5);
/// !!!!! Look at me. Now. !!!!!

As with the other method, you can style this output as well:

$climate->blink()->flank('Look at me. Now.');
$climate->blinkFlank('Look at me. Now.');

Breaks

The br method does exactly that, inserts a line break:

$climate->br();

For ease of use, the br method is chainable:

$climate->br()->out('I have moved down a line.');

Draw

This would all feel a bit incomplete without ASCII art, obviously. So here we go.

There are a few pre-defined choices:

• passed
• failed
• bender
• fancy-bender
• 404

To draw one of them:

$climate->draw('bender');

would result in:

     ( )
      H
      H
     _H_
  .-'-.-'-.
 /         \
|           |
|   .-------'._
|  / /  '.' '. \
|  \ \ @   @ / /
|   '---------'
|    _______|
|  .'-+-+-+|
|  '.-+-+-+|
|    """""" |
'-.__   __.-'
     """

And of course, as with all of the methods, you may style it however you want:

$climate->blue()->draw('bender');
$climate->backgroundRedDraw('bender');
$climate->blinkDraw('bender');

But not everyone's art taste is the same. So you can add your own art by just telling CLImate the directory in which it is located.

For example, let's say you this was your art collection:

/home
  /important
    /art
      dog.txt
      cat.txt
      rabbit.txt
      mug.txt

Just let CLImate know where it is via the full path:

$climate->addArt('/home/important/art');

and now you can use anything in that directory:

$climate->draw('dog');
$climate->red()->draw('cat');
$climate->boldDraw('mug');

You can keep using the addArt method to add as many directories as you'd like.

Bonus: If you've got some time on your hands, you can style your art using the style tags, as in the case of 'fancy-bender':

<blue>     ( )</blue>
<blue>      H</blue>
<blue>      H</blue>
<blue>     _H_</blue>
<blue>  .-'-.-'-.</blue>
<blue> /         \</blue>
<blue>|           |</blue>
<blue>|   .-------'._</blue>
<blue>|  /<white>/  '.' '.</white> \</blue>
<blue>|  \<white>\ <black><blink>@   @</blink></black> /</white> /</blue>
<blue>|   '---------'</blue>
<blue>|    _______|</blue>
<blue>|  .'<black>-+-+-+</black>|</blue>
<blue>|  '.<black>-+-+-+</black>|</blue>
<blue>|    """""" |</blue>
<blue>'-.__   __.-'</blue>
<blue>     """</blue>

resulting in:

Credits

Much love to Damian Makki for the logo.