climate/extending/index.md

---

layout: default title: Extending

permalink: /extending/

Extending

Adding your own functionality to CLImate is very simple.

$climate->extend('MyProject\Console\MyCustomTerminalObject');

// You can now use your extension within CLImate:
// $climate->myCustomTerminalObject('These pretzels are making me thirsty!');
// $climate->boldMyCustomTerminalObject('These pretzels are making me thirsty!');

$climate->extend([
    'MyProject\Console\MyCustomTerminalObject',
    'MyProject\Console\AnotherCustomTerminalObject'
]);

// $climate->myCustomTerminalObject('These pretzels are making me thirsty!');
// $climate->anotherCustomTerminalObject('Hello... Newman.');

If you want to use a custom alias instead of the class name of your extension:

$climate->extend('MyProject\Console\MyCustomTerminalObject', 'yell');

// $climate->yell('These pretzels are making me thirsty!');
// $climate->backgroundRedYell('These pretzels are making me thirsty!');

$climate->extend([
    'yell'            => 'MyProject\Console\MyCustomTerminalObject',
    'saySuspiciously' => 'MyProject\Console\AnotherCustomTerminalObject'
]);

// $climate->yell('These pretzels are making me thirsty!');
// $climate->saySuspiciously('Hello... Newman.');

You may also pass in instantiated objects instead of the FQN as a string:

$climate->extend(new MyProject\Console\MyCustomTerminalObject);
$climate->extend(new MyProject\Console\MyCustomTerminalObject, 'yell');

$climate->extend([
    new MyProject\Console\MyCustomTerminalObject,
    new MyProject\Console\AnotherCustomTerminalObject
]);

$climate->extend([
    'yell'            => new MyProject\Console\MyCustomTerminalObject,
    'saySuspiciously' => new MyProject\Console\AnotherCustomTerminalObject
]);

When creating an extension, first you have to ask yourself: Are you creating a Basic Terminal Object, or a Dynamic one?

Basic Terminal Object

A Basic Terminal Object simply prints output to the terminal based on the arguments. Tables, Columns, and Borders are examples of existing Basic Terminal Objects.

When creating a Basic Terminal Object, you must implement League\CLImate\TerminalObject\Basic\BasicTerminalObjectInterface.

Creating

The easiest way to create a Basic Terminal Object is to extend League\CLImate\TerminalObject\Basic\BasicTerminalObject. You may pass in arguments in one of two ways: through the constructor, or through an arguments method.

All you have to do is provide the result method that returns the terminal output as either a string or an array.

Let's say you wanted to write an terminal object that highlights an arbitrary word when used. It might look something like this:

namespace MyProject\Console;

use League\CLImate\TerminalObject\Basic\BasicTerminalObject;

class Highlight extends BasicTerminalObject
{
    protected $text;

    protected $search;

    public function __construct($text, $search)
    {
        $this->text   = $text;
        $this->search = $search;
    }

    public function result()
    {
        $replace = "<background-yellow>{$this->search}</background-yellow>";

        return str_replace($this->search, $replace, $this->text);
    }
}

Then simply use it:

$climate->extend('MyProject\Console\Highlight');

$climate->highlight('My whole life was ruined because of the puffy shirt.', 'puffy');

Dynamic Terminal Object

A dynamic terminal object returns the object itself. Examples of existing Dynamic terminal objects include Progress Bar, Input, and Animation.

For example:

// The progress method returns the Progress dynamic terminal object
$progress = $climate->progress(100);

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

When creating a Dynamic Terminal Object, you must implement League\CLImate\TerminalObject\Dynamic\DynamicTerminalObjectInterface.

Creating

The easiest way to create a Basic Terminal Object is to extend League\CLImate\TerminalObject\Dynamic\DynamicTerminalObject. Just like the basic object, you may pass in arguments in one of two ways: through the constructor, or through an arguments method.

To learn more about how Dynamic Terminal Objects work, you can look at the source code of the Progress Bar, Input, Padding, or Animation Terminal Objects.