Dionysopoulos.me

Like all Symfony Console applications, the Joomla CLI Application is extended with Command classes. The Joomla command classes need to extend from the \Joomla\Console\Command\AbstractCommand class.

Where do command classes live?

There are no hard rules about where you should put your command classes. There are two possibilities which make the most sense, as far as I can see.

A sample command class

<?php
namespace Acme\Component\Example\Administrator\CliCommand;

defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;
use Joomla\CMS\MVC\Factory\MVCFactoryAwareTrait;
use Joomla\CMS\MVC\Model\DatabaseAwareTrait;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

class ItemsList extends \Joomla\Console\Command\AbstractCommand
{
  use MVCFactoryAwareTrait;
  use DatabaseAwareTrait;

  /**
   * The default command name
   *
   * @var    string
   */
  protected static $defaultName = 'example:items:list';

  /**
   * @var   SymfonyStyle
   */
  private $ioStyle;

  /**
   * @var   InputInterface
   */
  private $cliInput;

  /**
   * @inheritDoc
   */
  protected function doExecute(InputInterface $input, OutputInterface $output): int
  {
    // Configure the Symfony output helper
    $this->configureSymfonyIO($input, $output);

    // Collect the options
    $search = $input->getOption('search') ?? null;

    // Get the items, using the backend model
    /** @var \Joomla\CMS\MVC\Model\BaseDatabaseModel $itemsModel */
    $itemsModel = $this->getMVCFactory()->createModel('Items', 'Administrator');

    if ($search)
    {
      $itemsModel->setState('filter.search', $search);
    }

    $items = $itemsModel->getItems();

    // If no items are found show a warning and set the exit code to 1.
    if (empty($items))
    {
      $this->ioStyle->warning('No items found matching your criteria');

      return 1;
    }

    // Reshape the items into something humans can read.
    $items = array_map(
      function (object $item): array
      {
        return [
          $item->id,
          $item->title,
          $item->published ? Text::_('JYES') : Text::_('JNO')
        ];
      },
      $items
    );

    // Display the items in a table and set the exit code to 0
    $this->ioStyle->table(
      [
        Text::_('COM_EXAMPLE_FIELD_HEADER_ID'),
        Text::_('JGLOBAL_TITLE'),
        Text::_('JPUBLISHED'),
      ],
      $items
    );

    return 0;
  }

  /**
   * Configure the command.
   *
   * @return  void
   */
  protected function configure(): void
  {
    $this->setDescription(Text::_('COM_EXAMPLE_CLI_ITEMS_LIST_DESC'));
    $this->setHelp(Text::_('COM_EXAMPLE_CLI_ITEMS_LIST_HELP'));

    $this->addOption('search', 's', InputOption::VALUE_OPTIONAL, Text::_('COM_EXAMPLE_CLI_CONFIG_SEARCH'));
  }

  /**
   * Configure the IO.
   *
   * @param   InputInterface   $input   The input to inject into the command.
   * @param   OutputInterface  $output  The output to inject into the command.
   *
   * @return  void
   */
  private function configureSymfonyIO(InputInterface $input, OutputInterface $output)
  {
    $this->cliInput = $input;
    $this->ioStyle  = new SymfonyStyle($input, $output);
  }

}

The command name ($defaultName)

A command class needs to provide a name for the command being executed. In Joomla 4 ,third party extensions should use the convention component:command and component:command:subcommand where component is the name of the component without com_. The command part is the name of your command. If you need to implement subcommands you can add a third, fourth etc part in your command name, all separated with colons. For example we could have the following names:

The name of the command goes into the command class' $defaultName static property.

Command configuration

Each command needs a bit of configuration so that Joomla knows how to display it in a list of commands (php joomla.php list), provide help for a command (e.g. php joomla.php example:items:list --help) and parse the arguments and options to the command. This is done in the configure() method.

Calling setDescription sets the short help text which appears next to the command in the list of available commands.

Calling setHelp sets the longer help text which appears in the per-command help page.

The rest of the method body defines the arguments and options to the commands, whether they are required or optional, their default values and their associated help text. This is explained in detail in the Symfony Console documentation article “Console Input (Arguments & Options)”.

Command implementation

The implementation of your command, the code which executes when you call it, is in the doExecute method.

The first thing we do is get a SymfonyStyle object to facilitate the formatting our command's output. It has all sorts of useful things, from titles and success / warning / error blocks to progress bars and tables. You can read more about it in the Symfony Console documentation article How to Style a Console Command.

The rest of the code is pretty straightforward; it's standard Joomla stuff. What you need to note is that we always return an integer. This MUST be an integer from 0 to 255 (inclusive). It is used as the command line application's exit code. It is very strongly recommended that you use a different exit code for each result state of your command and document it. This can be used in automation scenarios, e.g. someone using your CLI commands in an Ansible playbook or a custom shell script.