MediaWiki  1.28.0
Job.php
Go to the documentation of this file.
1 <?php
31 abstract class Job implements IJobSpecification {
33  public $command;
34 
36  public $params;
37 
39  public $metadata = [];
40 
42  protected $title;
43 
45  protected $removeDuplicates;
46 
48  protected $error;
49 
51  protected $teardownCallbacks = [];
52 
57  abstract public function run();
58 
68  public static function factory( $command, Title $title, $params = [] ) {
69  global $wgJobClasses;
70 
71  if ( isset( $wgJobClasses[$command] ) ) {
72  $class = $wgJobClasses[$command];
73 
74  $job = new $class( $title, $params );
75  $job->command = $command;
76 
77  return $job;
78  }
79 
80  throw new InvalidArgumentException( "Invalid job command '{$command}'" );
81  }
82 
88  public function __construct( $command, $title, $params = false ) {
89  $this->command = $command;
90  $this->title = $title;
91  $this->params = is_array( $params ) ? $params : []; // sanity
92 
93  // expensive jobs may set this to true
94  $this->removeDuplicates = false;
95 
96  if ( !isset( $this->params['requestId'] ) ) {
97  $this->params['requestId'] = WebRequest::getRequestId();
98  }
99  }
100 
112  public static function batchInsert( $jobs ) {
113  wfDeprecated( __METHOD__, '1.21' );
114  JobQueueGroup::singleton()->push( $jobs );
115  return true;
116  }
117 
121  public function getType() {
122  return $this->command;
123  }
124 
128  public function getTitle() {
129  return $this->title;
130  }
131 
135  public function getParams() {
136  return $this->params;
137  }
138 
143  public function getReleaseTimestamp() {
144  return isset( $this->params['jobReleaseTimestamp'] )
145  ? wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] )
146  : null;
147  }
148 
153  public function getQueuedTimestamp() {
154  return isset( $this->metadata['timestamp'] )
155  ? wfTimestampOrNull( TS_UNIX, $this->metadata['timestamp'] )
156  : null;
157  }
158 
165  public function getRequestId() {
166  return isset( $this->params['requestId'] )
167  ? $this->params['requestId']
168  : null;
169  }
170 
175  public function getReadyTimestamp() {
176  return $this->getReleaseTimestamp() ?: $this->getQueuedTimestamp();
177  }
178 
190  public function ignoreDuplicates() {
192  }
193 
198  public function allowRetries() {
199  return true;
200  }
201 
207  public function workItemCount() {
208  return 1;
209  }
210 
220  public function getDeduplicationInfo() {
221  $info = [
222  'type' => $this->getType(),
223  'namespace' => $this->getTitle()->getNamespace(),
224  'title' => $this->getTitle()->getDBkey(),
225  'params' => $this->getParams()
226  ];
227  if ( is_array( $info['params'] ) ) {
228  // Identical jobs with different "root" jobs should count as duplicates
229  unset( $info['params']['rootJobSignature'] );
230  unset( $info['params']['rootJobTimestamp'] );
231  // Likewise for jobs with different delay times
232  unset( $info['params']['jobReleaseTimestamp'] );
233  // Identical jobs from different requests should count as duplicates
234  unset( $info['params']['requestId'] );
235  // Queues pack and hash this array, so normalize the order
236  ksort( $info['params'] );
237  }
238 
239  return $info;
240  }
241 
261  public static function newRootJobParams( $key ) {
262  return [
263  'rootJobIsSelf' => true,
264  'rootJobSignature' => sha1( $key ),
265  'rootJobTimestamp' => wfTimestampNow()
266  ];
267  }
268 
274  public function getRootJobParams() {
275  return [
276  'rootJobSignature' => isset( $this->params['rootJobSignature'] )
277  ? $this->params['rootJobSignature']
278  : null,
279  'rootJobTimestamp' => isset( $this->params['rootJobTimestamp'] )
280  ? $this->params['rootJobTimestamp']
281  : null
282  ];
283  }
284 
290  public function hasRootJobParams() {
291  return isset( $this->params['rootJobSignature'] )
292  && isset( $this->params['rootJobTimestamp'] );
293  }
294 
299  public function isRootJob() {
300  return $this->hasRootJobParams() && !empty( $this->params['rootJobIsSelf'] );
301  }
302 
309  protected function addTeardownCallback( $callback ) {
310  $this->teardownCallbacks[] = $callback;
311  }
312 
318  public function teardown( $status ) {
319  foreach ( $this->teardownCallbacks as $callback ) {
320  call_user_func( $callback, $status );
321  }
322  }
323 
329  public function insert() {
330  JobQueueGroup::singleton()->push( $this );
331  return true;
332  }
333 
337  public function toString() {
338  $paramString = '';
339  if ( $this->params ) {
340  foreach ( $this->params as $key => $value ) {
341  if ( $paramString != '' ) {
342  $paramString .= ' ';
343  }
344  if ( is_array( $value ) ) {
345  $filteredValue = [];
346  foreach ( $value as $k => $v ) {
347  $json = FormatJson::encode( $v );
348  if ( $json === false || mb_strlen( $json ) > 512 ) {
349  $filteredValue[$k] = gettype( $v ) . '(...)';
350  } else {
351  $filteredValue[$k] = $v;
352  }
353  }
354  if ( count( $filteredValue ) <= 10 ) {
355  $value = FormatJson::encode( $filteredValue );
356  } else {
357  $value = "array(" . count( $value ) . ")";
358  }
359  } elseif ( is_object( $value ) && !method_exists( $value, '__toString' ) ) {
360  $value = "object(" . get_class( $value ) . ")";
361  }
362 
363  $flatValue = (string)$value;
364  if ( mb_strlen( $value ) > 1024 ) {
365  $flatValue = "string(" . mb_strlen( $value ) . ")";
366  }
367 
368  $paramString .= "$key={$flatValue}";
369  }
370  }
371 
372  $metaString = '';
373  foreach ( $this->metadata as $key => $value ) {
374  if ( is_scalar( $value ) && mb_strlen( $value ) < 1024 ) {
375  $metaString .= ( $metaString ? ",$key=$value" : "$key=$value" );
376  }
377  }
378 
379  $s = $this->command;
380  if ( is_object( $this->title ) ) {
381  $s .= " {$this->title->getPrefixedDBkey()}";
382  }
383  if ( $paramString != '' ) {
384  $s .= " $paramString";
385  }
386  if ( $metaString != '' ) {
387  $s .= " ($metaString)";
388  }
389 
390  return $s;
391  }
392 
393  protected function setLastError( $error ) {
394  $this->error = $error;
395  }
396 
397  public function getLastError() {
398  return $this->error;
399  }
400 }
getType()
Definition: Job.php:121
callable[] $teardownCallbacks
Definition: Job.php:51
getParams()
Definition: Job.php:135
hasRootJobParams()
Definition: Job.php:290
static getRequestId()
Get the unique request ID.
Definition: WebRequest.php:272
addTeardownCallback($callback)
Definition: Job.php:309
getTitle()
Definition: Job.php:128
static batchInsert($jobs)
Batch-insert a group of jobs into the queue.
Definition: Job.php:112
string $error
Text for error that occurred last.
Definition: Job.php:48
getQueuedTimestamp()
Definition: Job.php:153
allowRetries()
Definition: Job.php:198
Class to both describe a background job and handle jobs.
Definition: Job.php:31
This code would result in ircNotify being run twice when an article is and once for brion Hooks can return three possible true was required This is the default since MediaWiki *some string
Definition: hooks.txt:177
$value
getReadyTimestamp()
Definition: Job.php:175
string $command
Definition: Job.php:33
static newRootJobParams($key)
Get "root job" parameters for a task.
Definition: Job.php:261
getReleaseTimestamp()
Definition: Job.php:143
when a variable name is used in a it is silently declared as a new local masking the global
Definition: design.txt:93
insert()
Insert a single job into the queue.
Definition: Job.php:329
title
ignoreDuplicates()
Whether the queue should reject insertion of this job if a duplicate exists.
Definition: Job.php:190
const TS_UNIX
Unix time - the number of seconds since 1970-01-01 00:00:00 UTC.
Definition: defines.php:6
run()
Run the job.
getRootJobParams()
Definition: Job.php:274
wfTimestampNow()
Convenience function; returns MediaWiki timestamp for the present time.
getRequestId()
Definition: Job.php:165
static encode($value, $pretty=false, $escaping=0)
Returns the JSON representation of a value.
Definition: FormatJson.php:127
wfDeprecated($function, $version=false, $component=false, $callerOffset=2)
Throws a warning that $function is deprecated.
toString()
Definition: Job.php:337
This document is intended to provide useful advice for parties seeking to redistribute MediaWiki to end users It s targeted particularly at maintainers for Linux since it s been observed that distribution packages of MediaWiki often break We ve consistently had to recommend that users seeking support use official tarballs instead of their distribution s and this often solves whatever problem the user is having It would be nice if this could such as
Definition: distributors.txt:9
static singleton($wiki=false)
__construct($command, $title, $params=false)
Definition: Job.php:88
bool $removeDuplicates
Expensive jobs may set this to true.
Definition: Job.php:45
injection txt This is an overview of how MediaWiki makes use of dependency injection The design described here grew from the discussion of RFC T384 The term dependency this means that anything an object needs to operate should be injected from the the object itself should only know narrow no concrete implementation of the logic it relies on The requirement to inject everything typically results in an architecture that based on two main types of and essentially stateless service objects that use other service objects to operate on the value objects As of the beginning MediaWiki is only starting to use the DI approach Much of the code still relies on global state or direct resulting in a highly cyclical dependency which acts as the top level factory for services in MediaWiki which can be used to gain access to default instances of various services MediaWikiServices however also allows new services to be defined and default services to be redefined Services are defined or redefined by providing a callback the instantiator that will return a new instance of the service When it will create an instance of MediaWikiServices and populate it with the services defined in the files listed by thereby bootstrapping the DI framework Per $wgServiceWiringFiles lists includes ServiceWiring php
Definition: injection.txt:35
static factory($command, Title $title, $params=[])
Create the appropriate object to handle a specific job.
Definition: Job.php:68
array $metadata
Additional queue metadata.
Definition: Job.php:39
if(count($args)< 1) $job
setLastError($error)
Definition: Job.php:393
this hook is for auditing only RecentChangesLinked and Watchlist RecentChangesLinked and Watchlist e g Watchlist removed from all revisions and log entries to which it was applied This gives extensions a chance to take it off their books as the deletion has already been partly carried out by this point or something similar the user will be unable to create the tag set $status
Definition: hooks.txt:1046
array $params
Array of job parameters.
Definition: Job.php:36
Job queue task description interface.
isRootJob()
Definition: Job.php:299
getLastError()
Definition: Job.php:397
wfTimestampOrNull($outputtype=TS_UNIX, $ts=null)
Return a formatted timestamp, or null if input is null.
getDeduplicationInfo()
Subclasses may need to override this to make duplication detection work.
Definition: Job.php:220
workItemCount()
Definition: Job.php:207
Title $title
Definition: Job.php:42
teardown($status)
Do any final cleanup after run(), deferred updates, and all DB commits happen.
Definition: Job.php:318