MediaWiki  master
Job.php
Go to the documentation of this file.
1 <?php
27 
39 abstract class Job implements RunnableJob {
41  public $command;
42 
44  public $params;
45 
47  public $metadata = [];
48 
50  protected $title;
51 
53  protected $removeDuplicates = false;
54 
56  protected $error;
57 
59  protected $teardownCallbacks = [];
60 
62  protected $executionFlags = 0;
63 
72  public static function factory( $command, $params = [] ) {
73  $jobClasses = MediaWikiServices::getInstance()->getMainConfig()->get(
74  MainConfigNames::JobClasses );
75 
76  if ( $params instanceof PageReference ) {
77  // Backwards compatibility for old signature ($command, $title, $params)
79  $params = func_num_args() >= 3 ? func_get_arg( 2 ) : [];
80  } elseif ( isset( $params['namespace'] ) && isset( $params['title'] ) ) {
81  // Handle job classes that take title as constructor parameter.
82  // If a newer classes like GenericParameterJob uses these parameters,
83  // then this happens in Job::__construct instead.
84  $title = Title::makeTitle( $params['namespace'], $params['title'] );
85  } else {
86  // Default title for job classes not implementing GenericParameterJob.
87  // This must be a valid title because it not directly passed to
88  // our Job constructor, but rather it's subclasses which may expect
89  // to be able to use it.
90  $title = Title::makeTitle( NS_SPECIAL, 'Blankpage' );
91  }
92 
93  if ( isset( $jobClasses[$command] ) ) {
94  $handler = $jobClasses[$command];
95 
96  if ( is_callable( $handler ) ) {
97  $job = call_user_func( $handler, $title, $params );
98  } elseif ( class_exists( $handler ) ) {
99  if ( is_subclass_of( $handler, GenericParameterJob::class ) ) {
100  $job = new $handler( $params );
101  } else {
102  $job = new $handler( $title, $params );
103  }
104  } else {
105  $job = null;
106  }
107 
108  if ( $job instanceof Job ) {
109  $job->command = $command;
110 
111  return $job;
112  } else {
113  throw new InvalidArgumentException(
114  "Could not instantiate job '$command': bad spec!"
115  );
116  }
117  }
118 
119  throw new InvalidArgumentException( "Invalid job command '{$command}'" );
120  }
121 
128  public function __construct( $command, $params = null ) {
129  if ( $params instanceof PageReference ) {
130  // Backwards compatibility for old signature ($command, $title, $params)
131  $page = $params;
132  $params = func_num_args() >= 3 ? func_get_arg( 2 ) : [];
133  } else {
134  // Newer jobs may choose to not have a top-level title (e.g. GenericParameterJob)
135  $page = null;
136  }
137 
138  if ( !is_array( $params ) ) {
139  throw new InvalidArgumentException( '$params must be an array' );
140  }
141 
142  if (
143  $page &&
144  !isset( $params['namespace'] ) &&
145  !isset( $params['title'] )
146  ) {
147  // When constructing this class for submitting to the queue,
148  // normalise the $page arg of old job classes as part of $params.
149  $params['namespace'] = $page->getNamespace();
150  $params['title'] = $page->getDBkey();
151  }
152 
153  $this->command = $command;
154  $this->params = $params + [ 'requestId' => WebRequest::getRequestId() ];
155 
156  if ( $this->title === null ) {
157  // Set this field for access via getTitle().
158  $this->title = ( isset( $params['namespace'] ) && isset( $params['title'] ) )
159  ? Title::makeTitle( $params['namespace'], $params['title'] )
160  // GenericParameterJob classes without namespace/title params
161  // should not use getTitle(). Set an invalid title as placeholder.
162  : Title::makeTitle( NS_SPECIAL, '' );
163  }
164  }
165 
170  public function hasExecutionFlag( $flag ) {
171  return ( $this->executionFlags & $flag ) === $flag;
172  }
173 
178  public function getType() {
179  return $this->command;
180  }
181 
185  final public function getTitle() {
186  return $this->title;
187  }
188 
193  public function getParams() {
194  return $this->params;
195  }
196 
203  public function getMetadata( $field = null ) {
204  if ( $field === null ) {
205  return $this->metadata;
206  }
207 
208  return $this->metadata[$field] ?? null;
209  }
210 
218  public function setMetadata( $field, $value ) {
219  $old = $this->getMetadata( $field );
220  if ( $value === null ) {
221  unset( $this->metadata[$field] );
222  } else {
223  $this->metadata[$field] = $value;
224  }
225 
226  return $old;
227  }
228 
234  public function getReleaseTimestamp() {
235  return isset( $this->params['jobReleaseTimestamp'] )
236  ? wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] )
237  : null;
238  }
239 
244  public function getQueuedTimestamp() {
245  return isset( $this->metadata['timestamp'] )
246  ? wfTimestampOrNull( TS_UNIX, $this->metadata['timestamp'] )
247  : null;
248  }
249 
254  public function getRequestId() {
255  return $this->params['requestId'] ?? null;
256  }
257 
262  public function getReadyTimestamp() {
263  return $this->getReleaseTimestamp() ?: $this->getQueuedTimestamp();
264  }
265 
279  public function ignoreDuplicates() {
281  }
282 
287  public function allowRetries() {
288  return true;
289  }
290 
295  public function workItemCount() {
296  return 1;
297  }
298 
309  public function getDeduplicationInfo() {
310  $info = [
311  'type' => $this->getType(),
312  'params' => $this->getParams()
313  ];
314  if ( is_array( $info['params'] ) ) {
315  // Identical jobs with different "root" jobs should count as duplicates
316  unset( $info['params']['rootJobSignature'] );
317  unset( $info['params']['rootJobTimestamp'] );
318  // Likewise for jobs with different delay times
319  unset( $info['params']['jobReleaseTimestamp'] );
320  // Identical jobs from different requests should count as duplicates
321  unset( $info['params']['requestId'] );
322  // Queues pack and hash this array, so normalize the order
323  ksort( $info['params'] );
324  }
325 
326  return $info;
327  }
328 
348  public static function newRootJobParams( $key ) {
349  return [
350  'rootJobIsSelf' => true,
351  'rootJobSignature' => sha1( $key ),
352  'rootJobTimestamp' => wfTimestampNow()
353  ];
354  }
355 
362  public function getRootJobParams() {
363  return [
364  'rootJobSignature' => $this->params['rootJobSignature'] ?? null,
365  'rootJobTimestamp' => $this->params['rootJobTimestamp'] ?? null
366  ];
367  }
368 
375  public function hasRootJobParams() {
376  return isset( $this->params['rootJobSignature'] )
377  && isset( $this->params['rootJobTimestamp'] );
378  }
379 
385  public function isRootJob() {
386  return $this->hasRootJobParams() && !empty( $this->params['rootJobIsSelf'] );
387  }
388 
395  protected function addTeardownCallback( $callback ) {
396  $this->teardownCallbacks[] = $callback;
397  }
398 
403  public function teardown( $status ) {
404  foreach ( $this->teardownCallbacks as $callback ) {
405  call_user_func( $callback, $status );
406  }
407  }
408 
413  public function toString() {
414  $paramString = '';
415  if ( $this->params ) {
416  foreach ( $this->params as $key => $value ) {
417  if ( $paramString != '' ) {
418  $paramString .= ' ';
419  }
420  if ( is_array( $value ) ) {
421  $filteredValue = [];
422  foreach ( $value as $k => $v ) {
423  $json = FormatJson::encode( $v );
424  if ( $json === false || mb_strlen( $json ) > 512 ) {
425  $filteredValue[$k] = gettype( $v ) . '(...)';
426  } else {
427  $filteredValue[$k] = $v;
428  }
429  }
430  if ( count( $filteredValue ) <= 10 ) {
431  $value = FormatJson::encode( $filteredValue );
432  } else {
433  $value = "array(" . count( $value ) . ")";
434  }
435  } elseif ( is_object( $value ) && !method_exists( $value, '__toString' ) ) {
436  $value = "object(" . get_class( $value ) . ")";
437  }
438 
439  $flatValue = (string)$value;
440  if ( mb_strlen( $value ) > 1024 ) {
441  $flatValue = "string(" . mb_strlen( $value ) . ")";
442  }
443 
444  $paramString .= "$key={$flatValue}";
445  }
446  }
447 
448  $metaString = '';
449  foreach ( $this->metadata as $key => $value ) {
450  if ( is_scalar( $value ) && mb_strlen( $value ) < 1024 ) {
451  $metaString .= ( $metaString ? ",$key=$value" : "$key=$value" );
452  }
453  }
454 
455  $s = $this->command;
456  if ( is_object( $this->title ) ) {
457  $s .= " {$this->title->getPrefixedDBkey()}";
458  }
459  if ( $paramString != '' ) {
460  $s .= " $paramString";
461  }
462  if ( $metaString != '' ) {
463  $s .= " ($metaString)";
464  }
465 
466  return $s;
467  }
468 
469  protected function setLastError( $error ) {
470  $this->error = $error;
471  }
472 
477  public function getLastError() {
478  return $this->error;
479  }
480 }
const NS_SPECIAL
Definition: Defines.php:53
wfTimestampOrNull( $outputtype=TS_UNIX, $ts=null)
Return a formatted timestamp, or null if input is null.
wfTimestampNow()
Convenience function; returns MediaWiki timestamp for the present time.
static encode( $value, $pretty=false, $escaping=0)
Returns the JSON representation of a value.
Definition: FormatJson.php:96
Class to both describe a background job and handle jobs.
Definition: Job.php:39
hasRootJobParams()
Definition: Job.php:375
string $command
Definition: Job.php:41
setMetadata( $field, $value)
Definition: Job.php:218
getParams()
array Parameters that specify sources, targets, and options for execution
Definition: Job.php:193
getReadyTimestamp()
int|null UNIX timestamp of when the job was runnable, or null 1.26
Definition: Job.php:262
toString()
string Debugging string describing the job
Definition: Job.php:413
getType()
string Job type that defines what sort of changes this job makes
Definition: Job.php:178
Title $title
Definition: Job.php:50
getRootJobParams()
Definition: Job.php:362
hasExecutionFlag( $flag)
JOB_* class constant bool 1.31
Definition: Job.php:170
callable[] $teardownCallbacks
Definition: Job.php:59
getQueuedTimestamp()
Definition: Job.php:244
bool $removeDuplicates
Expensive jobs may set this to true.
Definition: Job.php:53
setLastError( $error)
Definition: Job.php:469
getMetadata( $field=null)
Definition: Job.php:203
teardown( $status)
Definition: Job.php:403
isRootJob()
Definition: Job.php:385
addTeardownCallback( $callback)
Definition: Job.php:395
array $params
Array of job parameters.
Definition: Job.php:44
getTitle()
Definition: Job.php:185
array $metadata
Additional queue metadata.
Definition: Job.php:47
static factory( $command, $params=[])
Create the appropriate object to handle a specific job.
Definition: Job.php:72
int $executionFlags
Bitfield of JOB_* class constants.
Definition: Job.php:62
workItemCount()
Definition: Job.php:295
getRequestId()
string|null Id of the request that created this job. Follows jobs recursively, allowing to track the ...
Definition: Job.php:254
static newRootJobParams( $key)
Get "root job" parameters for a task.
Definition: Job.php:348
getDeduplicationInfo()
Subclasses may need to override this to make duplication detection work.
Definition: Job.php:309
getReleaseTimestamp()
Definition: Job.php:234
ignoreDuplicates()
Whether the queue should reject insertion of this job if a duplicate exists.
Definition: Job.php:279
getLastError()
string
Definition: Job.php:477
string $error
Text for error that occurred last.
Definition: Job.php:56
allowRetries()
bool Whether this job can be retried on failure by job runners 1.21
Definition: Job.php:287
__construct( $command, $params=null)
Definition: Job.php:128
A class containing constants representing the names of configuration variables.
MediaWikiServices is the service locator for the application scope of MediaWiki.
static castFromPageReference(?PageReference $pageReference)
Return a Title for a given Reference.
Definition: Title.php:331
static makeTitle( $ns, $title, $fragment='', $interwiki='')
Create a new Title from a namespace index and a DB key.
Definition: Title.php:637
static getRequestId()
Get the current request ID.
Definition: WebRequest.php:342
Interface for objects (potentially) representing a page that can be viewable and linked to on a wiki.
Job that has a run() method and metadata accessors for JobQueue::pop() and JobQueue::ack()
Definition: RunnableJob.php:37
foreach( $mmfl['setupFiles'] as $fileName) if( $queue) if(empty( $mmfl['quiet'])) $s
if(count( $args)< 1) $job