job_functions.php
Table of Contents
Functions
- job_queue_add() : string|int
- Adds a job to the job_queue table.
- job_queue_update() : void
- Update the data/status/time of a job queue record.
- job_queue_delete() : void
- Delete a job queue entry if user owns job or user is admin
- job_queue_get_jobs() : mixed
- Gets a list of offline jobs
- job_queue_get_job() : array<string|int, mixed>
- Get details of specified offline job
- job_queue_purge() : void
- Delete all jobs in the specified state
- job_queue_run_job() : string
- Run offline job
- get_job_type_priority() : int
- Get the default priority for a given job type
- get_job_queue_log_path() : string|false
- Build and ensure a writable log file path for a queued job
- get_job_queue_log_path_by_ref() : string|false
- Resolve a queued job reference to its corresponding log file path
- get_job_progress_from_log_file() : array<string|int, mixed>
- Scan a log file from the end and return the most recent line matching a pattern.
- job_trigger_permission_check() : bool
- Determine whether the current user is allowed to manually trigger background jobs.
- triggerable_job_check() : bool
- Determine whether a job type is user triggerable.
Functions
job_queue_add()
Adds a job to the job_queue table.
job_queue_add([string $type = "" ][, array<string|int, mixed> $job_data = array() ][, string $user = "" ][, string $time = "" ][, string $success_text = "" ][, string $failure_text = "" ][, string $job_code = "" ][, int $priority = null ]) : string|int
Parameters
- $type : string = ""
- $job_data : array<string|int, mixed> = array()
- $user : string = ""
- $time : string = ""
- $success_text : string = ""
- $failure_text : string = ""
- $job_code : string = ""
- $priority : int = null
Return values
string|int —ID of newly created job or error text
job_queue_update()
Update the data/status/time of a job queue record.
job_queue_update(int $ref[, array<string|int, mixed> $job_data = array() ][, string $newstatus = "" ][, string $newtime = "" ][, mixed $priority = null ]) : void
Parameters
- $ref : int
- $job_data : array<string|int, mixed> = array()
-
- pass empty array to leave unchanged
- $newstatus : string = ""
- $newtime : string = ""
- $priority : mixed = null
job_queue_delete()
Delete a job queue entry if user owns job or user is admin
job_queue_delete(mixed $ref) : void
Parameters
- $ref : mixed
job_queue_get_jobs()
Gets a list of offline jobs
job_queue_get_jobs([string $type = "" ][, string $status = -1 ][, int $user = "" ][, string $job_code = "" ][, string $job_order_by = "priority" ][, string $job_sort = "asc" ][, string $find = "" ][, bool $returnsql = false ][, int $maxjobs = 0 ][, bool $overdue = false ][, array<string|int, mixed> $find_by_job_ref = [] ]) : mixed
Parameters
- $type : string = ""
-
Job type, can be a comma separated list of job types
- $status : string = -1
-
Job status - see definitions.php
- $user : int = ""
-
Job user
- $job_code : string = ""
-
Unique job code
- $job_order_by : string = "priority"
-
Column to order by - default is priority
- $job_sort : string = "asc"
-
Sort order - ASC or DESC
- $find : string = ""
-
Search jobs for this string
- $returnsql : bool = false
-
Return raw SQL
- $maxjobs : int = 0
-
Maximum number of jobs to return
- $overdue : bool = false
-
Only return overdue jobs?
- $find_by_job_ref : array<string|int, mixed> = []
-
Find queued jobs by their ref
Return values
mixed —Resulting array of requests or an SQL query object
job_queue_get_job()
Get details of specified offline job
job_queue_get_job(mixed $ref) : array<string|int, mixed>
Parameters
- $ref : mixed
Return values
array<string|int, mixed>job_queue_purge()
Delete all jobs in the specified state
job_queue_purge([int $status = 0 ]) : void
Parameters
- $status : int = 0
-
to purge, whole queue will be purged if not set
job_queue_run_job()
Run offline job
job_queue_run_job(array<string|int, mixed> $job, bool $clear_process_lock) : string
Parameters
- $job : array<string|int, mixed>
-
Metadata of the queued job as returned by job_queue_get_jobs()
- $clear_process_lock : bool
-
Clear process lock for this job
Return values
string —'Process lock', 'Error' or 'Complete'.
get_job_type_priority()
Get the default priority for a given job type
get_job_type_priority([string $type = "" ]) : int
Parameters
- $type : string = ""
-
Name of job type e.g. 'collection_download'
Return values
intget_job_queue_log_path()
Build and ensure a writable log file path for a queued job
get_job_queue_log_path([string $type = "" ][, string $job_code = "" ][, string $job_ref = "" ]) : string|false
Parameters
- $type : string = ""
-
Job category or queue type used as a subdirectory name
- $job_code : string = ""
-
Job identifier used in the log filename
- $job_ref : string = ""
-
Job reference value used in the log filename
Return values
string|false —Full path to the log file on success, or false on failure
get_job_queue_log_path_by_ref()
Resolve a queued job reference to its corresponding log file path
get_job_queue_log_path_by_ref([int $job_ref = 0 ]) : string|false
Parameters
- $job_ref : int = 0
-
Job reference
Return values
string|false —Full path to the job log file on success, or false on failure
get_job_progress_from_log_file()
Scan a log file from the end and return the most recent line matching a pattern.
get_job_progress_from_log_file([string $path = "" ][, string $pattern = "/\\[PROGRESS\\]/i" ][, int $block_size = 65536 ]) : array<string|int, mixed>
The file is read in fixed-size blocks starting from EOF and scanned backwards line-by-line for the first line that matches the supplied regular expression (by default, lines containing "[PROGRESS]").
On the first read pass, the function also captures the last non-empty line in the file (closest to EOF), regardless of whether it matches the pattern.
Parameters
- $path : string = ""
-
Path to the log file to scan
- $pattern : string = "/\\[PROGRESS\\]/i"
-
Regular expression used to match progress lines
- $block_size : int = 65536
-
Number of bytes to read per backward scan iteration
Return values
array<string|int, mixed> —found: string|null The most recent line matching $pattern, or null if none found or if the file could not be read last_line: string|null The last non-empty line in the file, or null if unavailable
job_trigger_permission_check()
Determine whether the current user is allowed to manually trigger background jobs.
job_trigger_permission_check() : bool
The system must have config $offline_job_queue set to true and the user must have 'a', 'f*', 't' and 'v' permissions as well as edit access to all workflow states.
Return values
bool —true if the user satisfies all required permissions and workflow access, false otherwise
triggerable_job_check()
Determine whether a job type is user triggerable.
triggerable_job_check([string $type = "" ]) : bool
This can stop system jobs from creating unnecessary log files.
Parameters
- $type : string = ""
Return values
bool —true if job is user triggerable, so logging is allowed