Job.php

Go to the documentation of this file.

<?php
use MediaWiki\Page\PageReference;
 
abstract class Job implements RunnableJob {
    public $command;
 
    public $params;
 
    public $metadata = [];
 
    protected $title;
 
    protected $removeDuplicates = false;
 
    protected $error;
 
    protected $teardownCallbacks = [];
 
    protected $executionFlags = 0;
 
    public static function factory( $command, $params = [] ) {
        global $wgJobClasses;
 
        if ( $params instanceof PageReference ) {
            // Backwards compatibility for old signature ($command, $title, $params)
            $title = Title::castFromPageReference( $params );
            $params = func_num_args() >= 3 ? func_get_arg( 2 ) : [];
        } elseif ( isset( $params['namespace'] ) && isset( $params['title'] ) ) {
            // Handle job classes that take title as constructor parameter.
            // If a newer classes like GenericParameterJob uses these parameters,
            // then this happens in Job::__construct instead.
            $title = Title::makeTitle( $params['namespace'], $params['title'] );
        } else {
            // Default title for job classes not implementing GenericParameterJob.
            // This must be a valid title because it not directly passed to
            // our Job constructor, but rather it's subclasses which may expect
            // to be able to use it.
            $title = Title::makeTitle( NS_SPECIAL, 'Blankpage' );
        }
 
        if ( isset( $wgJobClasses[$command] ) ) {
            $handler = $wgJobClasses[$command];
 
            if ( is_callable( $handler ) ) {
                $job = call_user_func( $handler, $title, $params );
            } elseif ( class_exists( $handler ) ) {
                if ( is_subclass_of( $handler, GenericParameterJob::class ) ) {
                    $job = new $handler( $params );
                } else {
                    $job = new $handler( $title, $params );
                }
            } else {
                $job = null;
            }
 
            if ( $job instanceof Job ) {
                $job->command = $command;
 
                return $job;
            } else {
                throw new InvalidArgumentException(
                    "Could not instantiate job '$command': bad spec!"
                );
            }
        }
 
        throw new InvalidArgumentException( "Invalid job command '{$command}'" );
    }
 
    public function __construct( $command, $params = null ) {
        if ( $params instanceof PageReference ) {
            // Backwards compatibility for old signature ($command, $title, $params)
            $page = $params;
            $params = func_num_args() >= 3 ? func_get_arg( 2 ) : [];
        } else {
            // Newer jobs may choose to not have a top-level title (e.g. GenericParameterJob)
            $page = null;
        }
 
        if ( !is_array( $params ) ) {
            throw new InvalidArgumentException( '$params must be an array' );
        }
 
        if (
            $page &&
            !isset( $params['namespace'] ) &&
            !isset( $params['title'] )
        ) {
            // When constructing this class for submitting to the queue,
            // normalise the $page arg of old job classes as part of $params.
            $params['namespace'] = $page->getNamespace();
            $params['title'] = $page->getDBkey();
        }
 
        $this->command = $command;
        $this->params = $params + [ 'requestId' => WebRequest::getRequestId() ];
 
        if ( $this->title === null ) {
            // Set this field for access via getTitle().
            $this->title = ( isset( $params['namespace'] ) && isset( $params['title'] ) )
                ? Title::makeTitle( $params['namespace'], $params['title'] )
                // GenericParameterJob classes without namespace/title params
                // should not use getTitle(). Set an invalid title as placeholder.
                : Title::makeTitle( NS_SPECIAL, '' );
        }
    }
 
    public function hasExecutionFlag( $flag ) {
        return ( $this->executionFlags & $flag ) === $flag;
    }
 
    public function getType() {
        return $this->command;
    }
 
    final public function getTitle() {
        return $this->title;
    }
 
    public function getParams() {
        return $this->params;
    }
 
    public function getMetadata( $field = null ) {
        if ( $field === null ) {
            return $this->metadata;
        }
 
        return $this->metadata[$field] ?? null;
    }
 
    public function setMetadata( $field, $value ) {
        $old = $this->getMetadata( $field );
        if ( $value === null ) {
            unset( $this->metadata[$field] );
        } else {
            $this->metadata[$field] = $value;
        }
 
        return $old;
    }
 
    public function getReleaseTimestamp() {
        return isset( $this->params['jobReleaseTimestamp'] )
            ? wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] )
            : null;
    }
 
    public function getQueuedTimestamp() {
        return isset( $this->metadata['timestamp'] )
            ? wfTimestampOrNull( TS_UNIX, $this->metadata['timestamp'] )
            : null;
    }
 
    public function getRequestId() {
        return $this->params['requestId'] ?? null;
    }
 
    public function getReadyTimestamp() {
        return $this->getReleaseTimestamp() ?: $this->getQueuedTimestamp();
    }
 
    public function ignoreDuplicates() {
        return $this->removeDuplicates;
    }
 
    public function allowRetries() {
        return true;
    }
 
    public function workItemCount() {
        return 1;
    }
 
    public function getDeduplicationInfo() {
        $info = [
            'type' => $this->getType(),
            'params' => $this->getParams()
        ];
        if ( is_array( $info['params'] ) ) {
            // Identical jobs with different "root" jobs should count as duplicates
            unset( $info['params']['rootJobSignature'] );
            unset( $info['params']['rootJobTimestamp'] );
            // Likewise for jobs with different delay times
            unset( $info['params']['jobReleaseTimestamp'] );
            // Identical jobs from different requests should count as duplicates
            unset( $info['params']['requestId'] );
            // Queues pack and hash this array, so normalize the order
            ksort( $info['params'] );
        }
 
        return $info;
    }
 
    public static function newRootJobParams( $key ) {
        return [
            'rootJobIsSelf'    => true,
            'rootJobSignature' => sha1( $key ),
            'rootJobTimestamp' => wfTimestampNow()
        ];
    }
 
    public function getRootJobParams() {
        return [
            'rootJobSignature' => $this->params['rootJobSignature'] ?? null,
            'rootJobTimestamp' => $this->params['rootJobTimestamp'] ?? null
        ];
    }
 
    public function hasRootJobParams() {
        return isset( $this->params['rootJobSignature'] )
            && isset( $this->params['rootJobTimestamp'] );
    }
 
    public function isRootJob() {
        return $this->hasRootJobParams() && !empty( $this->params['rootJobIsSelf'] );
    }
 
    protected function addTeardownCallback( $callback ) {
        $this->teardownCallbacks[] = $callback;
    }
 
    public function teardown( $status ) {
        foreach ( $this->teardownCallbacks as $callback ) {
            call_user_func( $callback, $status );
        }
    }
 
    public function toString() {
        $paramString = '';
        if ( $this->params ) {
            foreach ( $this->params as $key => $value ) {
                if ( $paramString != '' ) {
                    $paramString .= ' ';
                }
                if ( is_array( $value ) ) {
                    $filteredValue = [];
                    foreach ( $value as $k => $v ) {
                        $json = FormatJson::encode( $v );
                        if ( $json === false || mb_strlen( $json ) > 512 ) {
                            $filteredValue[$k] = gettype( $v ) . '(...)';
                        } else {
                            $filteredValue[$k] = $v;
                        }
                    }
                    if ( count( $filteredValue ) <= 10 ) {
                        $value = FormatJson::encode( $filteredValue );
                    } else {
                        $value = "array(" . count( $value ) . ")";
                    }
                } elseif ( is_object( $value ) && !method_exists( $value, '__toString' ) ) {
                    $value = "object(" . get_class( $value ) . ")";
                }
 
                $flatValue = (string)$value;
                if ( mb_strlen( $flatValue ) > 1024 ) {
                    $flatValue = "string(" . mb_strlen( $value ) . ")";
                }
 
                $paramString .= "$key={$flatValue}";
            }
        }
 
        $metaString = '';
        foreach ( $this->metadata as $key => $value ) {
            if ( is_scalar( $value ) && mb_strlen( $value ) < 1024 ) {
                $metaString .= ( $metaString ? ",$key=$value" : "$key=$value" );
            }
        }
 
        $s = $this->command;
        if ( is_object( $this->title ) ) {
            $s .= " {$this->title->getPrefixedDBkey()}";
        }
        if ( $paramString != '' ) {
            $s .= " $paramString";
        }
        if ( $metaString != '' ) {
            $s .= " ($metaString)";
        }
 
        return $s;
    }
 
    protected function setLastError( $error ) {
        $this->error = $error;
    }
 
    public function getLastError() {
        return $this->error;
    }
}