User Tools

Site Tools


products:stewjob:jobdetails

How to build your own job

Easiest to browse existing jobs and start by copying (cloning) one that is close to what you want.

There are almost no requirements.

A bare bones job has a class name and two methods: getRows and processRow().

Everything else may be used/added as you wish. We detail the options on this page.

Properties

$db

The phpfox database service is available as public property of the job.

$data

Any data you wish to persist between page refreshes.

You should provide a method called initData to return a standard class containing the properties to persist.

Note 1: You can use ordinary class properties in your job too, they jus wont be persistent.

Note 2: If you want to obtain initial values for data from the admin user, and/or just display them as a result of the run, you configure that behaviour in the getFieldDefs method.

$log

Logging is provided by https://github.com/Seldaek/monolog

NB Our convention for stewjob is:

DEBUG dump batch control and data at start and end of each page/run.
INFO what would happen if bFix was true.
NOTICE what did happen because bFix was true.
ERROR unexpected conditions

$batch

You do not normally need to play with batch properties. These control paging and refreshing.

$jobman

Miscellaneous services for jobs

Batch Control

Batch control variables are managed by stewjob by default. But can be overridden by the job.

iPageSize (limit)

Number of rows per page. This can make a big difference to how long your job will run.

iPageOffset (offset)

Starting offset for query. eg SELECT… LIMIT($this→batch→iPageOffset, $this→batch→iPageSize)

iRowCount

Zeroed in startPage, incremented after processRow.

iTotalCount

Zeroed in startRun, incremented after processRow.

iFixCount

Zeroed in startRun. Up to the job to use it or not.

iErrorCount

Zeroed in startRun. Up to the job to use it or not.

iDeletedCount

Zeroed in startRun. Up to the job to use it or not.

iInternalDeletedRowCounter

Zeroed at startPage. If the job increments this for every row deleted, stewjob will produce correct paging even as rows are deleted during processing.

See Job paging for a detailed explanation.

bFix

TRUE to perform actions. False to log actions only.

logLevel

DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY

DEBUG dump batch control and data at start and end of each page/run.
INFO what would happen if bFix was true.
NOTICE what did happen because bFix was true.
ERROR unexpected conditions

run_mode

Deprecated or not used yet. Testing for sapi is sufficient for now

How was the job launched?

  • admin - from the adminCP.
  • cron - from the local system cron tab
  • web - from and external cron service provider
  • term - from the command line

In each case different resources are available (or unavailable).

state

Deprecated or not used yet. This is more for cron jobs.

A job is READY, WAITING, or RUNNING.

start/end time/user

For information purposes. When the job started and stopped, who ran the job.

Job Data

Anything in job data is preserved between pages and runs. It is up the the job to manage it.

If your job needs private/protected/internal variables, declare and use them normally. Use data only when you want a value to persist between pages.

BATCH control is about housekeeping for all jobs.

DATA is particular to the job.

If DATA is set by the user, it needs a FieldDef entry, and you may rely on stewjob to place the property and value in your data section.

If you want to display DATA at the end of a run, without bothering to define input fields, use our data to create a string in getResults.

What is data? Just a aggregate property. stewjob will serialize it as an array.

FieldDefs

getFieldDefs must return an associative array to define how any data may be displayed as a result from the run, or obtained from the adminCP user as a parameter.

The key is a unique field name (identifier).

Any or all of the following entries may be present:

phrase

The field name (label) for display in adminCP. This is not translated, use it to bypass languages and phrases, just hard-code for your own people.

phrase_key

The field name (label) for display in adminCP. Use for sites that support stewjob in other languages.

When a phrase_key is given it will be used instead of phrase. If neither are given the variable name will be used.

EG echo Phpfox::getPhrase($job['phrase_key') vs echo $job['phrase']

type

display, text, select, multiselect, radio, checkbox, date.

Additionally an options array where appropriate (radio, checkbox, select, multiselect).

These were cloned form the custom field module. Same deal.

value

Initial value for form display before user input.

valid

Optional closure to validate user entry in adminCP. Must return TRUE or error message.

result

Indicates the data item is to be displays in the “Results from last run” section.

The data item must be in data or batch.

from

When a field is given as a result, this must be set to “batch” or “data”.

Methods

All of these methods are optional except getRows and processRow.

They provide the hooks you may need for your job.

Refer to stewjob the base class implementation, you may want to call the parent method.

initRun

When the job is constructed for a run. Consider it a constructor.

Jobs may be instantiated in adminCP, so you may need to keep startup code outside the constructor. We instantiate the logger in initRun rather than the constructor.

startRun

Once only at the start of a job.

A job can last across any page loads, or run as cron forever.

The start of a job is defined and controlled by job_state.

startPage

When the job is loaded to process a page of data.

getRows

Expected to return an array or false.

endRun

When all pages are complete. This is your last chance to set any results or clean up.

processRow

Called once for each row returned by getRows.

endRows

After all rows have been processed.

endPage

At end of page. Coming back for another.

incrementPageOffset

Default is to increment batch iPageOffset by batch iPageSize.

getNextPageUrl

Default depend on run_mode. From adminCP this generates a javascript form.submit() so that your job is reloaded for the next page of data.

wantNextPage

Returns true or false. We'll either end the page or the run, as you wish ;)

The default is to return true when the batch row count is equal to the batch batch size (all rows processed).

load

Load job data. Default is to do this at startRun and startPage.

save

Save job data. Default is to do this at endPage and endRun.

getTitle

If not supplied we'll use your class name. You should give a short description for admin users.

getFieldDefs

Optional list of parameters you want adminCP to accept.

initData

Return a standard class with properties and values for the construction of data.

products/stewjob/jobdetails.txt · Last modified: 2015/06/02 10:05 by steward