Attention

TYPO3 v9 has reached its end-of-life September 30th, 2021 and is not maintained by the community anymore. Looking for a stable version? Use the version switch on the top left.

You can order Extended Long Term Support (ELTS) here: TYPO3 ELTS.

Command Controllers

Note

Since TYPO3 8, it is possible to use Symfony commands in TYPO3. This is the preferred method and is documented in "TYPO3 Explained" Symfony Console Commands (cli). You can still use Extbase Command Controllers, but they have been deprecated in 9.4 and will trigger a PHP E_USER_DEPRECATED error if used from the command line.

Command controllers make functionality available at the command line and in the scheduler backend module.

They can provide functionality for recurring tasks like mail queues, cleanups, imports and more, which is then available for administrators and regular backend users.

Creating command controllers

A CommandController needs to be located at Classes/Command/. This following simple example meets the minimum requirements.

Classes/Command/SimpleCommandController.php:

<?php
namespace Vendor\Example\Command;

use \TYPO3\CMS\Extbase\Mvc\Controller\CommandController;

class SimpleCommandController extends CommandController
{

    public function simpleCommand()
    {

    }
}

Requirements are:

1. Classname must match file name.

2. Class must extend \TYPO3\CMS\Extbase\Mvc\Controller\CommandController.

3. Method names must end with Command.

After creation of the controller you need to register it. Add the following line to ext_localconf.php to let TYPO3 know about the controller.

/ext_localconf.php:

<?php

if (TYPO3_MODE === 'BE') {
    $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['extbase']['commandControllers']['ExtensionName-MeaningFullName'] =
        \Vendor\ExtKey\Command\SimpleCommandController::class;
}

Calling commands

Clear the backend-cache to complete the registration. Once a command is registered and available, you can check the availability by calling ` /cli_dispatch.phpsh extbase help`.

The output should look like:

EXTENSION "EXAMPLE":
-------------------------------------------------------------------------------
  simple:simple

To execute your command call typo3/cli_dispatch.phpsh extbase simple:simple.

Note

Commands are running in TYPO3 Backend context. Therefore you cannot directly access TypoScript of frontend pages for example.

Command arguments

Some commands need to be flexible and therefore need some arguments which may be optional or required.

As with ActionController you can define them the same way:

/**
 * @param int $required
 * @param bool $optional
 */
public function argumentsCommand($required, $optional = false)
{

}

As soon as you have parameter for your command, you must document them, to enable TYPO3 to detect there types for mapping, and whether they are required or not. To make an argument optional, provide a default value.

TYPO3 will map the incoming values to the documented type.

You can check whether the documentation is correct, by calling typo3/cli_dispatch.phpsh extbase help simple:arguments. The result will be something like:

COMMAND:
  example:simple:arguments

USAGE:
  /typo3/cli_dispatch.phpsh typo3/cli_dispatch.phpsh extbase simple:arguments [<options>] <required>

ARGUMENTS:
  --required

OPTIONS:
  --optional

Command documentation

So far you have provided information on what the command and its arguments. To help others, you may want to provide further information within the PHPDoc that is to be displayed on the commandline:

/**
 * This is a short description.
 *
 * This will be further information available to everyone asking for it
 * from the cli.
 *
 * @param int $required This is an required argument.
 * @param bool $optional And this is an optional argument.
 */
public function argumentsCommand($required, $optional = false)
{

}

The information is shown when calling typo3/cli_dispatch.phpsh extbase help simple:arguments:

This is a short description.

COMMAND:
  example:simple:arguments

USAGE:
  /typo3/cli_dispatch.phpsh typo3/cli_dispatch.phpsh extbase simple:arguments [<options>] <required>

ARGUMENTS:
  --required           This is an required argument.

OPTIONS:
  --optional           And this is an optional argument.

DESCRIPTION:
  This will be further information available to everyone asking for it
  from the cli.