Geplande taken in Joomla

1. De Basis

1.1 Wat Zijn Geplande Taken?

Met de component Geplande Taken (com_scheduler) laat je een stuk werk automatisch draaien volgens een tijdregel. Joomla introduceerde het in versie 4.1 (begin 2022), en sindsdien zit het in de kern. Het vervangt de oude manier waarop je je eigen cron-scripts schreef voor routineonderhoud van Joomla.

Een paar ideeen maken het bijzonder:

• Elke taak is een rij in een enkele tabel: #__scheduler_tasks.
• Een taak bevat geen code. Hij verwijst naar een taakroutine die een plugin levert. De plugin doet het echte werk.
• Timing is data, geen code. Je kiest een regel ("elke 6 uur", "elke nacht om 03:00", of een volledige cron-expressie) en Joomla berekent de volgende uitvoering.
• Taken kunnen draaien op basis van webverkeer, een echte servercron, de commandoregel, of een beveiligde webcron-URL. Jij kiest.

Kort gezegd: de component is de manager, de plugins zijn de werkers, en de tabel is het lijstje met klusjes.

1.2 Waar Vind Ik Het?

In de Joomla 6-beheeromgeving zijn deze plekken relevant:

Systeem → Beheren → Geplande Taken             (de takenlijst)
Systeem → Beheren → Geplande Taken → Nieuw     (een taak maken)
Systeem → Beheren → Geplande Taken → Opties    (instellingen + ACL)
Systeem → Beheren → Plugins (filter "Taak")     (de taakroutines)

De component staat in administrator/components/com_scheduler/. De taakroutines bestaan als plugins onder plugins/task/. Er is nog een onderdeel: een systeemplugin, Systeem - Schedule Runner (plg_system_schedulerunner), die bezoekers in staat stelt om openstaande taken op de achtergrond te activeren.

1.3 De Drie Onderdelen

Geplande Taken is opgebouwd uit drie delen die samenwerken:

Schakel je de taak-plugin uit, dan verdwijnt zijn routine uit de lijst "Nieuwe Taak". Schakel je de Schedule Runner uit, dan stopt het activeren via het web, hoewel een echte servercron dan nog gewoon werkt.

1.4 Een Taak Versus een Routine

Dit onderscheid zorgt bij veel mensen voor verwarring, dus zet het meteen recht:

• Een routine is een mogelijkheid die een plugin aanbiedt, herkenbaar aan een tekenreeks zoals session.gc of delete.actionlogs. Die is voor elke site hetzelfde.
• Een taak is jouw ingestelde versie van een routine: een titel, een tijdregel, wat parameters en een status. Je kunt meerdere taken van dezelfde routine maken, bijvoorbeeld twee "Maak een GET-verzoek"-taken die naar twee verschillende URL's wijzen.

Een routine is het recept. Een taak is de maaltijd die je echt hebt ingepland.

3. De Standaard Taaktypes

Joomla 6 wordt geleverd met negen taak-plugins. Samen dekken ze de meest voorkomende onderhoudsklusjes. Hier staat wat elke plugin doet en welke routine-id hij levert.

Twee daarvan verdienen een speciale vermelding. Update Notification maakt van Joomla iets dat zijn eigen versie voor je in de gaten houdt, een van de eenvoudigste beveiligingswinsten op elke site. En Requests is de brug naar de buitenwereld: plan een GET naar een webhook en je kunt alles activeren wat een externe dienst aanbiedt, van een Slack-bericht tot het opwarmen van een cache op een CDN.

5. Hoe Taken Echt Draaien

Een taak vastleggen zorgt er niet voor dat hij draait. Iets moet de Scheduler wakker maken en vragen "is er iets aan de beurt?". Joomla biedt daar vier manieren voor, en de juiste kiezen is de belangrijkste beslissing die je met deze component maakt.

5.1 De Lazy Scheduler (webverkeer)

Dit is de standaard. Wanneer Lazy Scheduler is ingeschakeld in de Opties, voegt de Schedule Runner-plugin een klein achtergrondverzoek toe aan gewone paginaweergaven. Wanneer een echte bezoeker je site opent en een taak aan de beurt is, activeert de pagina van die bezoeker stilletjes de taak via een AJAX-aanroep (onAjaxRunSchedulerLazy).

Het is handig en vereist geen serverconfiguratie, maar het heeft een zwakte: geen verkeer betekent geen runs. Een rustige site draait om 03:00 zijn nachtelijke taak niet totdat de eerste bezoeker 's ochtends arriveert. De lazy scheduler heeft ook een minimuminterval (standaard 300 seconden), zodat hij niet bij elke paginaweergave afvuurt.

5.2 Een Echte Servercron (aanbevolen)

Voor betrouwbare timing laat je het besturingssysteem het wakker maken doen. Voeg een regel toe aan de crontab van de server die de Joomla-CLI om de paar minuten aanroept:

*/5 * * * * /usr/bin/php /pad/naar/site/cli/joomla.php scheduler:run --all

Nu wordt de Scheduler elke vijf minuten gecontroleerd, ongeacht bezoekers. Dit is de professionele keuze voor elke site waar timing belangrijk is. Zie hoofdstuk 8 voor het volledige commando.

5.3 De Webcron-URL

Als je geen systeemcron kunt toevoegen maar je host (of een externe dienst zoals een monitoringtool) wel een URL volgens een planning kan ophalen, schakel dan Web Cron in de Opties in. Joomla genereert een geheime sleutel en bouwt een URL als deze:

https://example.test/index.php?option=com_ajax&plugin=RunSchedulerWebcron
       &group=system&format=json&hash=JOUW_GEHEIME_SLEUTEL

Wat die URL ook ophaalt, het activeert de openstaande taken (onAjaxRunSchedulerWebcron). Voeg &id=5 toe om alleen taak met id 5 te draaien. De hash houdt vreemden ervan af om jouw taken te activeren, dus behandel hem als een wachtwoord en deel hem nooit in het openbaar.

5.4 De Knop Testrun

Het Testrun-pictogram in de beheerlijst vuurt een enkele taak op verzoek af (onAjaxRunSchedulerTest). Het negeert de planning en is bedoeld om een taak te controleren vlak nadat je hem hebt gemaakt. Gebruik het gerust tijdens het instellen; vertrouw er niet op voor timing in productie.

5.5 Welke Moet Je Gebruiken?

Op een site die je belangrijk vindt, stel je een servercron in en schakel je de lazy scheduler uit. Dat haalt de kleine overhead weg uit de paginaweergaven van je bezoekers en geeft je timing waarop je kunt vertrouwen.

7. Je Eigen Taak-plugin Schrijven

7.1 De Vorm van een Taak-plugin

Een taak-plugin is een gewone Joomla-plugin in de groep task. Hij doet drie dingen: hij biedt zijn routines aan, hij draait ze, en hij voegt optioneel formuliervelden voor zijn parameters toe. Joomla geeft je een trait, TaskPluginTrait, die het meeste leidingwerk afhandelt.

Het hart van de plugin is een constante TASKS_MAP die elke routine-id koppelt aan een methode en een taalprefix:

protected const TASKS_MAP = [
    'mycompany.cleanup' => [
        'langConstPrefix' => 'PLG_TASK_MYCLEANUP',
        'method'          => 'doCleanup',
        'form'            => 'cleanupForm',
    ],
];

7.2 Inschrijven op de Events

De plugin schrijft zich in op de events van de Scheduler. onTaskOptionsList zorgt dat de routine in de lijst "Nieuwe Taak" verschijnt; onExecuteTask draait hem:

public static function getSubscribedEvents(): array
{
    return [
        'onTaskOptionsList'    => 'advertiseRoutines',
        'onExecuteTask'        => 'standardRoutineHandler',
        'onContentPrepareForm' => 'enhanceTaskItemForm',
    ];
}

De eerste twee handlers komen rechtstreeks uit TaskPluginTrait. Je schrijft alleen de routinemethode zelf.

7.3 De Routinemethode

Je methode ontvangt het uitvoeringsevent, doet het werk, en geeft een van de statuscodes uit hoofdstuk 6 terug:

protected function doCleanup(ExecuteTaskEvent $event): int
{
    $params = $event->getArgument('params');

    // ... doe hier het echte werk ...

    $this->logTask('Cleanup finished.');

    return Status::OK;   // 0 = succes
}

Geef Status::OK terug wanneer alles goed is, of een andere constante om een probleem te signaleren. Joomla legt de code vast, werkt de tellers bij en herberekent de volgende uitvoering. Dat is het hele contract: inschrijven, aanbieden, draaien, een code teruggeven.

7.4 De Belangrijkste Klassen

Wil je ooit een uitgewerkt voorbeeld, dan zijn de negen kern-plugins onder plugins/task/ kort, leesbaar en volgen ze precies dit patroon. sessiongc is de eenvoudigste plek om te beginnen.

7.5 Langlopend Werk: Batchverwerking met WILL_RESUME

En een klus die te groot is voor een enkele run, zoals het verkleinen van tienduizend afbeeldingen of het mailen van een nieuwsbrief naar elke abonnee? Draai je hem in een keer, dan raakt hij een PHP-geheugenlimiet of een tijdslimiet, vooral onder de lazy scheduler of een webcron, waar de trigger binnen een gewoon webverzoek leeft.

Joomla lost dit op met een speciale exitcode, Status::WILL_RESUME (123). Het idee is eenvoudig: doe een kleine batch per run, en vertel Joomla dan dat je nog niet klaar bent.

• Verwerk een behapbaar stuk (zeg 100 records) en geef dan Status::WILL_RESUME terug.
• Joomla logt de run als geslaagd en laat de taak openstaan, zodat de volgende trigger je routine opnieuw aanroept voor de volgende batch.
• Wanneer de laatste batch klaar is, geef je Status::OK terug en valt de taak terug op zijn normale planning.

De vorm van een hervatbare routine ziet er zo uit:

protected function doImport(ExecuteTaskEvent $event): int
{
    $offset = (int) $this->getProgress();   // waar de vorige batch stopte

    $batch = $this->fetchRecords($offset, 100);

    foreach ($batch as $record) {
        $this->processOne($record);
    }

    if (\count($batch) < 100) {
        $this->clearProgress();
        return Status::OK;            // laatste batch, we zijn klaar
    }

    $this->saveProgress($offset + 100);
    return Status::WILL_RESUME;       // nog meer te doen, draai me opnieuw
}

Een ding doet het framework niet voor je: het onthoudt niet waar je was. Elke run is een nieuwe aanroep, dus je routine moet zijn eigen voortgang bewaren (een cursor, een offset, of de id's die al verwerkt zijn) tussen batches. Bewaar die ergens duurzaam, zoals in de taakparameters of je eigen tabel, en lees die aan het begin van de volgende run terug.

Houd elke batch ruim binnen de globale timeout uit hoofdstuk 6.2, en houd het werk idempotent zodat een batch die twee keer draait (na een crash, bijvoorbeeld) geen kwaad doet. Geen van de negen kern-taak-plugins heeft dit patroon nodig, maar het is precies hoe je een serieuze import-, export- of bulkmail-taak bovenop de Scheduler bouwt.

9. Web Services en Headless

Een veelgestelde vraag: heeft de Scheduler een REST-API onder /api, zoals artikelen of contacten dat hebben? In Joomla 6 is het antwoord nee. De component registreert geen Web Services-route, dus er is geen eindpunt v1/scheduler/tasks om taken via REST aan te maken of op te vragen.

Wat hij in plaats daarvan biedt is het webcron-eindpunt, dat een activeringsmechanisme is in plaats van een data-API. Het draait openstaande taken maar laat je geen taakdefinities lezen of bewerken:

curl "https://example.test/index.php?option=com_ajax&plugin=RunSchedulerWebcron&group=system&format=json&hash=<sleutel>"

Behandel de Scheduler voor de rest als een server-side hulpmiddel. Moet je taken programmatisch beheren, gebruik dan de PHP-klassen Scheduler en Task uit hoofdstuk 7 binnen je eigen code, of stuur de CLI-commando's aan vanuit een deployment-script. Voor het op afstand activeren op een timer richt je een externe monitoringdienst op de webcron-URL.

11. Veelgemaakte Fouten en Valkuilen

11.1 "Mijn nachtelijke taak draait nooit"

Symptoom: een taak die voor 03:00 is gepland draait pas uren later, of helemaal niet.

Oplossing: je leunt op de lazy scheduler op een site met weinig verkeer. Geen bezoeker om 03:00 betekent geen trigger. Stel een echte servercron in (hoofdstuk 8) zodat timing niet meer afhangt van verkeer.

11.2 "Laatste exitcode is 127"

Symptoom: de taak mislukt meteen met exitcode 127.

Oplossing: NO_ROUTINE betekent dat Joomla de plugin die de routine levert niet kan vinden. De taak-plugin is waarschijnlijk uitgeschakeld of verwijderd. Schakel hem weer in onder Systeem → Plugins, gefilterd op de groep Taak.

11.3 "Dezelfde taak draaide twee keer"

Symptoom: een klus lijkt twee keer kort na elkaar uitgevoerd te worden.

Oplossing: meestal vuurden twee triggers af voordat de vergrendeling was geschreven, of een servercron en de lazy scheduler zijn allebei actief. Kies een triggermethode en schakel de lazy scheduler uit wanneer je een servercron gebruikt.

11.4 "Een taak is vastgelopen en draait niet meer"

Symptoom: een taak blijft eindeloos als draaiend staan en vuurt nooit meer af.

Oplossing: de run crashte en liet de kolom locked gevuld achter. Wacht tot de timeout (standaard 300 seconden) verloopt en Joomla wist de verlopen vergrendeling zelf. Herstelt hij nooit, verlaag dan de timeout of ontgrendel de taak via de werkbalk van de lijst.

11.5 "Ik deelde mijn webcron-URL en taken vuren willekeurig af"

Symptoom: taken draaien op vreemde tijden nadat de webcron-URL is uitgelekt.

Oplossing: de hash in de URL is een geheim. Genereer de sleutel opnieuw in de Opties om de oude URL ongeldig te maken, en houd de nieuwe geheim.

11.6 "De site ging vanzelf offline"

Symptoom: de site staat onverwacht in de offline-modus.

Oplossing: controleer op een Site Status-taak. Zijn hele taak is de site online of offline te schakelen, en een verkeerd ingestelde planning doet precies dat. Schakel de taak uit of herplan hem.

13. In het kort

COMPONENT      Systeem → Beheren → Geplande Taken
NIEUWE TAAK    Geplande Taken → Nieuw (kies een routine)
OPTIES         Geplande Taken → Opties (timeout, lazy, webcron)
TAAK-PLUGINS   Systeem → Plugins (filter "Taak")
RUNNER-PLUGIN  Systeem - Schedule Runner (plg_system_schedulerunner)
HOOFDTABEL     #__scheduler_tasks
LOGS-TABEL     #__scheduler_logs (runhistorie; Logs wissen om te legen)
LOGS-WEERGAVE  Geplande Taken → Logs (filter op exitcode)
REGELTYPES     interval-minutes/-hours/-days/-months, cron-expression, manual
TRIGGERS       lazy scheduler, servercron, webcron-URL, Testrun
CLI RUN        php cli/joomla.php scheduler:run --all
CLI EEN        php cli/joomla.php scheduler:run --id N
CLI LIJST      php cli/joomla.php scheduler:list
WEBCRON-URL    index.php?option=com_ajax&plugin=RunSchedulerWebcron
               &group=system&format=json&hash=SLEUTEL
EXIT 0         OK (succes)
EXIT 124       TIMEOUT          EXIT 127  NO_ROUTINE (plugin ontbreekt)
STATE          1 ingeschakeld, 0 uitgeschakeld, -2 prullenbak
LOCK           tijdstempel "locked"; gewist na timeout (standaard 300s)
SINDS          Joomla 4.1 (2022)