README

CLI kernel integration for DecodeLabs Genesis

Clip provides a framework for building comprehensive CLI based applications on top of Genesis.

Installation

Install via Composer:

composer require decodelabs/clip

Usage

Clip is a middleware library that provides an out-of-the-box setup for implementing a Genesis based CLI task runner. This means you don't really interact with it much directly, except when setting up the core of your task running infrastructure.

Create your Hub

Define your Genesis Hub by extending Clip's abstract implementation:

namespace MyThing;

use DecodeLabs\Archetype;
use DecodeLabs\Clip\Controller as ControllerInterface;
use DecodeLabs\Clip\Hub as ClipHub;
use DecodeLabs\Commandment\Action as ActionInterface;
use DecodeLabs\Monarch;
use DecodeLabs\Pandora\Container;
use DecodeLabs\Veneer;
use MyThing;
use MyThing\Controller as MyThingController;
use MyThing\Action;

class Hub extends ClipHub
{
    public function initializePlatform(): void
    {
        parent::initializePlatform();

        // Load tasks from local namespace
        Archetype::map(ActionInterface::class, Action::class);

        // Create and load your controller (or use Generic)
        if(Monarch::$container instanceof Container) {
            $controller = new MyThingController();

            Monarch::$container->bindShared(ControllerInterface::class, $controller);
            Monarch::$container->bindShared(MyThingController::class, $controller);
        }
    }
}

With this hub in place, you can run tasks defined in your nominated namespace from the terminal via a bin defined in composer:

namespace MyThing;

use DecodeLabs\Genesis\Bootstrap\Bin as BinBootstrap;
use MyThing\Hub;

require_once $_composer_autoload_path ?? __DIR__ . '/../vendor/autoload.php';
new BinBootstrap(Hub::class)->run();

{
    "bin": [
        "bin/thing"
    ]
}

Define your task:

namespace MyThing\Action;

use DecodeLabs\Commandment\Action;
use DecodeLabs\Commandment\Request;

class MyAction implements Action
{
    public function execute(
        Request $request
    ): bool {
        // Do the thing
        return true;
    }
}

composer exec thing my-action

# or with effigy
effigy thing my-action

IO

When writing back to the terminal, you can use Terminus via it's Veneer frontage directly:

use DecodeLabs\Terminus as Cli;

Cli::writeLine('Hello world');

However, this will tightly couple your Action to the STD output stream. To make your Actions as portable as possible, you should import the Terminus Session in your Action constructor using Commandment's dependency injection:

namespace MyThing\Action;

use DecodeLabs\Commandment\Action;
use DecodeLabs\Commandment\Request;
use DecodeLabs\Terminus\Session;

class MyAction implements Action
{
    public function __construct(
        private Session $io
    ) {
    }

    public function execute(
        Request $request
    ): bool {
        $this->io->writeLine('Hello world');

        return true;
    }
}

Then, any calling code can provide an alternative Session instance to the Dispatcher to allow your Action to run in a different context.

Licensing

Clip is licensed under the MIT License. See LICENSE for the full license text.