Nextcloud PHP API (master)

IJobList

Interface IJobList

This interface provides functions to register background jobs

To create a new background job create a new class that inherits from either \OCP\BackgroundJob\Job, \OCP\BackgroundJob\QueuedJob or \OCP\BackgroundJob\TimedJob and register it using ->add($job, $argument), $argument will be passed to the run() function of the job when the job is executed.

A regular job will be executed every time cron.php is run, a QueuedJob will only run once and a TimedJob will only run at a specific interval which is to be specified in the constructor of the job by calling $this->setInterval($interval) with $interval in seconds.

This interface should be used directly and not implemented by an application. The implementation is provided by the server.

Tags
since
7.0.0

Table of Contents

Methods

add()  : void
Add a job to the list
getById()  : IJob|null
getDetailsById()  : array<string|int, mixed>|null
getJobs()  : array<string|int, IJob>
Get jobs matching the search
getJobsIterator()  : iterable<string|int, IJob>
Get jobs matching the search
getNext()  : IJob|null
get the next job in the list
has()  : bool
check if a job is in the list
hasReservedJob()  : bool
Checks whether a job of the passed class was reserved to run in the last 6h
remove()  : void
Remove a job from the list
resetBackgroundJob()  : void
Reset the $job so it executes on the next trigger
scheduleAfter()  : void
Add a job to the list but only run it after the given timestamp
setExecutionTime()  : void
set the run duration of $job
setLastJob()  : void
set the job that was last ran to the current time
setLastRun()  : void
set the lastRun of $job to now
unlockJob()  : void
Remove the reservation for a job

Methods

add()

Add a job to the list

public add(IJob|IJob> $job[, mixed $argument = null ]) : void
Parameters
$job : IJob|IJob>
$argument : mixed = null

The argument to be passed to $job->run() when the job is executed

Tags
since
7.0.0

getById()

public getById(int $id) : IJob|null
Parameters
$id : int
Tags
since
7.0.0
Return values
IJob|null

getDetailsById()

public getDetailsById(int $id) : array<string|int, mixed>|null
Parameters
$id : int
Tags
since
23.0.0
Return values
array<string|int, mixed>|null

getJobs()

Get jobs matching the search

public getJobs(IJob|IJob>|null $job, int|null $limit, int $offset) : array<string|int, IJob>
Parameters
$job : IJob|IJob>|null
$limit : int|null
$offset : int
Tags
since
25.0.0
deprecated
26.0.0

Use getJobsIterator instead to avoid duplicated job objects

Return values
array<string|int, IJob>

getJobsIterator()

Get jobs matching the search

public getJobsIterator(IJob|IJob>|null $job, int|null $limit, int $offset) : iterable<string|int, IJob>
Parameters
$job : IJob|IJob>|null
$limit : int|null
$offset : int
Tags
since
26.0.0
Return values
iterable<string|int, IJob>

getNext()

get the next job in the list

public getNext([bool $onlyTimeSensitive = false ]) : IJob|null
Parameters
$onlyTimeSensitive : bool = false
Tags
since
7.0.0
  • In 24.0.0 parameter $onlyTimeSensitive got added
Return values
IJob|null

has()

check if a job is in the list

public has(IJob|IJob> $job, mixed $argument) : bool
Parameters
$job : IJob|IJob>
$argument : mixed
Tags
since
7.0.0
Return values
bool

hasReservedJob()

Checks whether a job of the passed class was reserved to run in the last 6h

public hasReservedJob(string|null $className) : bool
Parameters
$className : string|null
Tags
since
27.0.0
Return values
bool

remove()

Remove a job from the list

public remove(IJob|IJob> $job[, mixed $argument = null ]) : void
Parameters
$job : IJob|IJob>
$argument : mixed = null
Tags
since
7.0.0

resetBackgroundJob()

Reset the $job so it executes on the next trigger

public resetBackgroundJob(IJob $job) : void
Parameters
$job : IJob
Tags
since
23.0.0

scheduleAfter()

Add a job to the list but only run it after the given timestamp

public scheduleAfter(IJob> $job, int $runAfter[, mixed $argument = null ]) : void

For cron background jobs this means the job will likely run shortly after the timestamp has been reached. For ajax background jobs the job might only run when users are active on the instance again.

Parameters
$job : IJob>
$runAfter : int
$argument : mixed = null

The serializable argument to be passed to $job->run() when the job is executed

Tags
since
28.0.0

setExecutionTime()

set the run duration of $job

public setExecutionTime(IJob $job, int $timeTaken) : void
Parameters
$job : IJob
$timeTaken : int
Tags
since
12.0.0

setLastJob()

set the job that was last ran to the current time

public setLastJob(IJob $job) : void
Parameters
$job : IJob
Tags
since
7.0.0

setLastRun()

set the lastRun of $job to now

public setLastRun(IJob $job) : void
Parameters
$job : IJob
Tags
since
7.0.0

unlockJob()

Remove the reservation for a job

public unlockJob(IJob $job) : void
Parameters
$job : IJob
Tags
since
9.1.0

        
On this page

Search results