Scheduled Task Plugins in Joomla

plg_task_tallpine_trailsync/
  tallpine_trailsync.xml
  services/
    provider.php
  src/
    Extension/
      TallpineTrailsync.php
  forms/
    syncForm.xml
  language/
    en-GB/
      plg_task_tallpine_trailsync.ini
      plg_task_tallpine_trailsync.sys.ini
    de-DE/
      plg_task_tallpine_trailsync.ini
      plg_task_tallpine_trailsync.sys.ini

<?xml version="1.0" encoding="UTF-8"?>
<extension type="plugin" group="task" method="upgrade">
    <name>plg_task_tallpine_trailsync</name>
    <author>Tallpine Hiking Club</author>
    <creationDate>2026-10</creationDate>
    <copyright>(C) 2026 Tallpine Hiking Club</copyright>
    <license>GNU General Public License version 2 or later</license>
    <authorEmail>web@tallpine.example</authorEmail>
    <authorUrl>https://www.tallpine.example</authorUrl>
    <version>1.0.0</version>
    <description>PLG_TASK_TALLPINE_TRAILSYNC_XML_DESCRIPTION</description>
    <namespace path="src">Tallpine\Plugin\Task\TallpineTrailsync</namespace>
    <files>
        <folder plugin="tallpine_trailsync">services</folder>
        <folder>src</folder>
        <folder>forms</folder>
        <folder>language</folder>
    </files>
    <languages>
        <language tag="en-GB">language/en-GB/plg_task_tallpine_trailsync.ini</language>
        <language tag="en-GB">language/en-GB/plg_task_tallpine_trailsync.sys.ini</language>
        <language tag="de-DE">language/de-DE/plg_task_tallpine_trailsync.ini</language>
        <language tag="de-DE">language/de-DE/plg_task_tallpine_trailsync.sys.ini</language>
    </languages>
</extension>

<?php

/**
 * @package     Tallpine.Plugin
 * @subpackage  Task.tallpine_trailsync
 */

\defined('_JEXEC') or die;

use Joomla\CMS\Extension\PluginInterface;
use Joomla\CMS\Factory;
use Joomla\CMS\Plugin\PluginHelper;
use Joomla\Database\DatabaseInterface;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use Joomla\Http\HttpFactory;
use Tallpine\Plugin\Task\TallpineTrailsync\Extension\TallpineTrailsync;

return new class () implements ServiceProviderInterface {
    public function register(Container $container): void
    {
        $container->set(
            PluginInterface::class,
            $container->lazy(TallpineTrailsync::class, function (Container $container) {
                $plugin = new TallpineTrailsync(
                    (array) PluginHelper::getPlugin('task', 'tallpine_trailsync'),
                    new HttpFactory()
                );
                $plugin->setApplication(Factory::getApplication());
                $plugin->setDatabase($container->get(DatabaseInterface::class));

                return $plugin;
            })
        );
    }
};

<?php

namespace Tallpine\Plugin\Task\TallpineTrailsync\Extension;

use Joomla\CMS\Date\Date;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Component\Scheduler\Administrator\Event\ExecuteTaskEvent;
use Joomla\Component\Scheduler\Administrator\Task\Status;
use Joomla\Component\Scheduler\Administrator\Traits\TaskPluginTrait;
use Joomla\Database\DatabaseAwareTrait;
use Joomla\Database\ParameterType;
use Joomla\Event\SubscriberInterface;
use Joomla\Http\HttpFactory;

\defined('_JEXEC') or die;

final class TallpineTrailsync extends CMSPlugin implements SubscriberInterface
{
    use DatabaseAwareTrait;
    use TaskPluginTrait;

    private const TASKS_MAP = [
        'tallpine.trailsync' => [
            'langConstPrefix' => 'PLG_TASK_TALLPINE_TRAILSYNC_SYNC',
            'method'          => 'syncClosures',
            'form'            => 'syncForm',
        ],
    ];

    protected $autoloadLanguage = true;

    public function __construct(array $config, private readonly HttpFactory $httpFactory)
    {
        parent::__construct($config);
    }

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

    /**
     * Routine tallpine.trailsync: pull trail closures changed since the last sync.
     */
    private function syncClosures(ExecuteTaskEvent $event): int
    {
        $params   = $event->getArgument('params');
        $endpoint = (string) ($params->endpoint ?? '');
        $timeout  = max(1, (int) ($params->timeout ?? 30));
        $limit    = max(1, (int) ($params->batch ?? 100));
        $token    = (string) getenv('TALLPINE_PARK_API_TOKEN');

        if ($token === '' || !str_starts_with($endpoint, 'https://')) {
            $this->logTask('The endpoint must use https and TALLPINE_PARK_API_TOKEN must be set.', 'error');

            return Status::KNOCKOUT;
        }

        $db = $this->getDatabase();

        // The newest closure already stored is the cursor: the sync is stateless and idempotent.
        $since = $db->setQuery(
            $db->createQuery()
                ->select('MAX(' . $db->quoteName('closure_synced') . ')')
                ->from($db->quoteName('#__tallpine_trails'))
        )->loadResult() ?: '1970-01-01 00:00:00';

        $url = $endpoint . '?' . http_build_query(['updated_since' => $since, 'limit' => $limit]);

        try {
            $response = $this->httpFactory->getHttp()->get(
                $url,
                ['Authorization' => 'Bearer ' . $token, 'Accept' => 'application/json'],
                $timeout
            );
        } catch (\Throwable $e) {
            $this->logTask('Park API request failed: ' . $e->getMessage(), 'error');

            return Status::TIMEOUT;
        }

        if ($response->getStatusCode() !== 200) {
            $this->logTask('Park API answered HTTP ' . $response->getStatusCode(), 'error');

            return Status::KNOCKOUT;
        }

        try {
            $closures = json_decode((string) $response->getBody(), true, 8, JSON_THROW_ON_ERROR)['closures'] ?? [];
        } catch (\JsonException) {
            $this->logTask('The park API did not return valid JSON.', 'error');

            return Status::KNOCKOUT;
        }

        $parkRef = '';
        $closed  = 0;
        $note    = '';
        $synced  = '';

        $query = $db->createQuery()
            ->update($db->quoteName('#__tallpine_trails'))
            ->set($db->quoteName('closed') . ' = :closed')
            ->set($db->quoteName('closure_note') . ' = :note')
            ->set($db->quoteName('closure_synced') . ' = :synced')
            ->where($db->quoteName('park_ref') . ' = :ref')
            ->bind(':closed', $closed, ParameterType::INTEGER)
            ->bind(':note', $note)
            ->bind(':synced', $synced)
            ->bind(':ref', $parkRef);

        $db->setQuery($query);
        $count = 0;

        foreach ($closures as $closure) {
            $parkRef = (string) ($closure['ref'] ?? '');

            if ($parkRef === '') {
                continue;
            }

            $closed = empty($closure['closed']) ? 0 : 1;
            $note   = mb_substr((string) ($closure['note'] ?? ''), 0, 255);
            $synced = (new Date((string) ($closure['updated_at'] ?? 'now')))->toSql();

            $db->execute();
            $count++;
        }

        $this->logTask(\sprintf('%d trail closures synchronised.', $count));
        $this->snapshot['output'] = \sprintf('Synchronised %d closures since %s', $count, $since);

        // A full batch means more may be waiting: ask the scheduler to run this task again soon.
        return $count >= $limit ? Status::WILL_RESUME : Status::OK;
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<form>
    <fields name="params">
        <fieldset name="task_params">
            <field
                name="endpoint"
                type="url"
                label="PLG_TASK_TALLPINE_TRAILSYNC_LABEL_ENDPOINT"
                description="PLG_TASK_TALLPINE_TRAILSYNC_DESC_ENDPOINT"
                required="true"
                validate="url"
                filter="url"
                schemes="https"
                hint="https://api.park-authority.example/v1/closures"
            />
            <field
                name="timeout"
                type="number"
                label="PLG_TASK_TALLPINE_TRAILSYNC_LABEL_TIMEOUT"
                default="30"
                min="1"
                max="120"
                step="1"
                filter="int"
                validate="number"
            />
            <field
                name="batch"
                type="number"
                label="PLG_TASK_TALLPINE_TRAILSYNC_LABEL_BATCH"
                default="100"
                min="10"
                max="500"
                step="10"
                filter="int"
                validate="number"
            />
        </fieldset>
    </fields>
</form>

; plg_task_tallpine_trailsync.ini
PLG_TASK_TALLPINE_TRAILSYNC_SYNC_TITLE="Synchronise trail closures"
PLG_TASK_TALLPINE_TRAILSYNC_SYNC_DESC="Pulls trail closures changed since the last run from the park authority and updates the trail list."
PLG_TASK_TALLPINE_TRAILSYNC_LABEL_ENDPOINT="API endpoint"
PLG_TASK_TALLPINE_TRAILSYNC_DESC_ENDPOINT="HTTPS address of the closures feed. The access token is read from the server environment."
PLG_TASK_TALLPINE_TRAILSYNC_LABEL_TIMEOUT="Request timeout (seconds)"
PLG_TASK_TALLPINE_TRAILSYNC_LABEL_BATCH="Closures per run"

; plg_task_tallpine_trailsync.sys.ini
PLG_TASK_TALLPINE_TRAILSYNC="Task - Tallpine trail closures"
PLG_TASK_TALLPINE_TRAILSYNC_XML_DESCRIPTION="Scheduled routine that synchronises trail closures from the park authority."

cd /var/www/html
php cli/joomla.php scheduler:list
php cli/joomla.php scheduler:run --id=7
tail -n 20 administrator/logs/joomla_scheduler.php

services:
  joomla:
    image: joomla:6.2-php8.3-apache
    environment:
      JOOMLA_DB_HOST: db
      JOOMLA_DB_USER: tallpine
      JOOMLA_DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
      JOOMLA_DB_NAME: tallpine
      TALLPINE_PARK_API_TOKEN: ${TALLPINE_PARK_API_TOKEN:-CHANGE_ME}
    volumes:
      - ./site:/var/www/html
    depends_on: [db]
  scheduler:
    image: joomla:6.2-php8.3-apache
    entrypoint: ["sh", "-c", "while true; do php /var/www/html/cli/joomla.php scheduler:run --all; sleep 60; done"]
    environment:
      JOOMLA_DB_HOST: db
      TALLPINE_PARK_API_TOKEN: ${TALLPINE_PARK_API_TOKEN:-CHANGE_ME}
    volumes:
      - ./site:/var/www/html
    depends_on: [db]
  db:
    image: mariadb:11.4
    environment:
      MARIADB_DATABASE: tallpine
      MARIADB_USER: tallpine
      MARIADB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
      MARIADB_RANDOM_ROOT_PASSWORD: "1"