Attention

TYPO3 v10 has reached end-of-life as of April 30th 2023 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.

Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v10 here: TYPO3 ELTS.

Symfony Console Commands (cli)

It is possible to run TYPO3 CMS scripts from the command line. This functionality can be used to set up cronjobs, for example.

TYPO3 uses Symfony commands API for writing CLI (command line interface) commands. These commands can also be run from the TYPO3 scheduler.

Deprecated since version 10: Deprecation: #89139 - Console Commands configuration format Commands.php

New in version 10: Feature: #89139 - Add dependency injection support for console commands

Creating a new Command in Extensions

  1. Register Commands

    Commands can be registered via Dependency Injection or a PHP file. Detailed information can be read on the corresponding Symfony component documentation: https://symfony.com/doc/current/console/commands_as_services.html. E.g. how to setup aliases via Services.yaml, or how to use dependency injection in commands.

    The following example will add a command named yourext:dothings.

    Register via DI in Configuration/Services.yaml:

    services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  Vendor\Extension\:
    resource: '../Classes/*'

  Vendor\Extension\Command\DoThingsCommand:
    tags:
      - name: 'console.command'
        command: 'yourext:dothings'

    Or register Configuration/Commands.php. Deprecated since v10 and will be removed in v11:

    return [
    'yourext:dothings' => [
        'class' => \Vendor\Extension\Command\DoThingsCommand::class,
    ],
];

  2. Create the corresponding class file: Classes/Command/DoThingsCommand.php

    Symfony commands should extend the class \Symfony\Component\Console\Command\Command.

    The command should implement at least a configure() and an execute() method.

    configure()

    As the name would suggest allows to configure the command. Allows to add a description, a help text, and / or define arguments.

    execute()

    Contains the logic when executing the command.

See also

A detailed description and an example can be found in the Symfony Command Documentation.

Command Class

Example taken from ListSysLogCommand in the core and simplified:

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

class DoThingsCommand extends Command
{
    /**
     * Configure the command by defining the name, options and arguments
     */
    protected function configure()
    {
        $this->setDescription('Show entries from the sys_log database table of the last 24 hours.')
           ->setHelp('Prints a list of recent sys_log entries.' . LF . 'If you want to get more detailed information, use the --verbose option.');
    }

    /**
     * Executes the command for showing sys_log entries
     *
     * @param InputInterface $input
     * @param OutputInterface $output
     */
    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $io = new SymfonyStyle($input, $output);
        $io->title($this->getDescription());

        // ...
        $io->writeln('Write something');
        return 0;
    }
}

Return value

Changed in version 10: It is now mandatory to return a value in execute(). Since TYPO3 version 10 (and symfony/console version 5), using execute() without return will result in an exception.

The return type is int, Command::SUCCESS or Command::FAILURE can be used.

Passing Arguments

Since your command is inherited from Symfony\Component\Console\Command\Command, it is possible to define arguments (ordered) and options (unordered) using the Symfony command API. This is explained in depth on the following Symfony Documentation page:

See also

Add an optional argument and an optional option to your command:

/**
 * Configure the command by defining the name, options and arguments
 */
protected function configure()
{
    $this->setDescription('Run content importer. Without arguments all available wizards will be run.')
        ->addArgument(
            'wizardName',
            InputArgument::OPTIONAL,
            'Here is a description for your argument'
        )
        ->addOption(
           'brute-force',
           'b',
           InputOption::VALUE_OPTIONAL,
           'Some optional option for your wizard(s). You can use --brute-force or -b when running command'
       );
}

This command takes one optional argument wizardName and one optional option, which can be passed on the command line:

vendor/bin/typo3 yourext:dothings [-b] [wizardName]

This argument can be retrieved with $input->getArgument(), the options with $input->getOption(), for example:

protected function execute(InputInterface $input, OutputInterface $output)
{
   // ...

   if ($input->getArgument('wizardName')) {

      // ...

   }

   if ($input->getOption('brute-force')) {

   // ...

   }

Deactivating the Command in Scheduler

By default, the command can be used in the scheduler too. This can be disabled by setting schedulable to false in Configuration/Services.yaml:

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  Vendor\Extension\:
    resource: '../Classes/*'

  Vendor\Extension\Command\DoThingsCommand:
    tags:
      - name: 'console.command'
        command: 'yourext:dothings'
        schedulable: false

Or inside Configuration/Commands.php. Deprecated since v10 and will be removed in v11:

return [
    'yourext:dothings' => [
        'class' => \Vendor\Extension\Command\DoThingsCommand::class,
        'schedulable' => false,
    ],
];

Initialize Backend User

A backend user can be initialized with this call inside execute() method:

Bootstrap::initializeBackendAuthentication();

This is necessary when using DataHandler or other backend permission handling related tasks.

Running the Command From the Command Line

The above example can be run via command line:

vendor/bin/typo3 yourext:dothings

Show help for the command:

vendor/bin/typo3 yourext:dothings -h

Tip

If you installed TYPO3 without Composer, the path for the executable is typo3/sysext/core/bin/typo3.

Running the Command From the Scheduler

By default, it is possible to run the command from the TYPO3 scheduler as well. To do this, select the task Execute console commands followed by your command in the Schedulable Command field.

Note

You need to save and reopen the task to define command arguments.

In order to prevent commands from being set up as Scheduler tasks, see Deactivating the Command in Scheduler.

More information