Cron jobs and CLI commands

Run scheduled work from a FeatherPanel plugin with Cron classes and the Cron helper, and add your own commands to the panel CLI with CommandBuilder.

Cron jobs

How the runner calls your class

The PHP cron runner, backend/storage/cron/runner.php, starts once a minute (see Cron and workers for how it is scheduled). On each run it:

1. runs the core jobs in storage/cron/php/,
2. for every folder in storage/addons/, loads each Cron/*.php file and instantiates the class App\Addons\<folder>\Cron\<file name>,
3. calls run() on it.

Things to know:

• The runner does not check whether the plugin is valid or loaded. Any folder with a Cron/ directory is run.
• If the class name does not match, the output shows Class App\Addons\... not found and the file is skipped.
• The runner catches Exception only. A PHP Error, such as a TypeError or a call to an undefined method, stops the whole run, so jobs after yours do not run that minute.
• Output goes to the cron log, /var/log/cron.log inside the Docker backend container.
• php cli cron runs the core jobs only. To test a plugin job, run the runner itself from the backend folder: php storage/cron/runner.php.

A cron class

Implement App\Cron\TimeTask and use App\Cron\Cron to decide whether the work is due:

<?php

namespace App\Addons\myplugin\Cron;

use App\App;
use App\Chat\TimedTask;
use App\Cron\Cron;
use App\Cron\TimeTask;

class Cleanup implements TimeTask
{
    public function run()
    {
        $cron = new Cron('myplugin-cleanup', '1H');

        try {
            $cron->runIfDue(function (): void {
                // Delete old rows, call an API, send a report...
                TimedTask::markRun('myplugin-cleanup', true, 'cleanup finished');
            });
        } catch (\Throwable $e) {
            App::getInstance(false, true)->getLogger()->error('myplugin cleanup failed: ' . $e->getMessage());
            TimedTask::markRun('myplugin-cleanup', false, $e->getMessage());
        }
    }
}

The file is Cron/Cleanup.php. The namespace must be App\Addons\<identifier>\Cron and the class name must equal the file name.

The Cron helper

new Cron(string $identifier, string $interval):

Delete the .fptj file to make the job run on the next minute.

App\Chat\TimedTask::markRun(string $name, bool $success, ?string $message) records the result in the panel’s timed task table, the same way the core jobs do. It is optional.

CLI commands

How commands are found

The panel CLI is the file backend/cli, run as php cli <command> from the backend folder. The installer also adds a featherpanel command that runs php cli inside the Docker backend container. See Panel CLI.

When you run a command, the CLI first looks for a plugin command:

1. On v1.5.2 and earlier it scans <current directory>/backend/storage/addons/*/Commands/*.php. From v1.5.3 (PR #365) it scans the panel’s addons directory (APP_ADDONS_DIR, backend/storage/addons) wherever you run it from, and still checks the old location as a fallback.
2. For each file it loads the class App\Addons\<folder>\Commands\<file name>.
3. The first class whose name matches the command, ignoring case, runs. Plugin commands are checked before built-in ones, so a plugin command named migrate would replace the core command. Pick a name that cannot clash.

help lists plugin commands under Plugins: using the same lookup.

The CLI only runs from /var/www/featherpanel, /var/www/featherpanel/backend or /var/www/html unless you pass --skip-path-check. On v1.5.2 and earlier, because of the <current directory>/backend/storage/addons lookup, plugin commands are only found when the current directory is the repository root:

cd /var/www/featherpanel
php backend/cli myplugincleanup

In the Docker image the working directory is /var/www/html, which is the backend folder itself, so on v1.5.2 and earlier php cli and the featherpanel wrapper do not find plugin commands there. Use a cron job or an admin route for work that has to run in every setup. Discovery from any directory, including Docker, is fixed in v1.5.3 (PR #365).

A command class

<?php

namespace App\Addons\myplugin\Commands;

use App\Cli\App;
use App\Cli\CommandBuilder;

class MyPluginCleanup implements CommandBuilder
{
    public static function execute(array $args): void
    {
        $cli = App::getInstance();
        $cli->send('&aCleanup started');

        // $args[0] is the command name itself; your arguments start at $args[1].
        $days = (int) ($args[1] ?? 30);
        $cli->send('&7Removing entries older than &f' . $days . ' &7days');
    }

    public static function getDescription(): string
    {
        return 'Remove old MyPlugin entries';
    }

    public static function getSubCommands(): array
    {
        return [];
    }
}

The file is Commands/MyPluginCleanup.php and the command is myplugincleanup. The Create file tool names the class <Name>Command, which makes the command <name>command.

Notes:

• send() understands & colour codes such as &a (green), &c (red), &7 (grey) and &f (white). The global flags --no-colors, --clean-output and --no-prefix are removed from $args before your command runs.
• The CLI does not boot the HTTP app or connect to the database for you. The built-in settings command loads the environment with \App\App::getInstance(true)->loadEnv() and opens a connection with new \App\Chat\Database(...) from the DATABASE_* values; do the same if your command needs the database.

Related

• Cron and workers
• Panel CLI
• Migrations and storage
• Debugging plugins