User Tools

Site Tools


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.



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


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.


Logging is provided by

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


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


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)


Zeroed in startPage, incremented after processRow.


Zeroed in startRun, incremented after processRow.


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


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


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


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.


TRUE to perform actions. False to log actions only.



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


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).


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


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.


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:


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.


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']


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.


Initial value for form display before user input.


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


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

The data item must be in data or batch.


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


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.


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.


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.


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


Expected to return an array or false.


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


Called once for each row returned by getRows.


After all rows have been processed.


At end of page. Coming back for another.


Default is to increment batch iPageOffset by batch iPageSize.


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.


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 job data. Default is to do this at startRun and startPage.


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


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


Optional list of parameters you want adminCP to accept.


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