User Tools

Site Tools


products:stewfix

May 2015, this has morphed into a new project…stewjob

stewfix

April 2015: under active development. This info will change

A set of scripts to make writing “quick fix it!” programs easier.

May also be used to provide core functionality for your site.

These can be run once only, on demand, or as cron jobs.

Handles housekeeping, so you can focus on what needs doing.

  • No core edits, no trap doors, source is unencrypted and never phones home.
  • Language ready, uses phrases
  • Avoids loading templates, caching and fox overhead so jobs run quicker
  • Full logging with MonoLog

Installing

Unzip and copy the contents of upload to your site.

If you have never installed a product before, please visit phpfox for details.

Nothing special here. Install like any other add-on.

You may need to create the folder ./file/stewfix (log files)

UnInstalling

Uninstall same as any other product via adminCP.

You may need to remove the folder /file/stewfix (log files)

Settings and Security

She talks scary talk:
All jobs are potential dangerous. Some of them could do major damage. Know what you are doing, or have a professional look it over.
When writing a new job or running it live for the first time, have backups at hand.
Bad things happen. Be prepared.

Most problems will usually be your own bugs ;)

But if staff have access to your admin panel, you may need to protect your site from somebody running a job by accident. It may be harmless, or it may be a job you intended to be run once only!

The normal phpfox admin panel has it's own way of managing access. You may be using that, and so you'll want to update it so that stewfix is available or not.

We also provide settings (detailed below) to prevent given users or IPs from running jobs. But these settings are available in the admin panel and may be changed by staff! So for precious jobs we recommend you place authentication in the code directly.

Also note you can disable a job but keep it around for future use by renaming it (remove .json extension) ie MySweetFix.json.disabled

Allowed IPs

You can find your IP by visiting eg http://www.ipchicken.com/

Enter a list of IPs (one per line).

If the IP is not in the list, the job will not run.

If the list is empty, any IP is allowed.

Allowed user ids

Same as above, but with user_id instead of IP.

To find a user id, edit their record in admincp, and snip it off of the end of the browser address bar. Eg /admincp/user/add/id_999/

Usage

In adminCP, choose Modules > stewfix.

You should see a list of jobs. For each job you may

  • Delete For now, delete the json and php files found in module/stewfix/jobs
  • Edit For now, use any text editor to edit the JSON file.
  • Run it
  • Show the log
  • Clear the log
  • Set as cron job

Find a job

(insert list of available jobs here)

If you don't find what you need, ask at http://scripttechs.com/ forums, or contact us directly.

The great thing about stewfix is that essentials of a small job can be shared by posting in a forum.

That's the downside too. Beware that each job is an opportunity for an evil coder to take control of your system. I would never have thought of it, but they are pretty panicked about it at moxi9, I guess they've had some bad experiences. So herewith the appropriate doomsday warning about trojan horses and unscrupulous developers.

Of course you can always hire another to verify the code before you run it ;)

Creating your own job

The idea is that we can create a job and share them with other foxers.

There are many/potential options.

To start, we want to Keep It Simple. This page outlines the essentials only.

Creating a new fix really is easy: you need only code one select query and whatever processing you need.

Choose a name

Choose a (file) name (key) for your job.

It must be unique, no other jobs may have the same name.

By convention it should contain only upper and lower letters.

For the discussion below, Let us say you choose MySweetFix

If you think you will share your job, the easiest way to avoid a name collision is to include a vendor/site handle to make your job name unique: eg stewardMySweetFix

Create JSON

The easiest way to do this is by cloning an existing job (copy then edit).

Create a JSON file and place it in ./module/stewfix/jobs/MySweetFix.json. The minimal required entry is:

    {
        "name" : "MySweetFix",
        "title" : "A short description of what my sweet fix does"
    }

There are potentially many other options. We have chosen a JSON object to allow different properties in any given job. Add as needed for whatever purpose. The values are available to your job at runtime.

We will document the options in detail later, but for now the only other one you might want is:

    {
        "batch" : {
            "iPageSize" : 200
            }
    }

Page size tells the system how many items to process per page. The default is 20.

This may be important. The actual settings depends on the amount of work your job must do per row, your hardware, your database, the time of day and system load. Etc.

A large value is appropriate when the job runs quickly, it will save the overhead of many page refreshes.

Create class

Create a script with the class to run your fix.

At minimum, you will need to write two methods: getRows and processRow. One to fetch a page (set of rows), another to process a row.

Following our example here, the class must be named MySweetFix, and it must be placed in ./module/stewfix/jobs/MySweetFix.php

The essential skeleton is:

<?php
class MySweetFix extends stewfix
{
    public function getRows()
    {
        /* logic to read a page of items here */
        return $aRows;
    }
    public function processRow($row)
    {
        /* logic to process a single item here */
        return true;
    }
}

getRows

getRows will be called when the job is ready to begin processing. Log files open, parameters obtained etc.

Write a select query. Return $aRows.

$aRows is empty, false or NULL to signal end of input.

Use $this→iOffset and $this→iLimit in your query.

processRow

processRow is called once per item in $aRows, the array returned from getRows().

return false to abort, true to continue.

other methods

The “get and process” outlined above is sufficient for most needs.

But there are always good reasons for needing more!

If your job entails deletions, there are special considerations to keep the batch pages in sequence.

There are logging functions and helper routines.

document them somewhere

Hooks

Using plugins in V3 is a fool's errand unless you intend to upgrade to V4.

We are ready for V4 and support hooks.

  • stewfix_load_job_begin
  • stewfix_load_job_end
  • stewfix_save_job_begin
  • stewfix_save_job_before_write

Notes

Futures

  • Read/write crontab, integrate with stewnotice and stewcron? Re-issue cron manager.
  • Delete job from adminCP
  • Create new job in adminCP
  • Edit params
  • Edit job
  • Re-start job
  • Log display large files in pages with search, instead of dumping to browser
  • Enable/disable from adminCP
  • PDO for foreign database access
  • File system iterators
  • Install product create log dir
  • Remove product remove log dir
products/stewfix.txt · Last modified: 2015/05/05 16:14 by steward