twzCronChart v1.1.4 2015-10-28
=================================
In this document:
1. Introduction
2. Instantiation
3. Public methods
4. CSS class names
5. Limitations
_________________________________
1. Introduction
_________________________________
twzCronChart is a PHP5 class that shows a simple Gantt chart of cron tasks,
by parsing the crontab to extract task and scheduling information. The class
also provides methods to retrieve the number of cron tasks, the cron line
for each task, and the next or last date for any task.
Nothing is echoed by the class. This makes it easier for you to manipulate
any output to your liking before sending it to the browser (or where ever).
dev@tweezy.net.au
_________________________________
2. Instantiation
_________________________________
After including the class, simply create a new instance like this:
$cron = new twzCronChart();
This will read and parse your crontab (obtained by executing "crontab -l").
Alternatively, you can read a crontab from elsewhere and pass it to the class
as a string or array using PHP's file_get_contents() or file() function:
$MyCron = file('../path/mycron.cron');
$cron = new twzCronChart($MyCron);
_________________________________
3. Public methods
_________________________________
->Chart - generate a cron chart
-------------------------------
This is main purpose of the twzCronChart class; it returns the html for a
gantt chart, or boolean false on error. Before calling this method, you can
set various options with other methods, eg SetChartName(), SetTaskNames().
You can style the chart to suit your preferences using CSS.
Parameters:
FromDate ...... string or int representing the first date for the chart
(default 'now')
ToDate ........ string or int representing the last date for the chart
(default '+5 days')
MainWidth ..... approximate pixel width for the chart body (not including
task names). The actual pixel width will vary, depending
on the other parameters (default 750).
You can optionally set a scrollable viewport to fit a
wide display into a small screen by passing a string value
in the form 'mainwidth>portwidth'; for example '1200>650'
will create a 1200px width timeline, which is scrollable
inside a 650px container.
StepMinutes ... the number of minutes for each step in the interval between
FromDate to ToDate (default 60)
Headings ...... array with 2 elements; the date/time format for headings,
and the number of minutes between headings.
eg array('H:i', 4*60) shows hr:min heading every 4 hours
Ref: http://php.net/manual/en/function.date.php
(default false; no headings)
Example: echo $cron->Chart('now', '+1 week');
->SetChartName - set the chart title
--------------------------------------------------------
Parameter: ChartName (default '')
->SetDateFormat - set the display format for dates
--------------------------------------------------------
Sets the format of displayed dates
Parameter:
DateFormat .... format string compatible with PHP's date function,
including year, month, day, hour and minute.
Ref: http://php.net/manual/en/function.date.php
(default 'j M Y H:i')
->SetTaskNames - set friendly names for tasks
--------------------------------------------------------
Set a name for each task, based on a unique part of the command (or
in fact the entire crontab line). You can also set the name for a
specific task number by specifying its index. Without names set,
tasks will be called Task 1, Task 2, etc
Parameter
Names ......... an array of names, indexed by id or search string
(default empty array)
Example: $cron->SetTaskNames( array('twzFW.php'=>'FileWatch', 3=>'Third task') );
->SetTaskDurations - set estimated duration for tasks
--------------------------------------------------------
For tasks that take a long time to run, you can specify the estimated
duration and this will be indicated on the chart.
Parameter
Times ......... an array of times, indexed by id or search string
(similar to the SetTaskNames() parameter).
Values can be minutes (int or string), or a string
specifying hours and minutes
Example: $cron->SetTaskDurations( array('twzFW.php'=>'12', 3=>'1:20') );
->GetNextRun - get the date of the next run for a task
->GetLastRun - get the date of the previous run for a task
--------------------------------------------------------
These methods return a string containing the next/previous scheduled run
date for a specific task, or false on error.
Parameters:
Task ......... The name or numeric Id of the task to query (required)
FromDate ..... The date from which to start searching (default 'now')
Example: $NextDate = $cron->GetNextRun(2);
->GetTaskNames - get task names
--------------------------------------------------------
Returns an array of task names indexed by TaskId
Parameters: none
Example: $Tasks=$cron->GetTaskNames(); print_r($Tasks);
->GetTaskCrons - get cron line for all tasks
--------------------------------------------------------
Returns an array of task cron lines indexed by TaskId
Parameters: none
Example: $Tasks=$cron->GetTaskCrons(); print_r($Tasks);
->GetMailto - get cron mailto address
--------------------------------------------------------
If an email address was set in the crontab, this method returns it.
Parameters: none
->GetErrors - get list of any errors
--------------------------------------------------------
Returns an array of any errors encountered.
Parameters: none
->SetSwitchLimit - choose searching algorithm (ADVANCED)
--------------------------------------------------------
Sets the value of SwitchLimit to determine which search algorithm to use
when creating a Chart. When building the chart, twzCronChart steps from
FromDate to ToDate in units of StepMinutes (see Chart method). When
StepMinutes is more than 1 (ie almost always), there's a possibility that
we step over the exact time of a scheduled run. Therefore for each step,
twzCronChart needs to see if a scheduled run has been missed. There are two
different algorithms for doing this.
(1) The first method steps back in time by 1 minute increments, checking
each time in turn. This method is efficient for smaller intervals.
(2) The second method uses GetLastRun() - it finds the latest run date
prior to the current step, then checks if it's after the previous step.
This is more efficient for larger intervals.
Which algorithm is used depends on the number of seconds between steps,
and the choice is determined by the value of SwitchLimit. The best value
to use can depend on various things, including the Chart interval and step,
as well as the nature of the crontab. Let me know if you find a formula for
setting the best SwitchLimit! I think 60 times the chart StepMinutes (ie
StepMinutes converted to seconds) seems to work well most of the time.
Parameters:
SwitchLimit ..... SwitchLimit in seconds (default 60*60*24 = 1 day)
LogSwitchLimit .. If true, twzCronChart will populate the Errors array
with the decision made for each step, and the total
elapsed time to build the chart. This information can
be retrieved from $cron->GetErrors() and you can use
it for fine-tuning the SwitchLimit. (default false)
_________________________________
4. CSS class names
_________________________________
twzCronChart adds a number of class names to the HTML elements it generates.
These class names can be used to style the chart to suit your preferences.
See the included example script for some ideas. The main classes of interest
are:
.sched span.run - when a task starts
.sched span.inprog - while a task is in progress (see SetTaskDurations)
.sched span.mon - start of new month
.sched span.day - start of new day
.sched span.hour - start of new hour
.sched span.now - current date/time
If you don't want any special styling for any of these, remove them from your
stylesheet or set their style the same as the default .sched span
_________________________________
5. Limitations
_________________________________
For people with only a few cron tasks, each with a simple schedule (ie people
like me), twzCronChart will handle everything you throw at it. However with
a large number of tasks and/or a long charting period, it's likely to
struggle a bit. The SetSwitchLimit() method can be used to tweak performance
to some extent.
NOTE: Wikipedia gives two conflicting versions of how Day and Weekday values are
treated (Aug 2011). The "cron" article says that if both of these are specified,
then either one can match. For example day=3 with weekday=1 will match the
3rd day of every month and every Monday, even if it's not Monday the 3rd.
In contrast, the "CRON expression" article says it's not valid to specify
both, and you should use a ? character for one of them. The latter article
also mentions two additional fields: Seconds (mandatory) and Year (optional),
as well as special characters L, W and #.
We have assumed (from some reading of wiki talk pages) that "CRON expression"
is more of a cron extension used elsewhere, but not by cron itself. Therefore
we have used the "cron" article, and ignored "CRON expression".
|
Download
