Command Line Console Plugins in Joomla

1. De Basis

1.1 Wat is de Joomla CLI?

De CLI is een manier om Joomla vanuit een terminal te draaien in plaats van vanuit een browser. Je typt een commando, Joomla voert het uit, drukt het resultaat als tekst af en stopt. Er is geen pagina, geen template en geen bezoeker.

De enige ingang is een bestand in je site:

cli/joomla.php

Je start het met PHP op de server:

php cli/joomla.php list

Dat commando start de hele Joomla-applicatie op de achtergrond op en drukt vervolgens een lijst af van elk commando dat het kent. De website en de CLI delen dezelfde code, dezelfde database en dezelfde configuratie. Het enige verschil is, hoe je ze bereikt.

1.2 Waarom uberhaupt een command line?

Sommige klussen zijn simpelweg makkelijker, sneller of veiliger zonder browser:

• Automatisering. Een geplande taak (cron) kan elke nacht een commando draaien zonder dat er iemand bij is.
• Onderhoud. Leeg de cache, voer databasereparaties uit of zet de site offline in een regel.
• Bulkwerk. Voeg veel gebruikers toe, installeer extensies of bouw de zoekindex opnieuw op zonder door schermen te klikken.
• Herstel. Als de beheerkant op slot zit of stuk is, kun je via de CLI vaak nog een wachtwoord resetten of de site weer online brengen.
• Snelheid. Een commando gebruikt niet je Joomla template, geen modules en slaat daarm het renderen van de pagina over, dus het start en eindigt snel.

Zie de CLI als de personeelsingang van je Joomla-site: hetzelfde gebouw, dezelfde kamers, maar een ingang bedoeld voor personeel en machines in plaats van het publiek.

1.3 De vorm van een commando

Elk Joomla-commando volgt hetzelfde leesbare patroon. De naam gebruikt dubbele punten om verwante acties te groeperen:

php cli/joomla.php  extension:install  --path=/tmp/mod_hello.zip
                    |                  |
                    |                  └─ opties (beginnen met --)
                    └─ de commandonaam (groep:actie)

• De commandonaam vertelt Joomla wat het moet doen, bijvoorbeeld cache:clean of user:add.
• Argumenten zijn waarden die het commando op een vaste plek verwacht.
• Opties beginnen met -- en mogen in elke volgorde staan, bijvoorbeeld --path=....

Deze naamgeving is geen versiering. Het deel voor de dubbele punt is een namespace, dus alle extension:*-commando's horen bij elkaar en kunnen als groep worden getoond.

3. Een rondleiding langs de Joomla core commando's

Joomla 6 wordt geleverd met een handige set commando's, kant-en-klaar. Je installeert niets; ze horen bij de core. Hier zijn de families die je het meest zult gebruiken.

3.1 Cache, configuratie en sitestatus

3.2 Gebruikers

Alleen al het commando user:reset-password is het waard om te kennen: het is de standaardmanier om weer binnen te komen als je buitengesloten bent van de beheerlogin.

3.3 Extensies en updates

3.4 Scheduler, zoeken en sessies

Je hoeft deze lijst niet uit je hoofd te leren. Draai php cli/joomla.php list op je eigen site en de actuele, exacte set wordt voor je afgedrukt.

5. Hoe commando's worden geregistreerd

Een commando is een kleine klasse die Joomla weet te vinden en uit te voeren. Er zijn twee manieren waarop een commando de applicatie bereikt, en als je beide begrijpt, snap je hoe het hele systeem netjes uitbreidt.

5.1 Standaardcommando's

De CMS-applicatie noemt zijn eigen ingebouwde commando's in een methode genaamd getDefaultCommands(). Elk ervan is een klasse die wordt aangemaakt als de applicatie start:

protected function getDefaultCommands(): array
{
    return array_merge(parent::getDefaultCommands(), [
        new Console\CleanCacheCommand(),
        new Console\AddUserCommand($this->getDatabase()),
        // ... en meer
    ]);
}

De eigen commando's list en help van het framework komen uit parent::getDefaultCommands(). Het CMS voegt de Joomla-specifieke daar bovenop toe.

5.2 "Luie" commando's via de DI-container

Bij elke afzonderlijke CLI-aanroep tientallen commando-objecten aanmaken zou verspilling zijn, omdat je er altijd maar een draait. Daarom worden de meeste core commando's lazy geregistreerd: Joomla houdt een simpele koppeling bij van commandonaam naar klassenaam en bouwt het object pas als je dat commando daadwerkelijk aanroept.

// Vereenvoudigd: een naam -> klasse-koppeling die aan een command loader wordt gegeven
$mapping = [
    'cache:clean'        => CleanCacheCommand::class,
    'extension:install'  => ExtensionInstallCommand::class,
    'scheduler:run'      => TasksRunCommand::class,
    // ...
];

$app->setCommandLoader(new WritableContainerLoader($container, $mapping));

De command loader vraagt de klasse pas op bij de DI-container als de naam ervan wordt opgevraagd. Dit houdt de CLI snel: er wordt niets zwaars gebouwd totdat het nodig is.

5.3 De twee paden in een plaatje

Console-applicatie
   ├─ getDefaultCommands()      → meteen aangemaakt (list, help, een paar core commando's)
   ├─ command loader (DI-map)   → lui aangemaakt, alleen bij aanroep
   └─ console-plugins           → voegen commando's toe tijdens runtime (zie volgende sectie)

Het derde pad, console-plugins, is hoe jouw extensie de lijst binnenkomt zonder ook maar een core bestand aan te raken.

7. Je eigen commando bouwen

Een commando is een enkele klasse die AbstractCommand uitbreidt. Het heeft een naam nodig, een optionele configuratie van argumenten en opties, en de code om te draaien.

7.1 Het minimale commando

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

final class HelloCommand extends AbstractCommand
{
    // De commandonaam, zoals getypt in de terminal:
    protected static $defaultName = 'hello:world';

    protected function doExecute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $io->title('Hallo vanuit de Joomla CLI');
        $io->success('Het werkt.');

        return Command::SUCCESS;   // exit-code 0
    }
}

Draai het met php cli/joomla.php hello:world zodra de plugin die het toevoegt is ingeschakeld.

7.2 Argumenten en opties configureren

Overschrijf configure() om te bepalen wat je commando accepteert en om de helptekst te schrijven:

use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;

protected function configure(): void
{
    $this->setDescription('Begroet iemand vanaf de command line');
    $this->addArgument('name', InputArgument::OPTIONAL, 'Wie te begroeten', 'world');
    $this->addOption('shout', null, InputOption::VALUE_NONE, 'Gebruik hoofdletters');
    $this->setHelp('Dit commando drukt een vriendelijke begroeting af.');
}

7.3 Invoer lezen en een resultaat teruggeven

protected function doExecute(InputInterface $input, OutputInterface $output): int
{
    $io   = new SymfonyStyle($input, $output);
    $name = $input->getArgument('name');

    if ($input->getOption('shout')) {
        $name = strtoupper($name);
    }

    $io->writeln('Hallo, ' . $name . '!');

    return Command::SUCCESS;
}

Geef altijd een van de benoemde exit-codes terug - Command::SUCCESS, Command::FAILURE of Command::INVALID - zodat scripts en cronjobs op de uitkomst kunnen reageren.

7.4 Praten met het CMS

Omdat het CMS volledig is opgestart, kan je commando dezelfde moderne API's gebruiken als een controller of model. Om met een component te werken, start je het op en vraag je de factory om een model:

$model = $this->getApplication()
    ->bootComponent('com_content')
    ->getMVCFactory()
    ->createModel('Articles', 'Administrator', ['ignore_request' => true]);

$count = \count($model->getItems());
$io->info($count . ' artikelen gevonden.');

Zo werken core commando's als cache:clean precies: ze starten een component op en roepen het model aan, en rapporteren daarna het resultaat aan de terminal.

7.5 Services injecteren via de constructor

Naar globale status grijpen binnen een commando werkt, maar de nettere manier is om de DI-container je de services te laten aanreiken die je nodig hebt. Geef je commando een constructor en vraag erom op type:

use Joomla\Database\DatabaseInterface;

final class CountUsersCommand extends AbstractCommand
{
    protected static $defaultName = 'users:count';

    public function __construct(private DatabaseInterface $db)
    {
        parent::__construct();   // roep altijd de constructor van de ouder aan
    }

    protected function doExecute(InputInterface $input, OutputInterface $output): int
    {
        $query = $this->db->getQuery(true)
            ->select('COUNT(*)')
            ->from($this->db->quoteName('#__users'));

        $total = (int) $this->db->setQuery($query)->loadResult();

        (new SymfonyStyle($input, $output))->info($total . ' gebruikers.');

        return Command::SUCCESS;
    }
}

Core commando's doen dit ook: user:add krijgt de database via de constructor in plaats van hem zelf op te halen. Je console-plugin maakt het commando dan met zijn afhankelijkheid aan bij het registreren - $this->getApplication()->addCommand(new CountUsersCommand($db)). Het resultaat is code die los gekoppeld en makkelijk te testen is, omdat je in een unittest een neppe database kunt meegeven.

9. Invoer, uitvoer en interactie

Een goed commando is prettig om met de hand te gebruiken en betrouwbaar binnen een script. De Joomla CLI geeft je de gereedschappen voor beide.

9.1 SymfonyStyle: nette uitvoer

De helper SymfonyStyle verpakt de ruwe uitvoer in nette, consistente opmaak. Core commando's gebruiken hem overal:

$io = new SymfonyStyle($input, $output);

$io->title('Systeemcache legen');     // een kop
$io->success('Cache geleegd');         // groen succesblok
$io->error('Cache niet geleegd');      // rood foutblok
$io->warning('Niets te doen');         // gele waarschuwing
$io->table(['Id', 'Naam'], $rows);     // een opgemaakte tabel

9.2 De gebruiker vragen stellen

Wanneer een mens het draait, kan een commando om ontbrekende details vragen. Het commando user:add doet precies dit als je niet elke optie meegeeft:

$username = $io->ask('Gebruikersnaam');
$password = $io->askHidden('Wachtwoord');     // invoer wordt niet op het scherm getoond
$confirm  = $io->confirm('Deze gebruiker aanmaken?', true);

Dit is vriendelijk voor mensen, maar denk aan automatisering. In een cronjob is er niemand om te antwoorden, dus geef ofwel elke waarde als optie mee, of voeg --no-interaction toe en zorg dat je commando met zijn standaardwaarden kan draaien.

9.3 Niveaus van uitgebreidheid

Laat de gebruiker kiezen hoeveel detail hij wil door de uitgebreidheid te controleren, in plaats van altijd alles af te drukken:

if ($output->isVerbose()) {        // getoond met -v
    $io->writeln('Extra detail voor de nieuwsgierige.');
}

Normale uitvoer blijft netjes, en -v, -vv of -vvv onthullen stapsgewijs meer voor het debuggen.

9.4 Vastleggen wat een commando doet

Uitvoer op het scherm verdwijnt op het moment dat een cronjob eindigt. Voor alles wat onbeheerd draait, leg je een blijvend verslag vast met het logging-framework van Joomla, in plaats van of naast de schermuitvoer:

use Joomla\CMS\Log\Log;

Log::add('Nachtelijke import gestart', Log::INFO, 'cli');
// ... doe het werk ...
Log::add('Nachtelijke import klaar: ' . $count . ' items', Log::INFO, 'cli');

Het derde argument is een categorie. Door je commando een eigen categorie te geven (hier cli) kun je die regels naar hun eigen logbestand sturen en ze later teruglezen onder Systeem → Onderhoud → Logs beheren, los van de rest van de site. Standaard staan de bestanden in het ingestelde logpad, meestal administrator/logs/.

Log de start, het einde en elke fout. Als een geplande taak om drie uur 's nachts mislukt, is het log de enige getuige die je hebt.

9.5 Een commando debuggen dat niet wil draaien

Als een commando zich misdraagt of weigert te verschijnen, werk dan deze korte checklist op volgorde af:

• Is de plugin ingeschakeld? Controleer de pluginlijst, of draai de #__extensions-query uit sectie 8.4.
• Verschijnt hij uberhaupt? Draai php cli/joomla.php list. Als hij ontbreekt, laadt de plugin niet of roept hij addCommand() niet aan.
• Klopt de namespace? Het manifest <namespace> en de mappen onder src/ moeten exact overeenkomen, anders faalt het autoloaden stilletjes.
• Draai het uitgebreid. Voeg -vvv toe om de volledige stacktrace te zien in plaats van een korte melding: php cli/joomla.php mycli:hello -vvv.
• Lees de help. php cli/joomla.php help mycli:hello bevestigt de naam, argumenten en opties die Joomla daadwerkelijk heeft geregistreerd.

De meeste meldingen van "er gebeurt niets" komen neer op een van deze vijf: uitgeschakelde plugin, ontbrekende addCommand(), of een typefout in de namespace die het autoloaden breekt.

11. CLI versus web versus Web Services

Joomla is op drie manieren bereikbaar. Ze delen dezelfde code en data, maar passen bij verschillende klussen.

Een REST-aanroep naar de Web Services API draagt zijn token in een header, zo:

curl -H "X-Joomla-Token: <token>" \
     https://example.test/api/index.php/v1/content/articles

Vuistregel: gebruik de CLI voor klussen die je op de server draait, het web voor mensen, en de Web Services API voor andere programma's die met je site praten.

13. CLI en SEO: houd het onzichtbaar voor zoekmachines

De CLI heeft niets te zoeken in zoekresultaten, en dat goed doen draait vooral om niet de verkeerde dingen doen.

• CLI-commando's produceren geen webpagina's, geen URL's en geen metadata. Er is niets voor een zoekmachine om te indexeren, en dat is precies goed.
• Maak van een commando geen publiek web-endpoint alleen om het vanuit een browser te triggeren. Dat zou krachtige acties blootstellen aan iedereen die de URL vindt.
• Houd de map cli/ buiten de publieke documentroot waar de indeling van je host dat toelaat, zodat de scripts nooit over HTTP bereikbaar zijn.
• Gebruik de CLI om SEO indirect te verbeteren: finder:index houdt Smart Search vers, en geplande taken via scheduler:run kunnen op tijd sitemaps opnieuw opbouwen of redirects opschonen.

Kortom, de CLI werkt achter de schermen. Hij helpt je publieke pagina's snel en actueel te blijven, terwijl hij zelf volledig onzichtbaar blijft voor crawlers.

15. Best practices

Als je maar een paar dingen uit dit artikel onthoudt, onthoud dan deze:

• Begin met php cli/joomla.php list en help - ze documenteren elke site voor je.
• Draai commando's vanuit de Joomla-root, als de webgebruiker, met de PHP-versie die bij de website past.
• Gebruik voor automatisering volledige paden en voeg --no-interaction toe zodat niets op een mens wacht.
• Trigger geplande taken met een echte cronjob die scheduler:run aanroept, niet de web-trigger.
• Bouw nieuwe commando's als een console-plugin die ze toevoegt op BEFORE_EXECUTE - bewerk nooit de core.
• Houd de handler dun, gebruik SymfonyStyle voor uitvoer, en geef een duidelijke exit-code terug.
• Houd de cli/-scripts weg van het publieke web.

17. Samenvatting

De Joomla CLI is dezelfde site die je kent, maar dan via een andere ingang. Een ingang, cli/joomla.php, start het volledige CMS op en geeft de controle aan een commando, dat tekst afdrukt en een exit-code teruggeeft. Er is geen template, geen bezoeker en geen HTTP - alleen Joomla die snel een klus doet.

De belangrijkste punten kort samengevat:

• Draai php cli/joomla.php list om elk commando op een site te zien, en help om er een te leren.
• De Joomla core levert tientallen commando's voor cache, config, gebruikers, extensies, updates, zoeken en de scheduler.
• De applicatie is gebouwd op Symfony Console en registreert commando's meteen, lui via de DI-container, en tijdens runtime via console-plugins.
• Een console-plugin woont in de groep console en voegt commando's toe op het event BEFORE_EXECUTE, zodat je de CLI uitbreidt zonder de Joomla core aan te raken.
• Een commando is een kleine klasse: een naam, een configure() voor de argumenten en opties, en een doExecute() die een exit-code teruggeeft.

Zodra je je hier op je gemak voelt, wordt veel Joomla-onderhoud een enkele betrouwbare regel: de cache legen, opnieuw indexeren, de nachtelijke taken draaien of een buitengesloten site herstellen.

Wil je hulp bij het automatiseren van je Joomla-onderhoud, het opzetten van een betrouwbare, cron-gestuurde scheduler, of het bouwen van eigen CLI-commando's en console-plugins voor je eigen workflows, dan is dat precies het soort geavanceerde Joomla-werk dat ik dagelijks doe.