CLI Application¶

Overview¶

CLI stands for Command Line Interface. CLI applications are executed from the command line or a shell prompt. One of the benefits of CLI applications is that they do not have a view layer (only potentially echoing output on screen) and can be run more than one at a time. Some of the common usages are cron job tasks, manipulation scripts, import data scripts, command utilities and more.

Structure¶

You can create a CLI application in Phalcon, using the Phalcon\Cli\Console class. This class extends from the main abstract application class, and uses a directory in which the Task scripts are located. Task scripts are classes that extend Phalcon\Cli\Task and contain the code that we need executed.

The directory structure of a CLI application can look like this:

src/tasks/MainTask.php
php cli.php

In the above example, the cli.php is the entry point of our application, while the src/tasks directory contains all the task classes that handle each command.

Bootstrap¶

As seen above, the entry point of our CLI application is the cli.php. In that script, we need to bootstrap our application with relevant services, directives etc. This is similar to the all familiar index.php that we use for MVC applications.

<?php

declare(strict_types=1);

use Exception;
use Phalcon\Cli\Console;
use Phalcon\Cli\Dispatcher;
use Phalcon\Di\FactoryDefault\Cli as CliDI;
use Phalcon\Exception as PhalconException;
use Phalcon\Loader;
use Throwable;

$loader = new Loader();
$loader->registerNamespaces(
    [
       'MyApp' => 'src/',
    ]
);
$loader->register();

$container  = new CliDI();
$dispatcher = new Dispatcher();

$dispatcher->setDefaultNamespace('MyApp\Tasks');
$container->setShared('dispatcher', $dispatcher);

$container->setShared('config', function () {
    return include 'app/config/config.php';
});


$console = new Console($container);

$arguments = [];
foreach ($argv as $k => $arg) {
    if ($k === 1) {
        $arguments['task'] = $arg;
    } elseif ($k === 2) {
        $arguments['action'] = $arg;
    } elseif ($k >= 3) {
        $arguments['params'][] = $arg;
    }
}

try {
    $console->handle($arguments);
} catch (PhalconException $e) {
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
    exit(1);
} catch (Throwable $throwable) {
    fwrite(STDERR, $throwable->getMessage() . PHP_EOL);
    exit(1);
} catch (Exception $exception) {
    fwrite(STDERR, $exception->getMessage() . PHP_EOL);
    exit(1);
}

Let's look at the code above in more detail.

First we need to create all the necessary services for our CLI application. We are going to create a loader to autoload our tasks, the CLI application, a dispatcher and a CLI Console application. These are the minimum amount of services that we need to instantiate to create a CLI application.

Loader

$loader = new Loader();
$loader->registerNamespaces(
    [
       'MyApp' => 'src/',
    ]
);
$loader->register();

Create the Phalcon autoloader and register the namespace to point to the src/ directory.

DI

$container  = new CliDI();

Dispatcher

$dispatcher = new Dispatcher();

$dispatcher->setDefaultNamespace('MyApp\Tasks');
$container->setShared('dispatcher', $dispatcher);

CLI applications need a specific dispatcher. Phalcon\Cli\Dispatcher offers the same functionality as the main dispatcher for MVC applications, but it is tailored to CLI applications. As expected, we instantiate the dispatcher object, we set our default namespace and then register it in the DI container.

Config

$container->setShared('config', function () {
    return include 'app/config/config.php';
});

Make sure to update the include path to be relative to where your cli.php file is.

Application

$console = new Console($container);

Arguments Our application needs arguments. These come in the form of :

php ./cli.php argument1 argument2 argument3 ...

The first argument relates to the task to be executed. The second is the action and after that follow the parameters we need to pass.

$arguments = [];
foreach ($argv as $k => $arg) {
    if ($k === 1) {
        $arguments['task'] = $arg;
    } elseif ($k === 2) {
        $arguments['action'] = $arg;
    } elseif ($k >= 3) {
        $arguments['params'][] = $arg;
    }
}

As you can see in the above, we use the $argv to receive what has been passed through the command line, and we split those arguments accordingly to understand what task and action need to be invoked and with what parameters.

So for the following example:

php ./cli.php users recalculate 10

Our application will invoke the UsersTask, call the recalculate action and pass the parameter 10.

Execution

try {
    $console->handle($arguments);
} catch (PhalconException $e) {
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
    exit(1);
} catch (Throwable $throwable) {
    fwrite(STDERR, $throwable->getMessage() . PHP_EOL);
    exit(1);
} catch (Exception $exception) {
    fwrite(STDERR, $exception->getMessage() . PHP_EOL);
    exit(1);
}

In the code above, we use our console object and call handle with the calculated parameters. The CLI application will do the necessary routing and dispatch the task and action requested. If an exception is thrown, it will be caught by the catch statements and errors will be displayed on screen accordingly.

Exceptions¶

Any exception thrown in the Phalcon\Cli\Console component will be of type Phalcon\Cli\Console\Exception, which allows you to trap the exception specifically.

Tasks¶

Tasks are the equivalent of controllers in a MVC application. Any CLI application needs at least one task called MainTask and a mainAction. Any task defined needs to have a mainAction which will be called if no action is defined. You are not restricted to the number of actions that each task can contain.

An example of a task class (src/Tasks/MainTask.php) is:

<?php

declare(strict_types=1);

namespace MyApp\Tasks;

use Phalcon\Cli\Task;

class MainTask extends Task
{
    public function mainAction()
    {
        echo 'This is the default task and the default action' . PHP_EOL;
    }
}

You can implement your own tasks by either extending the supplied Phalcon\Cli\Task or writing your own class implementing the Phalcon\Cli\TaskInterface.

Actions¶

As seen above, we have specified the second parameter to be the action. The task can contain more than one actions.

<?php

declare(strict_types=1);

namespace MyApp\Tasks;

use Phalcon\Cli\Task;

class UsersTask extends Task
{
    public function mainAction()
    {
        echo 'This is the default task and the default action' . PHP_EOL;
    }

    public function regenerateAction(int $count = 0)
    {
        echo 'This is the retenerate action' . PHP_EOL;
    }
}

We can then call the main action (default action):

./cli.php users 

or the regenerate action:

./cli.php users regenerate

Parameters¶

You can also pass parameters to action. An example of how to process the parameters can be found above, in the sample bootstrap file.

<?php

declare(strict_types=1);

namespace MyApp\Tasks;

use Phalcon\Cli\Task;

class UsersTask extends Task
{
    public function mainAction()
    {
        echo 'This is the default task and the default action' . PHP_EOL;
    }

    public function addAction(int $first, int $second)
    {
        echo $first + $second . PHP_EOL;
    }
}

We can then run the following command:

php cli.php users add 4 5

9

Parameters can also be accessed through the Phalcon\Cli\Dispatcher which is helpful when passing flags in, or an unknown number of parameters.

<?php

declare(strict_types=1);

namespace MyApp\Tasks;

use Phalcon\Cli\Task;

class UsersTask extends Task
{
    public function mainAction()
    {
        print_r( $this->dispatcher->getParams() );
    }

}

Running this will then output:

php cli.php users main additional parameters

Array
(
    [0] => additional
    [1] => parameters
)

Chain¶

You can also chain tasks. To run them one after another, we need to make a small change in our bootstrap: we need to register our application in the DI container:

// ...
$console = new Console($container);
$container->setShared('console', $console);

$arguments = [];
// ...

Now that the console application is inside the DI container, we can access it from any task.

Assume we want to call the printAction() from the Users task, all we have to do is call it using the container.

<?php

namespace MyApp\Tasks;

use Phalcon\Cli\Console;
use Phalcon\Cli\Task;

/**
 * @property Console $console
 */
class UsersTask extends Task
{
    public function mainAction()
    {
        echo 'This is the default task and the default action' . PHP_EOL;

        $this->console->handle(
            [
                'task'   => 'main',
                'action' => 'print',
            ]
        );
    }

    public function printAction()
    {
        echo 'I will get printed too!' . PHP_EOL;
    }
}

This technique allows you to run any task and any action from any other task. However, it is not recommended because it could lead to maintenance nightmares. It is better to extend Phalcon\Cli\Task and implement your logic there.

Modules¶

CLI applications can also handle different modules, the same as MVC applications. You can register different modules in your CLI application, to handle different paths of your CLI application. This allows for better organization of your code and grouping of tasks.

The CLI application offers the following methods:

• getDefaultModule - string - Returns the default module name
• getModule(string $name) - array/object - Gets the module definition registered in the application via module name
• getModules - array - Return the modules registered in the application
• registerModules(array $modules, bool $merge = false) - AbstractApplication - Register an array of modules present in the application
• setDefaultModule(string $defaultModule) - AbstractApplication - Sets the module name to be used if the router doesn't return a valid module

You can register a frontend and backend module for your console application as follows:

<?php

declare(strict_types=1);

use Exception;
use MyApp\Modules\Backend\Module as BackendModule;
use MyApp\Modules\Frontend\Module as FrontendModule;
use Phalcon\Cli\Console;
use Phalcon\Cli\Dispatcher;
use Phalcon\Di\FactoryDefault\Cli as CliDI;
use Phalcon\Exception as PhalconException;
use Phalcon\Loader;
use Throwable;

$loader = new Loader();
$loader->registerNamespaces(
    [
       'MyApp' => 'src/',
    ]
);
$loader->register();

$container  = new CliDI();
$dispatcher = new Dispatcher();

$dispatcher->setDefaultNamespace('MyApp\Tasks');
$container->setShared('dispatcher', $dispatcher);

$console = new Console($container);

$console->registerModules(
    [
        'frontend' => [
            'className' => BackendModule::class,
            'path'      => './src/frontend/Module.php',
        ],
        'backend' => [
            'className' => FrontendModule::class,
            'path'      => './src/backend/Module.php',
        ],
    ]
);

$arguments = [];
foreach ($argv as $k => $arg) {
    if ($k === 1) {
        $arguments['task'] = $arg;
    } elseif ($k === 2) {
        $arguments['action'] = $arg;
    } elseif ($k >= 3) {
        $arguments['params'][] = $arg;
    }
}

try {
    $console->handle($arguments);
} catch (PhalconException $e) {
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
    exit(1);
} catch (Throwable $throwable) {
    fwrite(STDERR, $throwable->getMessage() . PHP_EOL);
    exit(1);
} catch (Exception $exception) {
    fwrite(STDERR, $exception->getMessage() . PHP_EOL);
    exit(1);
}

The above code assumes that you have structured your directories to contain modules in the frontend and backend directories.

src/
src/backend/Module.php
src/frontend/Module.php
php cli.php

Routes¶

The CLI application has its own router. By default the Phalcon CLI application uses the Phalcon\Cli\Router object, but you can implement your own by using the Phalcon\Cli\RouterInterface.

Similar to a MVC application, the Phalcon\Cli\Router uses Phalcon\Cli\Router\Route objects to store the route information. You can always implement your own objects by implementing the Phalcon\Cli\Router\RouteInterface.

The routes accept the expected regex parameters such as a-zA-Z0-9 etc. There are also additional placeholders that you can take advantage of:

The Phalcon\Cli\Router comes with two predefined routes, so that it works right out of the box. These are:

• /:task/:action
• /:task/:action/:params

If you do not wish to use the default routes, all you have to do is pass false in the Phalcon\Cli\Router object upon construction.

<?php

declare(strict_types=1);

use Phalcon\Cli\Router;

$router = new Router(false);

For more information regarding routes and the route classes, you can check the Routing page.

Events¶

CLI applications are also events aware. You can use the setEventsManager and getEventsManager methods to access the events manager.

The following events are available:

If you use the Phalcon\Cli\Dispatcher you can also take advantage of the beforeException event, which can stop operations and is fired from the dispatcher object.