MediaWiki  1.29.1
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 }
Job\getRootJobParams
getRootJobParams()
Definition: Job.php:274
Job\getReleaseTimestamp
getReleaseTimestamp()
Definition: Job.php:143
Job\teardown
teardown( $status)
Do any final cleanup after run(), deferred updates, and all DB commits happen.
Definition: Job.php:318
Job\getType
getType()
Definition: Job.php:121
Job\getParams
getParams()
Definition: Job.php:135
Job\toString
toString()
Definition: Job.php:337
captcha-old.count
count
Definition: captcha-old.py:225
Job\workItemCount
workItemCount()
Definition: Job.php:207
Job\getRequestId
getRequestId()
Definition: Job.php:165
Job\$title
Title $title
Definition: Job.php:42
Job\getQueuedTimestamp
getQueuedTimestamp()
Definition: Job.php:153
Job\getReadyTimestamp
getReadyTimestamp()
Definition: Job.php:175
$status
this hook is for auditing only RecentChangesLinked and Watchlist RecentChangesLinked and Watchlist Do not use this to implement individual filters if they are compatible with the ChangesListFilter and ChangesListFilterGroup structure use sub classes of those in conjunction with the ChangesListSpecialPageStructuredFilters hook This hook can be used to implement filters that do not implement that or custom behavior that is not an individual filter e g Watchlist and Watchlist you will want to construct new ChangesListBooleanFilter or ChangesListStringOptionsFilter objects When constructing you specify which group they belong to You can reuse existing or create your you must register them with $special registerFilterGroup 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:1049
$s
$s
Definition: mergeMessageFileList.php:188
Job\addTeardownCallback
addTeardownCallback( $callback)
Definition: Job.php:309
Job\$teardownCallbacks
callable[] $teardownCallbacks
Definition: Job.php:51
Job\$params
array $params
Array of job parameters.
Definition: Job.php:36
Job\setLastError
setLastError( $error)
Definition: Job.php:393
php
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
Job\ignoreDuplicates
ignoreDuplicates()
Whether the queue should reject insertion of this job if a duplicate exists.
Definition: Job.php:190
Job\getTitle
getTitle()
Definition: Job.php:128
Job
Class to both describe a background job and handle jobs.
Definition: Job.php:31
Job\factory
static factory( $command, Title $title, $params=[])
Create the appropriate object to handle a specific job.
Definition: Job.php:68
FormatJson\encode
static encode( $value, $pretty=false, $escaping=0)
Returns the JSON representation of a value.
Definition: FormatJson.php:127
Job\run
run()
Run the job.
Job\$error
string $error
Text for error that occurred last.
Definition: Job.php:48
wfDeprecated
wfDeprecated( $function, $version=false, $component=false, $callerOffset=2)
Throws a warning that $function is deprecated.
Definition: GlobalFunctions.php:1128
Job\$command
string $command
Definition: Job.php:33
wfTimestampOrNull
wfTimestampOrNull( $outputtype=TS_UNIX, $ts=null)
Return a formatted timestamp, or null if input is null.
Definition: GlobalFunctions.php:2010
Job\$metadata
array $metadata
Additional queue metadata.
Definition: Job.php:39
global
when a variable name is used in a it is silently declared as a new masking the global
Definition: design.txt:93
wfTimestampNow
wfTimestampNow()
Convenience function; returns MediaWiki timestamp for the present time.
Definition: GlobalFunctions.php:2023
Job\newRootJobParams
static newRootJobParams( $key)
Get "root job" parameters for a task.
Definition: Job.php:261
string
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
Job\allowRetries
allowRetries()
Definition: Job.php:198
$value
$value
Definition: styleTest.css.php:45
title
title
Definition: parserTests.txt:211
Job\batchInsert
static batchInsert( $jobs)
Batch-insert a group of jobs into the queue.
Definition: Job.php:112
Job\$removeDuplicates
bool $removeDuplicates
Expensive jobs may set this to true.
Definition: Job.php:45
Job\getLastError
getLastError()
Definition: Job.php:397
Job\getDeduplicationInfo
getDeduplicationInfo()
Subclasses may need to override this to make duplication detection work.
Definition: Job.php:220
error
&</p >< p >< sup id="cite_ref-blank_1-1" class="reference">< a href="#cite_note-blank-1"> &</p >< div class="mw-references-wrap">< ol class="references">< li id="cite_note-blank-1">< span class="mw-cite-backlink"> ↑< sup >< a href="#cite_ref-blank_1-0"></a ></sup >< sup >< a href="#cite_ref-blank_1-1"></a ></sup ></span >< span class="reference-text">< span class="error mw-ext-cite-error" lang="en" dir="ltr"> Cite error
Definition: citeParserTests.txt:219
Title
Represents a title within MediaWiki.
Definition: Title.php:39
$job
if(count( $args)< 1) $job
Definition: recompressTracked.php:47
WebRequest\getRequestId
static getRequestId()
Get the unique request ID.
Definition: WebRequest.php:272
JobQueueGroup\singleton
static singleton( $wiki=false)
Definition: JobQueueGroup.php:71
as
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
Job\isRootJob
isRootJob()
Definition: Job.php:299
Job\hasRootJobParams
hasRootJobParams()
Definition: Job.php:290
Job\__construct
__construct( $command, $title, $params=false)
Definition: Job.php:88
Job\insert
insert()
Insert a single job into the queue.
Definition: Job.php:329
IJobSpecification
Job queue task description interface.
Definition: JobSpecification.php:30
array
the array() calling protocol came about after MediaWiki 1.4rc1.