README

The intent of this module is to provide a quick way for other modules to schedule one-time, async jobs on the server, without the need to create specific crons, and quickly check the result of such jobs. The module also supports retrieving files from the launched command, making it a simple way to generate exports (such as .csvs) without locking other threads or timing out the page.

Configuration

Add the package to your composer.json:

"elitedivision/taskmanager": "dev-master",

Add the module configuration to your app’s common/config/modules-amos.php:

$modules['taskmanager'] = [
'class' => 'elitedivision\amos\taskmanager\TaskManager',
];

Add the following line to your app’s console/config/bootstrap.php:
```
$bootstrap[] = 'taskmanager';
```
Add migrations to the console in console/config/migrations-amos.php:
```
'@vendor/elitedivision/taskmanager/src/migrations'
```
Add one cron for each channel you want to use for the Task Manager, in your crontab or equivalent software:
- * * * * * yii taskmanager/scheduler (Default; will create a task manager for channel 1)
- * * * * * yii taskmanager/scheduler --channel=2 (Will create a task manager for channel 2)
- ... etc.

Module parameters

tmpDir - Temporary folder to use. If not set, the return value for sys_get_temp_dir() will be used.

Usage:

$modules['taskmanager'] = [
	'class' => 'elitedivision\amos\taskmanager\TaskManager',
	'tmpDir' => '/tmp'
];

Usage

New Scheduled Job

To create a new job, use the following method of the module object.

scheduleJob($command, $module, $output, $data, $channel)

Parameters

Name	Type	Required	Default	Description
`$command`	`string`	yes	none	The controller/action combination to launch as a job. It must be executable from the console. Absolute path should be given.
`$module`	`string`	no	`'amos_task_manager'`	The name of the module adding the job to the Task Manager. Used mainly for statistics; still, it is good practice to specify a custom value.
`$output`	`boolean`/`string`	no	`null`	If set to `true`, the Task Manager will automatically create a filename with a randomly generated UUID, and such path will be passed to the job as the `--filename` command line argument. If set as a string, this will be passed instead. If `null`, no `--filename` argument will be passed to the command.
`$data`	`string`	no	`null`	Additional data which will be passed to the job as the `--data` command line argument. It will be encoded as JSON to allow passing structured data objects; therefore it will have to be manually decoded with `json_decode()` in the command. If `null`, no `--data` argument will be passed to the command.
`$channel`	`int`	no	`1`	The channel to use on the Job Execution. Jobs on the same channel will be executed one by one in their insertion order. To execute concurrent jobs, set them on different channels.

Returns

int The Job ID if successful.

Will throw an error if something went wrong.

Examples

Create a Task Job with the command commandcontroller/action, without output and on channel 2:
```
$module = \Yii::$app->getModule('taskmanager');
$jobId = $module->scheduleJob('commandcontroller/action', 'calling_module', null, null, 2);
```
This will result in calling the console command on the first available occasion on channel 2:
```
commandcontroller/action
```

Create a Task Job with the command commandcontroller/action, letting the Task Manager handle the filename, and passing additional data:

$module = \Yii::$app->getModule('taskmanager');
$jobId = $module->scheduleJob(
'commandcontroller/action',
'calling_module',
true,
[
	'additionalParameters' => [
		'parameter1',
		'parameter2'
	]
]);

This will result in calling the console command on the first available occasion on channel 1:

commandcontroller/action --filename=/var/tmp/4b3403665fea6 --data='{'additionalParameters':['parameter1','parameter2']}'

Retrieve Job Details

To retrieve job details from the ID returned from scheduleJob(), use the following method on the module object:

getJob($id)

Notes

The called command needs to be set up to handle command line named arguments. Please see Console options and option aliases.