Browse files

Add some start to documentation for minion. Refs #3989

  • Loading branch information...
1 parent 18468df commit dcc1df3e60faf9e0f9a5d7ed391e4aba555c8e35 @zombor zombor committed Jan 11, 2012
Showing with 123 additions and 1 deletion.
  1. +5 −1 classes/minion/task/demo.php
  2. +13 −0 config/userguide.php
  3. +3 −0 guide/minion/index.md
  4. +3 −0 guide/minion/menu.md
  5. +32 −0 guide/minion/setup.md
  6. +67 −0 guide/minion/tasks.md
View
6 classes/minion/task/demo.php
@@ -1,6 +1,10 @@
<?php defined('SYSPATH') or die('No direct script access.');
/**
- * Demo task. Will delete this.
+ * This is a demo task.
+ *
+ * It can accept the following options:
+ * - foo: this parameter does something. It is required.
+ * - bar: this parameter does something else. It should be numeric.
*
* @package Kohana
* @category Helpers
View
13 config/userguide.php
@@ -0,0 +1,13 @@
+<?php
+
+return array
+(
+ 'modules' => array(
+ 'minion' => array(
+ 'enabled' => TRUE,
+ 'name' => 'Minion',
+ 'description' => 'Minion is a simple command line task runner',
+ 'copyright' => '&copy; 2009-2011 Kohana Team',
+ )
+ )
+);
View
3 guide/minion/index.md
@@ -0,0 +1,3 @@
+# Minion
+
+Minion is a simple command line task runner.
View
3 guide/minion/menu.md
@@ -0,0 +1,3 @@
+## [Minion]()
+ - [Setup](setup)
+ - [Writing a Task](tasks)
View
32 guide/minion/setup.md
@@ -0,0 +1,32 @@
+# Minion Setup
+
+To use minion, you'll need to make a small change to your index.php file:
+
+ -/**
+ - * Execute the main request. A source of the URI can be passed, eg: $_SERVER['PATH_INFO'].
+ - * If no source is specified, the URI will be automatically detected.
+ - */
+ -echo Request::factory()
+ - ->execute()
+ - ->send_headers(TRUE)
+ - ->body();
+ +if (PHP_SAPI == 'cli') // Try and load minion
+ +{
+ + class_exists('Minion_Task') OR die('minion required!');
+ + set_exception_handler(array('Kohana_Minion_Exception_Handler', 'handler'));
+ +
+ + Minion_Task::factory(CLI::options())->execute();
+ +}
+ +else
+ +{
+ + /**
+ + * Execute the main request. A source of the URI can be passed, eg: $_SERVER['PATH_INFO'].
+ + * If no source is specified, the URI will be automatically detected.
+ + */
+ + echo Request::factory()
+ + ->execute()
+ + ->send_headers(TRUE)
+ + ->body();
+ +}
+
+This will short-circuit your index file to intercept any cli calls, and route them to the minion module.
View
67 guide/minion/tasks.md
@@ -0,0 +1,67 @@
+# Writing Tasks
+
+Writing a task in minion is very easy. Simply create a new class called `Minion_Task_<Taskname>` and put it inside `classes/minion/task/<taskname>.php`.
+
+ <?php defined('SYSPATH') or die('No direct script access.');
+
+ class Minion_Task_Demo extends Minion_Task
+ {
+ protected $_config = array(
+ 'foo',
+ 'bar',
+ );
+
+ /**
+ * This is a demo task
+ *
+ * @return null
+ */
+ protected function _execute(array $params)
+ {
+ var_dump($params);
+ echo 'foobar';
+ }
+ }
+
+You'll notice a few things here:
+
+ - You need a main `_execute()` method. It should take one array parameter.
+ - This parameter contains any command line options passed to the task.
+ - For example, if you call a task with `./minion --task=demo --foo=foobar` then `$params` will contain: `array('foo' => 'bar')`
+ - It can optionally have a `protected $_config` array. This is a list of parameters you want to accept for this task. More on this below.
+
+# Parameter Validations
+
+To add validations to your command line options, simply overload the `build_validation()` method in your task:
+
+ public function build_validation(Validation $validation)
+ {
+ return parent::build_validation($validation)
+ ->rule('foo', 'not_empty') // Require this param
+ ->rule('bar', 'numeric'); // This param should be numeric
+ }
+
+These validations will run for every task call unless `--help` is passed to the task.
+
+# Task Help
+
+Tasks can have built-in help. Minion will read class docblocks that you specify:
+
+ <?php defined('SYSPATH') or die('No direct script access.');
+
+ /**
+ * This is a demo task.
+ *
+ * It can accept the following options:
+ * - foo: this parameter does something. It is required.
+ * - bar: this parameter does something else. It should be numeric.
+ *
+ * @package Kohana
+ * @category Helpers
+ * @author Kohana Team
+ * @copyright (c) 2009-2011 Kohana Team
+ * @license http://kohanaframework.org/license
+ */
+ class Minion_Task_Demo extends Minion_Task
+
+The `@` tags in the class comments will also be displayed in a human readable format. When writing your task comments, you should specify how to use it, and any parameters it accepts.

0 comments on commit dcc1df3

Please sign in to comment.