Console Command Plugins in Joomla

plg_console_tallpine/
  tallpine.xml
  services/
    provider.php
  src/
    Extension/
      Tallpine.php
    Command/
      ImportTrailsCommand.php
      TrailStatsCommand.php
    Gpx/
      GpxReader.php
  language/
    en-GB/
      plg_console_tallpine.ini
      plg_console_tallpine.sys.ini

<?xml version="1.0" encoding="UTF-8"?>
<extension type="plugin" group="console" method="upgrade">
    <name>plg_console_tallpine</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; see LICENSE.txt</license>
    <version>1.1.0</version>
    <description>PLG_CONSOLE_TALLPINE_XML_DESCRIPTION</description>
    <namespace path="src">Tallpine\Plugin\Console\Tallpine</namespace>
    <files>
        <folder plugin="tallpine">services</folder>
        <folder>src</folder>
    </files>
    <languages>
        <language tag="en-GB">language/en-GB/plg_console_tallpine.ini</language>
        <language tag="en-GB">language/en-GB/plg_console_tallpine.sys.ini</language>
    </languages>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field
                    name="default_category"
                    type="category"
                    extension="com_tallpine"
                    label="PLG_CONSOLE_TALLPINE_FIELD_CATEGORY_LABEL"
                    default=""
                    filter="integer"
                />
                <field
                    name="max_file_kb"
                    type="number"
                    label="PLG_CONSOLE_TALLPINE_FIELD_MAXFILE_LABEL"
                    default="2048"
                    min="64"
                    max="20480"
                    filter="integer"
                />
            </fieldset>
        </fields>
    </config>
</extension>

<?php

/**
 * @package     Tallpine.Plugin
 * @subpackage  Console.Tallpine
 *
 * @copyright   (C) 2026 Tallpine Hiking Club
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

\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 Tallpine\Plugin\Console\Tallpine\Extension\Tallpine;

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

                return $plugin;
            }
        );
    }
};

<?php

namespace Tallpine\Plugin\Console\Tallpine\Extension;

use Joomla\Application\ApplicationEvents;
use Joomla\CMS\Application\ConsoleApplication;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Console\Event\BeforeCommandExecuteEvent;
use Joomla\Console\ConsoleEvents;
use Joomla\Database\DatabaseAwareInterface;
use Joomla\Database\DatabaseAwareTrait;
use Joomla\Event\SubscriberInterface;
use Tallpine\Plugin\Console\Tallpine\Command\ImportTrailsCommand;
use Tallpine\Plugin\Console\Tallpine\Command\TrailStatsCommand;

\defined('_JEXEC') or die;

final class Tallpine extends CMSPlugin implements SubscriberInterface, DatabaseAwareInterface
{
    use DatabaseAwareTrait;

    public static function getSubscribedEvents(): array
    {
        return [
            ApplicationEvents::BEFORE_EXECUTE     => 'registerCommands',
            ConsoleEvents::BEFORE_COMMAND_EXECUTE => 'guardImport',
        ];
    }

    public function registerCommands(): void
    {
        $app = $this->getApplication();

        if (!$app instanceof ConsoleApplication) {
            return;
        }

        $app->addCommand(
            new ImportTrailsCommand(
                (int) $this->params->get('default_category', 0),
                (int) $this->params->get('max_file_kb', 2048) * 1024
            )
        );
        $app->addCommand(new TrailStatsCommand($this->getDatabase()));
    }

    public function guardImport(BeforeCommandExecuteEvent $event): void
    {
        $command = $event->getCommand();

        if ($command === null || $command->getName() !== 'tallpine:import') {
            return;
        }

        if (getenv('TALLPINE_ENV') === 'production' && getenv('TALLPINE_ALLOW_IMPORT') !== '1') {
            $event->disableCommand();
        }
    }
}

use Symfony\Component\Console\Command\Command;

return Command::SUCCESS;   // 0
return Command::FAILURE;   // 1
return Command::INVALID;   // 2, for bad arguments or options

<?php

namespace Tallpine\Plugin\Console\Tallpine\Command;

use Joomla\CMS\Application\ApplicationHelper;
use Joomla\CMS\Application\ConsoleApplication;
use Joomla\CMS\Date\Date;
use Joomla\CMS\MVC\Factory\MVCFactoryServiceInterface;
use Joomla\Console\Command\AbstractCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;
use Tallpine\Plugin\Console\Tallpine\Gpx\GpxReader;

\defined('_JEXEC') or die;

final class ImportTrailsCommand extends AbstractCommand
{
    protected static $defaultName = 'tallpine:import';

    public function __construct(
        private readonly int $defaultCategory = 0,
        private readonly int $maxFileBytes = 2097152
    ) {
        parent::__construct();
    }

    protected function configure(): void
    {
        $this->setDescription('Import trails from a folder of GPX files');
        $this->setHelp(
            "<info>%command.name%</info> creates one trail per GPX file.\n\n"
            . "Usage: <info>php %command.full_name% --folder=/srv/gpx</info>\n"
            . "Check first with <info>--dry-run</info>. Existing trails are only changed with <info>--update</info>."
        );
        $this->addOption('folder', 'f', InputOption::VALUE_REQUIRED, 'Folder that contains the .gpx files');
        $this->addOption('category', 'c', InputOption::VALUE_REQUIRED, 'Category id for new trails', null);
        $this->addOption('state', null, InputOption::VALUE_REQUIRED, 'State of new trails: 0 unpublished, 1 published', '0');
        $this->addOption('limit', 'l', InputOption::VALUE_REQUIRED, 'Import at most this many files', '200');
        $this->addOption('update', null, InputOption::VALUE_NONE, 'Update trails whose alias already exists');
        $this->addOption('dry-run', null, InputOption::VALUE_NONE, 'Parse and report, write nothing');
    }

    protected function doExecute(InputInterface $input, OutputInterface $output): int
    {
        $io     = new SymfonyStyle($input, $output);
        $app    = $this->getApplication();
        $folder = (string) $input->getOption('folder');
        $limit  = (int) $input->getOption('limit');
        $state  = (int) $input->getOption('state');
        $catid  = (int) ($input->getOption('category') ?? $this->defaultCategory);
        $dryRun = (bool) $input->getOption('dry-run');
        $update = (bool) $input->getOption('update');

        // 1. Validate usage before touching anything.
        if ($folder === '' || !is_dir($folder) || !is_readable($folder)) {
            $io->error('Pass a readable folder with --folder.');

            return Command::INVALID;
        }

        if (!\in_array($state, [0, 1], true) || $limit < 1 || $catid < 1) {
            $io->error('Check --state (0 or 1), --limit (1 or more) and --category (a category id).');

            return Command::INVALID;
        }

        if (!$app instanceof ConsoleApplication) {
            $io->error('This command needs the Joomla console application.');

            return Command::FAILURE;
        }

        // 2. Ask the component for its table class.
        $component = $app->bootComponent('com_tallpine');

        if (!$component instanceof MVCFactoryServiceInterface) {
            $io->error('com_tallpine is not installed or is not an MVC component.');

            return Command::FAILURE;
        }

        $factory = $component->getMVCFactory();
        $files   = glob(rtrim($folder, '/') . '/*.gpx') ?: [];
        sort($files);
        $files   = \array_slice($files, 0, $limit);

        if ($files === []) {
            $io->warning('No .gpx files found.');

            return Command::SUCCESS;
        }

        if ($update && !$dryRun && $input->isInteractive()
            && !$io->confirm('Existing trails with the same alias will be overwritten. Continue?', false)) {
            $io->note('Nothing was changed.');

            return Command::SUCCESS;
        }

        // 3. Work file by file; one bad file must not stop the others.
        $reader = new GpxReader($this->maxFileBytes);
        $rows   = [];
        $failed = 0;
        $io->progressStart(\count($files));

        foreach ($files as $path) {
            $name = basename($path);

            try {
                $trail = $reader->read($path);
                $alias = ApplicationHelper::stringURLSafe($trail['title']);
                $table = $factory->createTable('Trail', 'Administrator');

                $exists = $table->load(['alias' => $alias, 'catid' => $catid]);

                if ($exists && !$update) {
                    $rows[] = [$name, $alias, 'skipped (exists)'];
                    $io->progressAdvance();
                    continue;
                }

                if (!$exists) {
                    $table->reset();
                }

                $table->bind([
                    'title'       => $trail['title'],
                    'alias'       => $alias,
                    'catid'       => $catid,
                    'distance_km' => $trail['distance_km'],
                    'difficulty'  => $trail['difficulty'],
                    'description' => $trail['description'],
                    'state'       => $state,
                    'access'      => 1,
                ]);

                if (!$exists) {
                    $table->created = (new Date())->toSql();
                }

                if (!$dryRun) {
                    $table->check();
                    $table->store();
                }

                $rows[] = [$name, $alias, ($exists ? 'updated' : 'created') . ($dryRun ? ' (dry run)' : '')];
            } catch (\Throwable $e) {
                $failed++;
                $rows[] = [$name, '-', 'FAILED: ' . $e->getMessage()];
            }

            $io->progressAdvance();
        }

        $io->progressFinish();

        // 4. Report, then choose the exit code.
        if (!$io->isQuiet()) {
            $io->table(['File', 'Alias', 'Result'], $rows);
        }

        if ($failed > 0) {
            $io->error(\sprintf('%d of %d files failed.', $failed, \count($files)));

            return Command::FAILURE;
        }

        $io->success(\sprintf('%d files processed%s.', \count($files), $dryRun ? ' (dry run)' : ''));

        return Command::SUCCESS;
    }
}

<?php

namespace Tallpine\Plugin\Console\Tallpine\Gpx;

\defined('_JEXEC') or die;

final class GpxReader
{
    private const NS = 'http://www.topografix.com/GPX/1/1';

    public function __construct(private readonly int $maxBytes)
    {
    }

    /**
     * @return array{title: string, distance_km: float, difficulty: string, description: string}
     */
    public function read(string $path): array
    {
        $size = filesize($path);

        if ($size === false || $size < 1 || $size > $this->maxBytes) {
            throw new \RuntimeException('File is empty or larger than the configured limit');
        }

        $contents = file_get_contents($path);

        // A GPX file has no reason to declare entities. Refuse them instead of parsing them.
        if ($contents === false || stripos($contents, '<!DOCTYPE') !== false || stripos($contents, '<!ENTITY') !== false) {
            throw new \RuntimeException('File is unreadable or contains a DOCTYPE');
        }

        $previous = libxml_use_internal_errors(true);

        try {
            $xml = new \SimpleXMLElement($contents, LIBXML_NONET | LIBXML_NOCDATA);
        } catch (\Exception $e) {
            throw new \RuntimeException('Not valid XML');
        } finally {
            libxml_clear_errors();
            libxml_use_internal_errors($previous);
        }

        $xml->registerXPathNamespace('g', self::NS);

        $names = $xml->xpath('//g:trk/g:name') ?: $xml->xpath('//g:metadata/g:name') ?: [];
        $title = trim((string) ($names[0] ?? ''));

        if ($title === '') {
            $title = pathinfo($path, PATHINFO_FILENAME);
        }

        $points = [];

        foreach ($xml->xpath('//g:trk//g:trkpt') ?: [] as $point) {
            $points[] = [(float) $point['lat'], (float) $point['lon']];
        }

        if (\count($points) < 2) {
            throw new \RuntimeException('Fewer than two track points');
        }

        $km = round($this->length($points), 1);

        return [
            'title'       => mb_substr($title, 0, 255),
            'distance_km' => $km,
            'difficulty'  => $km < 8 ? 'easy' : ($km < 16 ? 'moderate' : 'hard'),
            'description' => '',
        ];
    }

    /** Haversine length of the polyline, in kilometres. */
    private function length(array $points): float
    {
        $total = 0.0;

        for ($i = 1, $n = \count($points); $i < $n; $i++) {
            [$lat1, $lon1] = $points[$i - 1];
            [$lat2, $lon2] = $points[$i];
            $dLat = deg2rad($lat2 - $lat1);
            $dLon = deg2rad($lon2 - $lon1);
            $a    = sin($dLat / 2) ** 2 + cos(deg2rad($lat1)) * cos(deg2rad($lat2)) * sin($dLon / 2) ** 2;
            $total += 6371.0 * 2 * asin(min(1.0, sqrt($a)));
        }

        return $total;
    }
}

<?php

namespace Tallpine\Plugin\Console\Tallpine\Command;

use Joomla\Console\Command\AbstractCommand;
use Joomla\Database\DatabaseInterface;
use Joomla\Database\ParameterType;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;

\defined('_JEXEC') or die;

final class TrailStatsCommand extends AbstractCommand
{
    protected static $defaultName = 'tallpine:stats';

    public function __construct(private readonly DatabaseInterface $db)
    {
        parent::__construct();
    }

    protected function configure(): void
    {
        $this->setDescription('Count trails by difficulty');
        $this->addOption('state', null, InputOption::VALUE_REQUIRED, 'Only trails in this state', '1');
    }

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

        $query = $this->db->createQuery()
            ->select([$this->db->quoteName('difficulty'), 'COUNT(*) AS ' . $this->db->quoteName('total')])
            ->from($this->db->quoteName('#__tallpine_trails'))
            ->where($this->db->quoteName('state') . ' = :state')
            ->bind(':state', $state, ParameterType::INTEGER)
            ->group($this->db->quoteName('difficulty'));

        $rows = $this->db->setQuery($query)->loadAssocList();

        $io->table(['Difficulty', 'Trails'], array_map(static fn ($r) => [$r['difficulty'], $r['total']], $rows));

        return Command::SUCCESS;
    }
}

# /etc/cron.d/tallpine-import  (runs as the web user)
SHELL=/bin/bash
PATH=/usr/local/bin:/usr/bin:/bin
MAILTO=webmaster@tallpine.example

# Every night at 03:10, skip the run if the previous one is still active
10 3 * * * www-data flock -n /run/lock/tallpine-import.lock /usr/local/bin/php /var/www/tallpine/cli/joomla.php -q -n --live-site=https://www.tallpine.example tallpine:import --folder=/srv/gpx/incoming --category=12 --state=0 || echo "tallpine:import exited with $?"

<?php

namespace Tallpine\Tests\Unit\Command;

use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;
use Symfony\Component\Console\Input\ArrayInput;
use Symfony\Component\Console\Output\BufferedOutput;
use Tallpine\Plugin\Console\Tallpine\Command\ImportTrailsCommand;

final class ImportTrailsCommandTest extends TestCase
{
    #[Test]
    public function aMissingFolderIsInvalidUsage(): void
    {
        $command = new ImportTrailsCommand(12);
        $output  = new BufferedOutput();

        $exit = $command->execute(
            new ArrayInput(['--folder' => '/does/not/exist', '--category' => '12']),
            $output
        );

        $this->assertSame(2, $exit);
        $this->assertStringContainsString('readable folder', $output->fetch());
    }
}