Building minicli: Implementing Command Controllers
Tags: showdev, php, cli, beginners
Published: 2019-09-25 11:34:34

---
title: Building minicli: Implementing Command Controllers
published: true
description: 
series: building-minicli
tags: showdev, php, cli, beginners
cover_image: https://thepracticaldev.s3.amazonaws.com/i/3yaxsqa2kp14r5u2puhc.jpg
---

## Introduction

The [MVC](https://en.wikipedia.org/wiki/Model–view–controller) (Model, View, Controller) pattern is very popular in web applications. Controllers are responsible for handling code execution, based on which endpoint is requested from the web application. CLI applications don't have endpoints, but we can implement a similar workflow by routing command execution through *Command Controllers*. 

In the [first tutorial of this series](https://dev.to/erikaheidi/bootstrapping-a-cli-php-application-in-vanilla-php-4ee), we've bootstrapped a PHP application for the command line interface (CLI), using a single entry point and registering commands through anonymous functions. In this new tutorial, we will refactor `minicli` to use Command Controllers.

This is **Part 2** of the [Building Minicli](https://dev.to/erikaheidi/bootstrapping-a-cli-php-application-in-vanilla-php-4ee) series.


### Before Getting Started

You'll need `php-cli` and [Composer](https://getcomposer.org/) to follow this tutorial.

If you haven't followed the [first part of this series](https://dev.to/erikaheidi/bootstrapping-a-cli-php-application-in-vanilla-php-4ee), you can download version `0.1.0` of [erikaheidi/minicli](https://github.com/erikaheidi/minicli) to bootstrap your setup:

```
wget https://github.com/erikaheidi/minicli/archive/0.1.0.zip
unzip 0.1.0.zip
cd minicli
```

Then, run Composer to set up autoload. This won't install any package, because `minicli` has no dependencies.

```
composer dump-autoload
```

Run the application with:

```
php minicli
```

or

```
chmod +x minicli
./minicli
```

## 1. Outsourcing Command Registration to a `CommandRegistry` Class

To get started with our refactoring, we'll create a new class to handle the work of registering and locating commands for the application. This work is currently handled by the `App` class, but we'll outsource it to a class named `CommandRegistry`.

Create the new class using your editor of choice. For simplicity, in this tutorial we'll be using `nano`:

```
nano lib/CommandRegistry.php
```

Copy the following content to your `CommandRegistry` class:

```
<?php

namespace Minicli;

class CommandRegistry
{
    protected $registry = [];

    public function registerCommand($name, $callable)
    {
        $this->registry[$name] = $callable;
    }

    public function getCommand($command)
    {
        return isset($this->registry[$command]) ? $this->registry[$command] : null;
    }
}
```
_Note: the `getCommand` method uses a ternary operator as a shorthand if/else. It returns `null` in case a command is not found._

Save and close the file when you're done.

Now, edit the file `App.php` and replace the current content with the following code, which incorporates the `CommandRegistry` class for registering commands:


```
<?php

namespace Minicli;

class App
{
    protected $printer;

    protected $command_registry;

    public function __construct()
    {
        $this->printer = new CliPrinter();
        $this->command_registry = new CommandRegistry();
    }

    public function getPrinter()
    {
        return $this->printer;
    }

    public function registerCommand($name, $callable)
    {
        $this->command_registry->register($name, $callable);
    }

    public function runCommand(array $argv = [])
    {
        $command_name = "help";

        if (isset($argv[1])) {
            $command_name = $argv[1];
        }

        $command = $this->command_registry->getCommand($command_name);
        if ($command === null) {
            $this->getPrinter()->display("ERROR: Command \"$command_name\" not found.");
            exit;
        }

        call_user_func($command, $argv);
    }
}
```

If you run the application now with `./minicli`, there should be no changes, and you should still be able to run both the `hello` and `help` commands.


## 2. Implementing Command Controllers

Now we'll go further with the refactoring of commands, moving specific command procedures to dedicated `CommandController` classes.

### 2.1 Creating a `CommandController` Model

The first thing we need to do is to set up an abstract model that can be inherited by several commands. This will allow us to have a few default implementations while enforcing a set of features through abstract methods that need to be implemented by the children (concrete) classes.

This model should define at least one mandatory method to be called by the `App` class on a given concrete `CommandController`, when that command is invoked by a user on the command line.

Open a new file on your text editor:

```
nano lib/CommandController.php
```

Copy the following contents to this file. This is how our initial `CommandController` abstract class should look like:

```
<?php

namespace Minicli;

abstract class CommandController
{
    protected $app;

    abstract public function run($argv);

    public function __construct(App $app)
    {
        $this->app = $app;
    }
    
    protected function getApp()
    {
        return $this->app;
    }
}
```

Any class that inherits from `CommandController` will inherit the `getApp` method, but it will be required to implement a `run` method and handle the command execution.

### 2.2 Creating a Concrete Command Controller

Now we'll create our first Command Controller concrete class: `HelloController`. This class will replace the current definition of the `hello` command, from an anonymous function to a `CommandController` object.


Remember how we created two separate namespaces within our Composer file, one for the framework and one for the application? Because this code is very specific to the application being developed, we'll use the `App` namespace now. 

First, create a new folder named `Command` inside the `app` namespace directory:

```
mkdir app/Command
```

Open a new file in your text editor:

```

nano app/Command/HelloController.php
```

Copy the following contents to your controller. This is how the new `HelloController` class should look like:

```
<?php

namespace App\Command;

use Minicli\CommandController;

class HelloController extends CommandController
{
    public function run($argv)
    {
        $name = isset ($argv[2]) ? $argv[2] : "World";
        $this->getApp()->getPrinter()->display("Hello $name!!!");
    }
}
```

There's not much going on here. We reused the same code from before, but now it's placed in a separate class that inherits from `CommandController`. The `App` object is now accessible through a method `getApp`, inherited from the parent abstract class `CommandController`.


### 2.3 Updating `CommandRegistry` to Use Controllers

We have defined a simple architecture for our Command Controllers based on inheritance, but we still need to update the `CommandRegistry` class to handle these changes.

Having the ability to separate commands into their own classes is great for maintainability, but for simple commands you might still prefer to use anonymous functions.

The following code implements the registration of Command Controllers in a way that keeps compatibility with the previous method of defining commands using anonymous functions. Open the `CommandRegistry.php` file using your editor of choice:


```
nano lib/CommandRegistry.php
```

Update the current contents of the `CommandRegistry` class with the following code:

```
<?php

namespace Minicli;

class CommandRegistry
{
    protected $registry = [];

    protected $controllers = [];

    public function registerController($command_name, CommandController $controller)
    {
        $this->controllers = [ $command_name => $controller ];
    }

    public function registerCommand($name, $callable)
    {
        $this->registry[$name] = $callable;
    }

    public function getController($command)
    {
        return isset($this->controllers[$command]) ? $this->controllers[$command] : null;
    }

    public function getCommand($command)
    {
        return isset($this->registry[$command]) ? $this->registry[$command] : null;
    }

    public function getCallable($command_name)
    {
        $controller = $this->getController($command_name);

        if ($controller instanceof CommandController) {
            return [ $controller, 'run' ];
        }

        $command = $this->getCommand($command_name);
        if ($command === null) {
            throw new \Exception("Command \"$command_name\" not found.");
        }

        return $command;
    }
}
```

Because we now have both Command Controllers and simple callback functions registered within the Application, we've implemented a method named `getCallable` that will be responsible for figuring out which code should be called when a command is invoked. This method throws an exception in case a command can't be found. The way we've implemented it, Command Controllers will always take precedence over single commands registered through anonymous functions.

Save and close the file when you're done replacing the old code.

### 2.4 Updating the `App` class
 
We still need to update the `App` class to handle all the recent changes. 

Open the file containing the `App` class:

```
nano lib/App.php
```

Replace the current contents of the `App.php` file with the following code:

```
<?php

namespace Minicli;

class App
{
    protected $printer;

    protected $command_registry;

    public function __construct()
    {
        $this->printer = new CliPrinter();
        $this->command_registry = new CommandRegistry();
    }

    public function getPrinter()
    {
        return $this->printer;
    }

    public function registerController($name, CommandController $controller)
    {
        $this->command_registry->registerController($name, $controller);
    }

    public function registerCommand($name, $callable)
    {
        $this->command_registry->registerCommand($name, $callable);
    }

    public function runCommand(array $argv = [], $default_command = 'help')
    {
        $command_name = $default_command;

        if (isset($argv[1])) {
            $command_name = $argv[1];
        }

        try {
            call_user_func($this->command_registry->getCallable($command_name), $argv);
        } catch (\Exception $e) {
            $this->getPrinter()->display("ERROR: " . $e->getMessage());
            exit;
        }
    }
}
```

First, we've implemented a method to allow users to register Command Controllers after instantiating an App object: `registerController`. This method will outsource the command registration to the `CommandRegistry` object. Then, we've update the `runCommand` method to use `getCallable`, catching a possible exception in a try / catch block.

Save and close the file when you're done editing.

### 2.5 Registering the `HelloController` Command Controller

The `minicli` script is still using the old method of defining commands through anonymous functions. We'll now update this file to use our new `HelloController` Command Controller, but we we'll keep the `help` command registration the same way it was before, registered as an anonymous function. 

Open the `minicli` script:

```
nano minicli
```

This is how the updated `minicli` script will look like now:

```
#!/usr/bin/php
<?php

if (php_sapi_name() !== 'cli') {
    exit;
}

require __DIR__ . '/vendor/autoload.php';

use Minicli\App;

$app = new App();

$app->registerController('hello', new \App\Command\HelloController($app));

$app->registerCommand('help', function (array $argv) use ($app) {
    $app->getPrinter()->display("usage: minicli hello [ your-name ]");
});

$app->runCommand($argv);

```

After updating the file with the new code, you should be able to run the application the same way as you run it before, and it should behave exactly the same:

```
./minicli
```

The difference is that now you have two ways of creating commands: by registering an anonymous function with `registerCommand`, or by creating a Controller class that inherits from `CommandController`. Using a Controller class will keep your code more organized and maintainable, but you can still use the "short way" with anonymous functions for quick  hacks and simple scripts.


## Conclusion & Next Steps

In this post, we refactored `minicli` to support commands defined in classes, with an architecture that uses **Command Controllers**. While this is working well for now, a Controller _should_ be able to handle more than one command; this would make it easier for us to implement command structures like this:

```
command [ subcommand ] [ action ] [ params ]
command [ subcommand 1 ] [ subcommand n ] [ params ]
```

In the next part of this series, we'll refactor `minicli` to support **subcommands**.

What do you think? How would you implement that?

Cheers and see you soon! \,,/

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
All files used in this tutorial can be found here: [erikaheidi/minicli:v0.1.2](https://github.com/erikaheidi/minicli/tree/0.1.2)