MediaWiki  master
Job.php
Go to the documentation of this file.
1 <?php
25 
37 abstract class Job implements RunnableJob {
39  public $command;
40 
42  public $params;
43 
45  public $metadata = [];
46 
48  protected $title;
49 
51  protected $removeDuplicates = false;
52 
54  protected $error;
55 
57  protected $teardownCallbacks = [];
58 
60  protected $executionFlags = 0;
61 
70  public static function factory( $command, $params = [] ) {
71  global $wgJobClasses;
72 
73  if ( $params instanceof PageReference ) {
74  // Backwards compatibility for old signature ($command, $title, $params)
76  $params = func_num_args() >= 3 ? func_get_arg( 2 ) : [];
77  } elseif ( isset( $params['namespace'] ) && isset( $params['title'] ) ) {
78  // Handle job classes that take title as constructor parameter.
79  // If a newer classes like GenericParameterJob uses these parameters,
80  // then this happens in Job::__construct instead.
81  $title = Title::makeTitle( $params['namespace'], $params['title'] );
82  } else {
83  // Default title for job classes not implementing GenericParameterJob.
84  // This must be a valid title because it not directly passed to
85  // our Job constructor, but rather it's subclasses which may expect
86  // to be able to use it.
87  $title = Title::makeTitle( NS_SPECIAL, 'Blankpage' );
88  }
89 
90  if ( isset( $wgJobClasses[$command] ) ) {
91  $handler = $wgJobClasses[$command];
92 
93  if ( is_callable( $handler ) ) {
94  $job = call_user_func( $handler, $title, $params );
95  } elseif ( class_exists( $handler ) ) {
96  if ( is_subclass_of( $handler, GenericParameterJob::class ) ) {
97  $job = new $handler( $params );
98  } else {
99  $job = new $handler( $title, $params );
100  }
101  } else {
102  $job = null;
103  }
104 
105  if ( $job instanceof Job ) {
106  $job->command = $command;
107 
108  return $job;
109  } else {
110  throw new InvalidArgumentException(
111  "Could not instantiate job '$command': bad spec!"
112  );
113  }
114  }
115 
116  throw new InvalidArgumentException( "Invalid job command '{$command}'" );
117  }
118 
125  public function __construct( $command, $params = null ) {
126  if ( $params instanceof PageReference ) {
127  // Backwards compatibility for old signature ($command, $title, $params)
128  $page = $params;
129  $params = func_num_args() >= 3 ? func_get_arg( 2 ) : [];
130  } else {
131  // Newer jobs may choose to not have a top-level title (e.g. GenericParameterJob)
132  $page = null;
133  }
134 
135  if ( !is_array( $params ) ) {
136  throw new InvalidArgumentException( '$params must be an array' );
137  }
138 
139  if (
140  $page &&
141  !isset( $params['namespace'] ) &&
142  !isset( $params['title'] )
143  ) {
144  // When constructing this class for submitting to the queue,
145  // normalise the $page arg of old job classes as part of $params.
146  $params['namespace'] = $page->getNamespace();
147  $params['title'] = $page->getDBkey();
148  }
149 
150  $this->command = $command;
151  $this->params = $params + [ 'requestId' => WebRequest::getRequestId() ];
152 
153  if ( $this->title === null ) {
154  // Set this field for access via getTitle().
155  $this->title = ( isset( $params['namespace'] ) && isset( $params['title'] ) )
156  ? Title::makeTitle( $params['namespace'], $params['title'] )
157  // GenericParameterJob classes without namespace/title params
158  // should not use getTitle(). Set an invalid title as placeholder.
159  : Title::makeTitle( NS_SPECIAL, '' );
160  }
161  }
162 
167  public function hasExecutionFlag( $flag ) {
168  return ( $this->executionFlags & $flag ) === $flag;
169  }
170 
175  public function getType() {
176  return $this->command;
177  }
178 
182  final public function getTitle() {
183  return $this->title;
184  }
185 
190  public function getParams() {
191  return $this->params;
192  }
193 
200  public function getMetadata( $field = null ) {
201  if ( $field === null ) {
202  return $this->metadata;
203  }
204 
205  return $this->metadata[$field] ?? null;
206  }
207 
215  public function setMetadata( $field, $value ) {
216  $old = $this->getMetadata( $field );
217  if ( $value === null ) {
218  unset( $this->metadata[$field] );
219  } else {
220  $this->metadata[$field] = $value;
221  }
222 
223  return $old;
224  }
225 
231  public function getReleaseTimestamp() {
232  return isset( $this->params['jobReleaseTimestamp'] )
233  ? wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] )
234  : null;
235  }
236 
241  public function getQueuedTimestamp() {
242  return isset( $this->metadata['timestamp'] )
243  ? wfTimestampOrNull( TS_UNIX, $this->metadata['timestamp'] )
244  : null;
245  }
246 
251  public function getRequestId() {
252  return $this->params['requestId'] ?? null;
253  }
254 
259  public function getReadyTimestamp() {
260  return $this->getReleaseTimestamp() ?: $this->getQueuedTimestamp();
261  }
262 
276  public function ignoreDuplicates() {
278  }
279 
284  public function allowRetries() {
285  return true;
286  }
287 
292  public function workItemCount() {
293  return 1;
294  }
295 
306  public function getDeduplicationInfo() {
307  $info = [
308  'type' => $this->getType(),
309  'params' => $this->getParams()
310  ];
311  if ( is_array( $info['params'] ) ) {
312  // Identical jobs with different "root" jobs should count as duplicates
313  unset( $info['params']['rootJobSignature'] );
314  unset( $info['params']['rootJobTimestamp'] );
315  // Likewise for jobs with different delay times
316  unset( $info['params']['jobReleaseTimestamp'] );
317  // Identical jobs from different requests should count as duplicates
318  unset( $info['params']['requestId'] );
319  // Queues pack and hash this array, so normalize the order
320  ksort( $info['params'] );
321  }
322 
323  return $info;
324  }
325 
345  public static function newRootJobParams( $key ) {
346  return [
347  'rootJobIsSelf' => true,
348  'rootJobSignature' => sha1( $key ),
349  'rootJobTimestamp' => wfTimestampNow()
350  ];
351  }
352 
359  public function getRootJobParams() {
360  return [
361  'rootJobSignature' => $this->params['rootJobSignature'] ?? null,
362  'rootJobTimestamp' => $this->params['rootJobTimestamp'] ?? null
363  ];
364  }
365 
372  public function hasRootJobParams() {
373  return isset( $this->params['rootJobSignature'] )
374  && isset( $this->params['rootJobTimestamp'] );
375  }
376 
382  public function isRootJob() {
383  return $this->hasRootJobParams() && !empty( $this->params['rootJobIsSelf'] );
384  }
385 
392  protected function addTeardownCallback( $callback ) {
393  $this->teardownCallbacks[] = $callback;
394  }
395 
400  public function teardown( $status ) {
401  foreach ( $this->teardownCallbacks as $callback ) {
402  call_user_func( $callback, $status );
403  }
404  }
405 
410  public function toString() {
411  $paramString = '';
412  if ( $this->params ) {
413  foreach ( $this->params as $key => $value ) {
414  if ( $paramString != '' ) {
415  $paramString .= ' ';
416  }
417  if ( is_array( $value ) ) {
418  $filteredValue = [];
419  foreach ( $value as $k => $v ) {
420  $json = FormatJson::encode( $v );
421  if ( $json === false || mb_strlen( $json ) > 512 ) {
422  $filteredValue[$k] = gettype( $v ) . '(...)';
423  } else {
424  $filteredValue[$k] = $v;
425  }
426  }
427  if ( count( $filteredValue ) <= 10 ) {
428  $value = FormatJson::encode( $filteredValue );
429  } else {
430  $value = "array(" . count( $value ) . ")";
431  }
432  } elseif ( is_object( $value ) && !method_exists( $value, '__toString' ) ) {
433  $value = "object(" . get_class( $value ) . ")";
434  }
435 
436  $flatValue = (string)$value;
437  if ( mb_strlen( $value ) > 1024 ) {
438  $flatValue = "string(" . mb_strlen( $value ) . ")";
439  }
440 
441  $paramString .= "$key={$flatValue}";
442  }
443  }
444 
445  $metaString = '';
446  foreach ( $this->metadata as $key => $value ) {
447  if ( is_scalar( $value ) && mb_strlen( $value ) < 1024 ) {
448  $metaString .= ( $metaString ? ",$key=$value" : "$key=$value" );
449  }
450  }
451 
452  $s = $this->command;
453  if ( is_object( $this->title ) ) {
454  $s .= " {$this->title->getPrefixedDBkey()}";
455  }
456  if ( $paramString != '' ) {
457  $s .= " $paramString";
458  }
459  if ( $metaString != '' ) {
460  $s .= " ($metaString)";
461  }
462 
463  return $s;
464  }
465 
466  protected function setLastError( $error ) {
467  $this->error = $error;
468  }
469 
474  public function getLastError() {
475  return $this->error;
476  }
477 }
Job\getMetadata
getMetadata( $field=null)
Definition: Job.php:200
Job\getRootJobParams
getRootJobParams()
Definition: Job.php:359
Job\getReleaseTimestamp
getReleaseTimestamp()
Definition: Job.php:231
Job\teardown
teardown( $status)
Definition: Job.php:400
Job\getType
getType()
string Job type that defines what sort of changes this job makes
Definition: Job.php:175
Job\getParams
getParams()
array Parameters that specify sources, targets, and options for execution
Definition: Job.php:190
Job\toString
toString()
string Debugging string describing the job
Definition: Job.php:410
Job\workItemCount
workItemCount()
Definition: Job.php:292
Job\getRequestId
getRequestId()
string|null Id of the request that created this job. Follows jobs recursively, allowing to track the ...
Definition: Job.php:251
Job\$title
Title $title
Definition: Job.php:48
Job\getQueuedTimestamp
getQueuedTimestamp()
Definition: Job.php:241
Job\getReadyTimestamp
getReadyTimestamp()
int|null UNIX timestamp of when the job was runnable, or null 1.26
Definition: Job.php:259
RunnableJob
Job that has a run() method and metadata accessors for JobQueue::pop() and JobQueue::ack()
Definition: RunnableJob.php:37
Job\addTeardownCallback
addTeardownCallback( $callback)
Definition: Job.php:392
Job\$teardownCallbacks
callable[] $teardownCallbacks
Definition: Job.php:57
Job\$params
array $params
Array of job parameters.
Definition: Job.php:42
Job\setLastError
setLastError( $error)
Definition: Job.php:466
Page\PageReference
Interface for objects (potentially) representing a page that can be viewable and linked to on a wiki.
Definition: PageReference.php:49
Job\ignoreDuplicates
ignoreDuplicates()
Whether the queue should reject insertion of this job if a duplicate exists.
Definition: Job.php:276
Job\getTitle
getTitle()
Definition: Job.php:182
Job\hasExecutionFlag
hasExecutionFlag( $flag)
JOB_* class constant bool 1.31
Definition: Job.php:167
NS_SPECIAL
const NS_SPECIAL
Definition: Defines.php:53
Job
Class to both describe a background job and handle jobs.
Definition: Job.php:37
FormatJson\encode
static encode( $value, $pretty=false, $escaping=0)
Returns the JSON representation of a value.
Definition: FormatJson.php:96
Job\$error
string $error
Text for error that occurred last.
Definition: Job.php:54
Job\$command
string $command
Definition: Job.php:39
wfTimestampOrNull
wfTimestampOrNull( $outputtype=TS_UNIX, $ts=null)
Return a formatted timestamp, or null if input is null.
Definition: GlobalFunctions.php:1681
Job\$metadata
array $metadata
Additional queue metadata.
Definition: Job.php:45
Title\makeTitle
static makeTitle( $ns, $title, $fragment='', $interwiki='')
Create a new Title from a namespace index and a DB key.
Definition: Title.php:663
wfTimestampNow
wfTimestampNow()
Convenience function; returns MediaWiki timestamp for the present time.
Definition: GlobalFunctions.php:1694
Job\newRootJobParams
static newRootJobParams( $key)
Get "root job" parameters for a task.
Definition: Job.php:345
Job\factory
static factory( $command, $params=[])
Create the appropriate object to handle a specific job.
Definition: Job.php:70
$s
foreach( $mmfl['setupFiles'] as $fileName) if( $queue) if(empty( $mmfl['quiet'])) $s
Definition: mergeMessageFileList.php:206
Job\allowRetries
allowRetries()
bool Whether this job can be retried on failure by job runners 1.21
Definition: Job.php:284
Job\$removeDuplicates
bool $removeDuplicates
Expensive jobs may set this to true.
Definition: Job.php:51
Job\getLastError
getLastError()
string
Definition: Job.php:474
Job\getDeduplicationInfo
getDeduplicationInfo()
Subclasses may need to override this to make duplication detection work.
Definition: Job.php:306
Job\$executionFlags
int $executionFlags
Bitfield of JOB_* class constants.
Definition: Job.php:60
$wgJobClasses
$wgJobClasses
Maps jobs to their handlers; extensions can add to this to provide custom jobs.
Definition: DefaultSettings.php:8664
Title
Represents a title within MediaWiki.
Definition: Title.php:47
$job
if(count( $args)< 1) $job
Definition: recompressTracked.php:49
WebRequest\getRequestId
static getRequestId()
Get the current request ID.
Definition: WebRequest.php:333
Job\isRootJob
isRootJob()
Definition: Job.php:382
Job\hasRootJobParams
hasRootJobParams()
Definition: Job.php:372
Title\castFromPageReference
static castFromPageReference(?PageReference $pageReference)
Return a Title for a given Reference.
Definition: Title.php:357
Job\setMetadata
setMetadata( $field, $value)
Definition: Job.php:215
Job\__construct
__construct( $command, $params=null)
Definition: Job.php:125