2010-12-24 17:52:03 +02:00
|
|
|
# Minion
|
|
|
|
|
2010-12-31 14:39:37 +02:00
|
|
|
*NOTE: Minion is currently in a beta state, please report any issues in the issue tracker*
|
|
|
|
|
2010-12-30 06:08:32 +02:00
|
|
|
Minion is a module for the Kohana framework which makes it easier to run various tasks from the cli.
|
2010-12-24 17:52:03 +02:00
|
|
|
|
2010-12-30 06:08:32 +02:00
|
|
|
The original "need" behind Minion was the lack of a good db migrations system, capable of selecting migrations
|
|
|
|
from multiple locations (i.e. different modules).
|
2010-12-28 07:24:04 +02:00
|
|
|
|
2010-12-30 06:08:32 +02:00
|
|
|
The system is inspired by ruckusing, which had a nice system for defining tasks but lacked the desired flexibility.
|
2010-12-28 07:24:04 +02:00
|
|
|
|
2010-12-30 06:21:54 +02:00
|
|
|
## Requirements
|
|
|
|
|
|
|
|
* [kohana-database](https://github.com/kohana/database)
|
|
|
|
|
|
|
|
## Compatability
|
|
|
|
|
|
|
|
Minion should be compatible with both Kohana 3.0.x and 3.1.x
|
|
|
|
|
2010-12-24 17:52:03 +02:00
|
|
|
## Getting Started
|
|
|
|
|
|
|
|
First off, download and enable the module in your bootstrap
|
|
|
|
|
|
|
|
Then you can run minion like so:
|
|
|
|
|
|
|
|
php index.php --uri=minion/{task}
|
|
|
|
|
|
|
|
To view a list of minion tasks, run
|
|
|
|
|
|
|
|
php index.php --uri=minion/help
|
|
|
|
|
|
|
|
To view help for a specific minion task run
|
|
|
|
|
|
|
|
php index.php --uri=minion/help/{task}
|
|
|
|
|
|
|
|
For security reasons Minion will only run from the cli. Attempting to access it over http will cause
|
2010-12-30 06:08:32 +02:00
|
|
|
a `Kohana_Exception` to be thrown.
|
2010-12-24 17:52:03 +02:00
|
|
|
|
|
|
|
## Writing your own tasks
|
|
|
|
|
|
|
|
All minion tasks must be located in `classes/minion/task/`. They can be in any module, thus allowing you to
|
|
|
|
ship custom minion tasks with your own module / product.
|
|
|
|
|
2010-12-30 06:08:32 +02:00
|
|
|
Each task must extend the abstract class `Minion_Task` and implement `Minion_Task::execute()`.
|
|
|
|
|
2010-12-24 17:52:03 +02:00
|
|
|
See `Minion_Task` for more details.
|
|
|
|
|
|
|
|
## Documentation
|
|
|
|
|
|
|
|
Code should be commented well enough not to need documentation, and minion can extract a class' doccomment to use
|
|
|
|
as documentation on the cli.
|
|
|
|
|
|
|
|
## Testing
|
|
|
|
|
2010-12-30 06:08:32 +02:00
|
|
|
This module is unittested using the [unittest module](http://github.com/kohana/unittest).
|
|
|
|
You can use the `minion` group to only run minion tests.
|
2010-12-24 19:39:11 +02:00
|
|
|
|
|
|
|
i.e.
|
|
|
|
|
|
|
|
phpunit --group minion
|
2010-12-28 07:24:04 +02:00
|
|
|
|
2010-12-30 06:08:32 +02:00
|
|
|
Feel free to contribute tests(!), they can be found in the `tests/minion` directory. :)
|
|
|
|
|
2010-12-28 07:24:04 +02:00
|
|
|
## License
|
|
|
|
|
2010-12-30 06:08:32 +02:00
|
|
|
This is licensed under the [same license as kohana](http://kohanaframework.org/license).
|
|
|
|
|
|
|
|
This project is not endorsed by the Kohana Framework project.
|
2010-12-28 07:24:04 +02:00
|
|
|
|
|
|
|
## FAQ
|
|
|
|
|
|
|
|
### Can't I just create my own controllers instead of creating "tasks"
|
|
|
|
|
|
|
|
Yes, controllers offer just as much control as tasks, however there are a number of advantages to tasks:
|
|
|
|
|
|
|
|
* They can only be run via command line or through code (see note about http)
|
|
|
|
* All the groundwork for interacting with the user on the command line is already in place, you
|
|
|
|
just need to take advantage of it
|
|
|
|
* It provides a uniform way to access and perform tasks on the command line, rather than creating an elaborate
|
|
|
|
collection of controllers while trying to restrict access to them. If you create a module that requires command
|
|
|
|
line interaction then you just ship a minion task with it and users will be able to start using it with minimal
|
2010-12-30 06:08:32 +02:00
|
|
|
setup & configuration
|
2010-12-30 06:21:54 +02:00
|
|
|
|
|
|
|
### Eeew why aren't you using ORM xyz?
|
|
|
|
|
|
|
|
In order to prevent conflicts across installations Minion aims to have as few dependencies as possible.
|
|
|
|
|
|
|
|
### This is awesome! How can I contribute?
|
|
|
|
|
|
|
|
Thanks for wanting to help out, just fork, commit, push, and send a pull request :)
|
|
|
|
|
|
|
|
### UR DOIN IT WRONG
|
|
|
|
|
|
|
|
Sorry you feel that way, it'd be useful if you could create an issue outlining what you think should be changed.
|
|
|
|
|
|
|
|
Please don't PM me with support / feature requests.
|