Skip to content

Latest commit

 

History

History
121 lines (83 loc) · 4.98 KB

vision.md

File metadata and controls

121 lines (83 loc) · 4.98 KB
Raw

Project Vision

This document is intended for developers to understand the flow of the module and be able to help out with its development. Features and usage may change before its release.

Task Types

Tasks are scheduled within the config file, Config\Tasks.php, within the init() method:

public function init(Scheduler $schedule)
{
	$schedule->command('foo:bar')->nightly();
}

There are 5 types of tasks:

  1. Commands. These are CLI commands that are defined by the name defined within their file, like migrate:create.
	$schedule->command('foo:bar')->nightly();
  1. Shell commands. These are passed to the system through exec() or shell(). Need to determine what makes sense here.
	$schedule->shell('cp foo bar')->daily()->at('11:00 pm');
  1. Closures. Anonymous functions can be used to define the action to take, also.
	$schedule->call(function() { 
		// do something.... 
	})->mondays();
  1. Events. These trigger pre-defined framework Events which allows for more dynamic actions to take place from a single Task.
	$schedule->event('reminders')->weekdays()->at('9:00 am');
  1. URL. These access a remote URL and are handy for interacting with other APIs or coordinating tasks across servers.
	$schedule->url('https://example.com/api/sync_remote_db')->environments('production')->everyTuesday(););

Note that URL Tasks perform a simple GET request; should you need more involved remote calls (like authentication) they should be written into a separate command.

Scheduling Tasks

Tasks are scheduled via fluent commands that allow chaining commands together. Some examples of available methods would be:

  • cron('/5 * * * *'') specifies the exact cron syntax to use.
  • daily() which runs every day at midnight. Optionally pass a time as the only argument, ie. 04:00 am
  • weekdays() runs M-F at midnight. Optionally pass a time as the only argument, ie. 04:00 am
  • weekends() runs on Saturday and Sunday at midnight. Optionally pass a time as the only argument, ie. 04:00 am
  • mondays() runs every Monday at midnight. Optionally pass a time as the only argument, ie. 04:00 am
  • everyMinute(), everyFiveMinutes(), allows scheduling some common intervals
  • hourly() runs the task at the top of every hour
  • environments() specifies one or more environments the tasks should run in
  • alias() specifies an alias that the script can be called by, useful when manually running the task.

How CRON interacts with the scheduler

In order to have the scheduler work, a cronjob needs to be setup on the server to run every minute against a command we'll need to create:

* * * * * cd /path-to-your-project && php spark tasks:run

Other classes

The following classes are anticipated to be needed for the main process flow:

TaskRunner is called by the main command and handles actually determining which tasks to run and running all of the commands.

Scheduler is passed into the init() method of the config class and handles generating the crontab formats for all tasks. It houses the commands that are called when scheduling tasks.

Task represents a single task that should be scheduled. These are generated by the Scheduler and passed to the TaskRunner when they're ready to be run.

CronExpression understands how to interpret a raw crontab expression (* * * * *) and determine if the task should run now, as well as provide future/past dates it would run.

Commands

In addition to the core functionality, the following features will be availble by commands to help developers:

tasks:run foo:bar an optional flag, --task can be set to define a single task that should be run right now. It can take either the name of a command one is associated with, or by the alias defined in the setup.

tasks:list generates a table with all tasks and the last and next times it is scheduled to run

tasks::disable can disable a job from running until tasks:enable is called on it again. Useful on production servers when something is going wrong. Likely stores a json file in /writable to maintain state

tasks::performance generates a table to display performance information about all of the last runs. See https://github.com/codestudiohq/laravel-totem for inspiration, though we're doing it on the CLI.

Notifications

The schedular should also provide a few different ways to return information about the jobs. I envision the following methods to start:

logs - simply logs the runtime and performance information. Would be nice to do this in a separate log file.

email - can notify one of more people of the performance of a single task, or a daily summary of all tasks at a specified time of day. This would basically be a provided cron task that could be scheduled. So - would need a command. Should display list of tasks ran, the time they ran, whether there were errors or not, and performance information.