/mwstake-mediawiki-component-runjobstrigger

Primary LanguagePHP

MediaWiki Stakeholders Group - Components

RunJobsTrigger for MediaWiki

Provides an infrastructure to execute background tasks based on MediaWiki's maintenance/runJobs.php.

This code is meant to be used within the MediaWiki framework. Do not attempt to use it outside of MediaWiki.

Prerequisites

MediaWiki's maintenance/runJobs.php script must be run periodically by a serverside process (e.g. in a cronjob on Linux or Scheduled Task on Windows).

The frequency of that job determines the minimum frequency at which handlers can be invoked. It is recommended to invoke maintenance/runJobs.php every 15 minutes at a minimum.

Use in a MediaWiki extension

Add "mwstake/mediawiki-component-runjobstrigger": "~1.0" to the require section of your composer.json file.

Implement a handler

Create a class that implements MWStake\MediaWiki\Component\RunJobsTrigger\IHandler. For convenience, you may want to implement a subclass of the abstract base class MWStake\MediaWiki\Component\RunJobsTrigger\HandlerBase

In the getInterval method you can return any object that implements MWStake\MediaWiki\Component\RunJobsTrigger\Interval. There are a few predefined intevals available:

  • MWStake\MediaWiki\Component\RunJobsTrigger\Interval\OnceADay
  • MWStake\MediaWiki\Component\RunJobsTrigger\Interval\OnceAWeek
  • MWStake\MediaWiki\Component\RunJobsTrigger\Interval\OnceEveryHour
  • MWStake\MediaWiki\Component\RunJobsTrigger\Interval\TwiceADay

Register a handler

There are two ways to register a handler:

  1. Using the mwsgRunJobsTriggerHandlerRegistry GlobalVars configuraton
  2. Using the hook MWStakeRunJobsTriggerRegisterHandlers

In both cases, an ObjectFactory specification must be provided.

Example 1: GlobalVars

$GLOBALS['mwsgRunJobsTriggerHandlerRegistry']['my-own-handler'] = [
    'class' => '\\MediaWiki\Extension\\MyExt\\MyHandler,
    'services' => 'MainConfig'
];

Example 2: Hookhandler

$GLOBALS['wgHooks']['MWStakeRunJobsTriggerRegisterHandlers'][] = function( &$handlers ) {
    $handlers["my-own-handler"] = [
        'class' => '\\MediaWiki\Extension\\MyExt\\MyHandler,
        'services' => 'MainConfig'
    ]
}

Configuration

  • mwsgRunJobsTriggerRunnerWorkingDir: Where to store data during execution. Defaults to the operating system's temp dir.
  • mwsgRunJobsTriggerOptions: Timing options for particular handlers.
  • mwsgRunJobsTriggerHandlerRegistry: Add your own trigger handlers.

Configuration examples

Using MediaWiki’s temporary directory to store data during execution

Suppose an administrator wants to ensure that they can ensure any temporary files are created in MediaWiki’s temporary directory rather than somewhere else. They could do this by adding the following to their LocalSettings.php:

$GLOBALS['mwsgRunJobsTriggerRunnerWorkingDir'] = $wgTmpDirectory;

Changing the timing options

A wiki administrator could add the following to their LocalSettings.php to have OnceAWeek tasks run on Friday instead of Sunday (by default):

$GLOBALS['mwsgRunJobsTriggerOptions']['*']['once-a-week-day'] = 'friday';

Debugging

A debug log can be enabled by adding

$GLOBALS['wgDebugLogGroups']['runjobs-trigger-runner'] = "/tmp/runjobs-trigger-runner.log";

to your LocalSettings.php file