---
title: "Phalcon Cli"
version: "5.20"
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.phalcon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Phalcon Cli
:::info[NOTE]
All classes are prefixed with `Phalcon`
:::
## Cli\Console
Class
This component allows to create CLI applications using Phalcon
- `\stdClass`
- [`Phalcon\Di\Injectable`](/5.20/api/phalcon_di/#diinjectable)
- [`Phalcon\Application\AbstractApplication`](/5.20/api/phalcon_application/#applicationabstractapplication)
- **`Phalcon\Cli\Console`**
`Closure` · `Phalcon\Application\AbstractApplication` · `Phalcon\Cli\Console\Exceptions\ContainerRequired` · `Phalcon\Cli\Console\Exceptions\InvalidModuleDefinition` · `Phalcon\Cli\Console\Exceptions\ModuleDefinitionPathNotFound` · `Phalcon\Cli\Router\Route` · `Phalcon\Contracts\Cli\CliTypes` · `Phalcon\Events\ManagerInterface` · `Phalcon\Mvc\ModuleDefinitionInterface` · `Phalcon\Traits\Php\FileTrait`
### Method Summary
Handle the whole command-line tasks
Set a specific argument
### Properties
### Methods
handle()
```php
public function handle( array|null $arguments = null );
```
Handle the whole command-line tasks
setArgument()
```php
public function setArgument(
array|null $arguments = null,
bool $str = true,
bool $shift = true
): static;
```
Set a specific argument
## Cli\Console\Exception
Class
Exceptions thrown in Phalcon\Cli\Console will use this class
- `\Exception`
- [`Phalcon\Application\Exception`](/5.20/api/phalcon_application/#applicationexception)
- **`Phalcon\Cli\Console\Exception`**
- [`Phalcon\Cli\Console\Exceptions\ContainerRequired`](#cliconsoleexceptionscontainerrequired)
- [`Phalcon\Cli\Console\Exceptions\InvalidModuleDefinition`](#cliconsoleexceptionsinvalidmoduledefinition)
- [`Phalcon\Cli\Console\Exceptions\ModuleDefinitionPathNotFound`](#cliconsoleexceptionsmoduledefinitionpathnotfound)
## Cli\Console\Exceptions\ContainerRequired
Class
- `\Exception`
- [`Phalcon\Application\Exception`](/5.20/api/phalcon_application/#applicationexception)
- [`Phalcon\Cli\Console\Exception`](#cliconsoleexception)
- **`Phalcon\Cli\Console\Exceptions\ContainerRequired`**
`Phalcon\Cli\Console\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct();
```
## Cli\Console\Exceptions\InvalidModuleDefinition
Class
- `\Exception`
- [`Phalcon\Application\Exception`](/5.20/api/phalcon_application/#applicationexception)
- [`Phalcon\Cli\Console\Exception`](#cliconsoleexception)
- **`Phalcon\Cli\Console\Exceptions\InvalidModuleDefinition`**
`Phalcon\Cli\Console\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct(
string|null $name = null,
string|null $reason = null
);
```
## Cli\Console\Exceptions\ModuleDefinitionPathNotFound
Class
- `\Exception`
- [`Phalcon\Application\Exception`](/5.20/api/phalcon_application/#applicationexception)
- [`Phalcon\Cli\Console\Exception`](#cliconsoleexception)
- **`Phalcon\Cli\Console\Exceptions\ModuleDefinitionPathNotFound`**
`Phalcon\Cli\Console\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $path );
```
## Cli\Dispatcher
Class
Dispatching is the process of taking the command-line arguments, extracting
the module name, task name, action name, and optional parameters contained in
it, and then instantiating a task and calling an action on it.
```php
use Phalcon\Di\Di;
use Phalcon\Cli\Dispatcher;
$di = new Di();
$dispatcher = new Dispatcher();
$dispatcher->setDi($di);
$dispatcher->setTaskName("posts");
$dispatcher->setActionName("index");
$dispatcher->setParams([]);
$handle = $dispatcher->dispatch();
```
- `\stdClass`
- [`Phalcon\Di\AbstractInjectionAware`](/5.20/api/phalcon_di/#diabstractinjectionaware)
- [`Phalcon\Dispatcher\AbstractDispatcher`](/5.20/api/phalcon_dispatcher/#dispatcherabstractdispatcher)
- **`Phalcon\Cli\Dispatcher`** - implements [`Phalcon\Cli\DispatcherInterface`](#clidispatcherinterface)
`Phalcon\Cli\Dispatcher\Exception` · `Phalcon\Contracts\Cli\CliTypes` · `Phalcon\Dispatcher\AbstractDispatcher` · `Phalcon\Events\ManagerInterface` · `Phalcon\Filter\FilterInterface`
### Method Summary
Calls the action method.
Returns the active task in the dispatcher
Returns the latest dispatched controller
Gets an option by its name or numeric index
Get dispatched options
Gets last dispatched task name
Gets the default task suffix
Check if an option exists
Sets the default task name
Set the options to be dispatched
Sets the task name to be dispatched
Sets the default task suffix
Handles a user exception
Throws an internal exception
### Properties
### Methods
callActionMethod()
```php
public function callActionMethod(
mixed $handler,
string $actionMethod,
array $params = []
): mixed;
```
Calls the action method.
The CLI options collected by the dispatcher are appended to the
positional `parameters` before the call, so a task action receives any
options as trailing arguments after its declared parameters.
getActiveTask()
```php
public function getActiveTask(): TaskInterface;
```
Returns the active task in the dispatcher
getLastTask()
```php
public function getLastTask(): TaskInterface;
```
Returns the latest dispatched controller
getOption()
```php
public function getOption(
mixed $option,
mixed $filters = null,
mixed $defaultValue = null
): mixed;
```
Gets an option by its name or numeric index
getOptions()
```php
public function getOptions(): array;
```
Get dispatched options
getTaskName()
```php
public function getTaskName(): string;
```
Gets last dispatched task name
getTaskSuffix()
```php
public function getTaskSuffix(): string;
```
Gets the default task suffix
hasOption()
```php
public function hasOption( mixed $option ): bool;
```
Check if an option exists
setDefaultTask()
```php
public function setDefaultTask( string $taskName ): void;
```
Sets the default task name
setOptions()
```php
public function setOptions( array $options ): void;
```
Set the options to be dispatched
setTaskName()
```php
public function setTaskName( string $taskName ): void;
```
Sets the task name to be dispatched
setTaskSuffix()
```php
public function setTaskSuffix( string $taskSuffix ): void;
```
Sets the default task suffix
handleException()
```php
protected function handleException( \Exception $exception );
```
Handles a user exception
throwDispatchException()
```php
protected function throwDispatchException(
string $message,
int $exceptionCode = 0
);
```
Throws an internal exception
## Cli\DispatcherInterface
Interface
Interface for Phalcon\Cli\Dispatcher
- [`Phalcon\Contracts\Dispatcher\Dispatcher`](/5.20/api/phalcon_contracts/#contractsdispatcherdispatcher)
- [`Phalcon\Contracts\Cli\Dispatcher`](/5.20/api/phalcon_contracts/#contractsclidispatcher)
- **`Phalcon\Cli\DispatcherInterface`**
`Phalcon\Contracts\Cli\Dispatcher`
## Cli\Dispatcher\Exception
Class
Exceptions thrown in Phalcon\Cli\Dispatcher will use this class
- `\Exception`
- [`Phalcon\Dispatcher\Exception`](/5.20/api/phalcon_dispatcher/#dispatcherexception)
- **`Phalcon\Cli\Dispatcher\Exception`**
## Cli\Router
Class
Phalcon\Cli\Router is the standard framework router. Routing is the process
of taking a command-line arguments and decomposing it into parameters to
determine which module, task, and action of that task should receive the
request.
```php
$router = new \Phalcon\Cli\Router();
$router->handle(
[
"module" => "main",
"task" => "videos",
"action" => "process",
]
);
echo $router->getTaskName();
```
- `\stdClass`
- [`Phalcon\Di\AbstractInjectionAware`](/5.20/api/phalcon_di/#diabstractinjectionaware)
- **`Phalcon\Cli\Router`** - implements [`Phalcon\Cli\RouterInterface`](#clirouterinterface)
`Phalcon\Cli\Router\Exception` · `Phalcon\Cli\Router\Exceptions\BeforeMatchNotCallable` · `Phalcon\Cli\Router\Exceptions\RouterArgumentsInvalidType` · `Phalcon\Cli\Router\Route` · `Phalcon\Cli\Router\RouteInterface` · `Phalcon\Contracts\Cli\CliTypes` · `Phalcon\Di\AbstractInjectionAware` · `Phalcon\Di\DiInterface`
### Method Summary
Phalcon\Cli\Router constructor
Adds a route to the router
Returns processed action name
Returns the route that matches the handled URI
Returns the sub expressions in the regular expression matched
Returns processed module name
Returns processed extra params
Returns processed extra params
Returns a route object by its id
Returns a route object by its name
Returns all the routes defined in the router
Returns processed task name
Handles routing information received from command-line arguments
Sets the default action name
Sets the name of the default module
Sets the default controller name
Sets an array of default paths. If a route is missing a path the router
Checks if the router matches any of the defined routes
### Properties
### Methods
__construct()
```php
public function __construct( bool $defaultRoutes = true );
```
Phalcon\Cli\Router constructor
add()
```php
public function add(
string $pattern,
mixed $paths = null
): RouteInterface;
```
Adds a route to the router
```php
$router->add("/about", "About::main");
```
getActionName()
```php
public function getActionName(): string;
```
Returns processed action name
getMatchedRoute()
```php
public function getMatchedRoute(): RouteInterface|null;
```
Returns the route that matches the handled URI
getMatches()
```php
public function getMatches(): array;
```
Returns the sub expressions in the regular expression matched
getModuleName()
```php
public function getModuleName(): string;
```
Returns processed module name
getParameters()
```php
public function getParameters(): array;
```
Returns processed extra params
getParams()
```php
public function getParams(): array;
```
Returns processed extra params
getRouteById()
```php
public function getRouteById( mixed $id ): bool|RouteInterface;
```
Returns a route object by its id
getRouteByName()
```php
public function getRouteByName( string $name ): bool|RouteInterface;
```
Returns a route object by its name
getRoutes()
```php
public function getRoutes(): Route[];
```
Returns all the routes defined in the router
getTaskName()
```php
public function getTaskName(): string;
```
Returns processed task name
handle()
```php
public function handle( mixed $arguments = null );
```
Handles routing information received from command-line arguments
setDefaultAction()
```php
public function setDefaultAction( string $actionName ): static;
```
Sets the default action name
setDefaultModule()
```php
public function setDefaultModule( string $moduleName ): static;
```
Sets the name of the default module
setDefaultTask()
```php
public function setDefaultTask( string $taskName ): static;
```
Sets the default controller name
setDefaults()
```php
public function setDefaults( array $defaults ): static;
```
Sets an array of default paths. If a route is missing a path the router
will use the defined here. This method must not be used to set a 404
route
```php
$router->setDefaults(
[
"module" => "common",
"action" => "index",
]
);
```
wasMatched()
```php
public function wasMatched(): bool;
```
Checks if the router matches any of the defined routes
## Cli\RouterInterface
Interface
Interface for Phalcon\Cli\Router
- **`Phalcon\Cli\RouterInterface`**
`Phalcon\Cli\Router\RouteInterface` · `Phalcon\Contracts\Cli\CliTypes`
### Method Summary
Adds a route to the router on any HTTP method
Returns processed action name
Returns the route that matches the handled URI
Return the sub expressions in the regular expression matched
Returns processed module name
Returns processed extra params
Returns processed extra params
Returns a route object by its id
Returns a route object by its name
Return all the routes defined in the router
Returns processed task name
Handles routing information received from the rewrite engine.
Sets the default action name
Sets the name of the default module
Sets the default task name
Sets an array of default paths
Check if the router matches any of the defined routes
### Methods
add()
```php
public function add(
string $pattern,
mixed $paths = null
): RouteInterface;
```
Adds a route to the router on any HTTP method
getActionName()
```php
public function getActionName(): string;
```
Returns processed action name
getMatchedRoute()
```php
public function getMatchedRoute(): RouteInterface|null;
```
Returns the route that matches the handled URI
getMatches()
```php
public function getMatches(): array;
```
Return the sub expressions in the regular expression matched
getModuleName()
```php
public function getModuleName(): string;
```
Returns processed module name
getParameters()
```php
public function getParameters(): array;
```
Returns processed extra params
getParams()
```php
public function getParams(): array;
```
Returns processed extra params
getRouteById()
```php
public function getRouteById( mixed $id ): bool|RouteInterface;
```
Returns a route object by its id
@todo change param type to string
getRouteByName()
```php
public function getRouteByName( string $name ): bool|RouteInterface;
```
Returns a route object by its name
getRoutes()
```php
public function getRoutes(): RouteInterface[];
```
Return all the routes defined in the router
getTaskName()
```php
public function getTaskName(): string;
```
Returns processed task name
handle()
```php
public function handle( mixed $arguments = null );
```
Handles routing information received from the rewrite engine.
When `arguments` is a string (or null), it is matched against the
registered routes. When it is an array, matching is bypassed entirely:
the array is treated as the already-resolved module/task/action/params,
so `wasMatched()` stays false and `getMatchedRoute()` returns null even
though routing succeeded.
setDefaultAction()
```php
public function setDefaultAction( string $actionName ): RouterInterface;
```
Sets the default action name
setDefaultModule()
```php
public function setDefaultModule( string $moduleName ): RouterInterface;
```
Sets the name of the default module
setDefaultTask()
```php
public function setDefaultTask( string $taskName ): RouterInterface;
```
Sets the default task name
setDefaults()
```php
public function setDefaults( array $defaults ): RouterInterface;
```
Sets an array of default paths
wasMatched()
```php
public function wasMatched(): bool;
```
Check if the router matches any of the defined routes
## Cli\Router\Exception
Class
Exceptions thrown in Phalcon\Cli\Router will use this class
- `\Exception`
- **`Phalcon\Cli\Router\Exception`**
- [`Phalcon\Cli\Router\Exceptions\BeforeMatchNotCallable`](#clirouterexceptionsbeforematchnotcallable)
- [`Phalcon\Cli\Router\Exceptions\InvalidRoutePaths`](#clirouterexceptionsinvalidroutepaths)
- [`Phalcon\Cli\Router\Exceptions\RouterArgumentsInvalidType`](#clirouterexceptionsrouterargumentsinvalidtype)
## Cli\Router\Exceptions\BeforeMatchNotCallable
Class
- `\Exception`
- [`Phalcon\Cli\Router\Exception`](#clirouterexception)
- **`Phalcon\Cli\Router\Exceptions\BeforeMatchNotCallable`**
`Phalcon\Cli\Router\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $route = "" );
```
## Cli\Router\Exceptions\InvalidRoutePaths
Class
- `\Exception`
- [`Phalcon\Cli\Router\Exception`](#clirouterexception)
- **`Phalcon\Cli\Router\Exceptions\InvalidRoutePaths`**
`Phalcon\Cli\Router\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $route = "" );
```
## Cli\Router\Exceptions\RouterArgumentsInvalidType
Class
- `\Exception`
- [`Phalcon\Cli\Router\Exception`](#clirouterexception)
- **`Phalcon\Cli\Router\Exceptions\RouterArgumentsInvalidType`**
`Phalcon\Cli\Router\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $type = "" );
```
## Cli\Router\Route
Class
This class represents every route added to the router
- **`Phalcon\Cli\Router\Route`** - implements [`Phalcon\Cli\Router\RouteInterface`](#clirouterrouteinterface)
`Phalcon\Cli\Router\Exceptions\BeforeMatchNotCallable` · `Phalcon\Cli\Router\Exceptions\InvalidRoutePaths` · `Phalcon\Contracts\Cli\CliTypes`
### Method Summary
Constructor
Sets a callback that is called if the route is matched.
Replaces placeholders from pattern returning a valid PCRE regular
Adds a converter to perform an additional transformation for certain
Set the routing delimiter.
Extracts parameters from a string
Returns the 'before match' callback if any
Returns the route's compiled pattern
Returns the router converter
Get routing delimiter
Returns the route's description
Returns the route's name
Returns the paths
Returns the route's pattern
Returns the paths using positions as keys and names as values
Returns the route's id
Reconfigure the route adding a new pattern and a set of paths
Resets the internal route id generator.
Sets the route's description
Sets the route's name
### Constants
### Properties
### Methods
__construct()
```php
public function __construct(
string $pattern,
mixed $paths = null
);
```
Constructor
beforeMatch()
```php
public function beforeMatch( mixed $callback ): RouteInterface;
```
Sets a callback that is called if the route is matched.
The developer can implement any arbitrary conditions here
If the callback returns false the route is treated as not matched
compilePattern()
```php
public function compilePattern( string $pattern ): string;
```
Replaces placeholders from pattern returning a valid PCRE regular
expression
convert()
```php
public function convert(
string $name,
mixed $converter
): RouteInterface;
```
Adds a converter to perform an additional transformation for certain
parameter
delimiter()
```php
public static function delimiter( string|null $delimiter = null ): void;
```
Set the routing delimiter.
This sets a process-global delimiter that each route captures at
construction time. Configure it once during bootstrap, before any routes
are created: routes built before and after a change keep their own
delimiter, and `Console::setArgument()` reads the current value when it
parses arguments.
```php
public function extractNamedParams( string $pattern ): array|bool;
```
Extracts parameters from a string
getBeforeMatch()
```php
public function getBeforeMatch(): mixed;
```
Returns the 'before match' callback if any
getCompiledPattern()
```php
public function getCompiledPattern(): string;
```
Returns the route's compiled pattern
getConverters()
```php
public function getConverters(): array;
```
Returns the router converter
getDelimiter()
```php
public static function getDelimiter(): string;
```
Get routing delimiter
getDescription()
```php
public function getDescription(): string;
```
Returns the route's description
getName()
```php
public function getName(): string;
```
Returns the route's name
getPaths()
```php
public function getPaths(): array;
```
Returns the paths
getPattern()
```php
public function getPattern(): string;
```
Returns the route's pattern
getReversedPaths()
```php
public function getReversedPaths(): array;
```
Returns the paths using positions as keys and names as values
getRouteId()
```php
public function getRouteId(): string;
```
Returns the route's id
```php
public function reConfigure(
string $pattern,
mixed $paths = null
): void;
```
Reconfigure the route adding a new pattern and a set of paths
reset()
```php
public static function reset(): void;
```
Resets the internal route id generator.
Intended for test isolation only. The router keys its route map by the
route id, so resetting the sequence while a router still holds routes
makes newly created routes overwrite existing entries.
setDescription()
```php
public function setDescription( string $description ): RouteInterface;
```
Sets the route's description
setName()
```php
public function setName( string $name ): RouteInterface;
```
Sets the route's name
```php
$router->add(
"/about",
[
"controller" => "about",
]
)->setName("about");
```
## Cli\Router\RouteInterface
Interface
Interface for Phalcon\Cli\Router\Route
Note: `Phalcon\Cli\Router` always constructs and returns the concrete
`Phalcon\Cli\Router\Route`, and there is no injection point for an externally
built route, so this interface is a marker for type hints rather than an
implementable contract. The fluent route API used in practice -
`beforeMatch()`, `getBeforeMatch()`, `convert()`, and `getConverters()` - is
declared on the concrete `Route` class, not here.
- **`Phalcon\Cli\Router\RouteInterface`**
`Phalcon\Contracts\Cli\CliTypes`
### Method Summary
Replaces placeholders from pattern returning a valid PCRE regular
Set the routing delimiter
Returns the route's pattern
Get routing delimiter
Returns the route's description
Returns the route's name
Returns the paths
Returns the route's pattern
Returns the paths using positions as keys and names as values
Returns the route's id
Reconfigure the route adding a new pattern and a set of paths
Resets the internal route id generator
Sets the route's description
Sets the route's name
### Methods
compilePattern()
```php
public function compilePattern( string $pattern ): string;
```
Replaces placeholders from pattern returning a valid PCRE regular
expression
delimiter()
```php
public static function delimiter( string|null $delimiter = null );
```
Set the routing delimiter
getCompiledPattern()
```php
public function getCompiledPattern(): string;
```
Returns the route's pattern
getDelimiter()
```php
public static function getDelimiter(): string;
```
Get routing delimiter
getDescription()
```php
public function getDescription(): string;
```
Returns the route's description
getName()
```php
public function getName(): string;
```
Returns the route's name
getPaths()
```php
public function getPaths(): array;
```
Returns the paths
getPattern()
```php
public function getPattern(): string;
```
Returns the route's pattern
getReversedPaths()
```php
public function getReversedPaths(): array;
```
Returns the paths using positions as keys and names as values
getRouteId()
```php
public function getRouteId(): string;
```
Returns the route's id
```php
public function reConfigure(
string $pattern,
mixed $paths = null
): void;
```
Reconfigure the route adding a new pattern and a set of paths
reset()
```php
public static function reset(): void;
```
Resets the internal route id generator
setDescription()
```php
public function setDescription( string $description ): RouteInterface;
```
Sets the route's description
setName()
```php
public function setName( string $name ): RouteInterface;
```
Sets the route's name
## Cli\Task
Class
Every command-line task should extend this class that encapsulates all the
task functionality
A task can be used to run "tasks" such as migrations, cronjobs, unit-tests,
or anything that you want. The Task class should at least have a "mainAction"
method.
```php
class HelloTask extends \Phalcon\Cli\Task
{
// This action will be executed by default
public function mainAction()
{
}
public function findAction()
{
}
}
```
Action methods receive the routed parameters as positional arguments,
followed by any CLI options the dispatcher collected (appended as trailing
arguments). Declare optional trailing parameters to read those options.
- `\stdClass`
- [`Phalcon\Di\Injectable`](/5.20/api/phalcon_di/#diinjectable)
- **`Phalcon\Cli\Task`** - implements [`Phalcon\Cli\TaskInterface`](#clitaskinterface), [`Phalcon\Events\EventsAwareInterface`](/5.20/api/phalcon_events/#eventseventsawareinterface)
- [`Phalcon\Queue\Cli\ConsumerTask`](/5.20/api/phalcon_queue/#queuecliconsumertask)
`Phalcon\Di\Injectable` · `Phalcon\Events\EventsAwareInterface` · `Phalcon\Events\ManagerInterface` · `Phalcon\Events\Traits\EventsAwareTrait`
### Method Summary
Phalcon\Cli\Task constructor
### Methods
__construct()
```php
final public function __construct();
```
Phalcon\Cli\Task constructor
## Cli\TaskInterface
Interface
Interface for task handlers
- **`Phalcon\Cli\TaskInterface`**
Source: https://docs.phalcon.io/5.20/api/phalcon_cli/index.mdx