Job Queue Management API

SPIP 3.0 natively integrates a programming interface (or API) for job queue management. It allows to schedule jobs to be executed in the future, or simply as soon as possible but without making the user wait [1].

Scheduled jobs can be viewed at any time in the administration area via the Maintenance > List of tasks menu. The follow-up page allows you to force the immediate execution of a job, or to delete certain jobs.

Adding a job to the queue

  1. $id_job = job_queue_add($function, $description, $arguments = array(), $file = '', $no_duplicate = FALSE, $time=0, $priority=0)

With the arguments:

  • $function: the name of the PHP function to be called
  • $description: a humanly understandable description of what the task does (mainly for display in the private area tracking page)
  • $arguments (optional, empty by default): the arguments that will be passed to the function, in the form of a PHP array
  • $file (facultatif, vide par défaut) : name of the file to include, via include_spip($file) (example: 'inc/mail': you must not indicate .php). If the name ends with a / then it is considered to be a directory and SPIP will execute a charger_fonction($function,$file)
  • $no_duplicate (optional, false by default)
    • if it is true the task will not be added if it already exists in the queue with the same function and arguments.
    • if it is 'function_only' the task will not be added if it already exists in the queue with the same function regardless of its arguments
  • $time (optional, 0 by default) indicates the date in timestamp format at which the task is to be scheduled. If 0 or a date is in the past, the task will be executed as soon as possible (usually at the end hit, asynchronously).
  • $priority (optional, 0 by default) indicates a priority level between -10 and +10. Tasks are executed in descending order of priority once their execution date has passed. Priority is mainly used when a cron task indicates that it has not finished and needs to be restarted : in this case SPIP reduces its priority to make sure that the task does not monopolise the queue.

The function returns the number of the job added or 0 if no job has been added.

Delete a job from the queue

  1. job_queue_remove($id_job)

$id_job is the number of the pending job, as returned by the job_queue_add

The function returns true if the job was indeed found and deleted, false otherwise.

Associating a work with an editorial object

  1. job_queue_link($id_job,$objets)

With the arguments:

  • $id_job: the pending job number, as returned by the function job_queue_add
  • $objets a list of objects in the form of an object table array(array('objet'=>'article','id_objet'=>23),...)

When jobs are associated with an object, they appear on that object’s private area page, and authors who have the right to modify the object can also delete the job before it is executed.

Footnotes

[1These functionalities were available for SPIP 2.1 in the job queue plugin

Author jack Published :

Translations : English, français