Introduction
this Article is meant to give you a short overview on how to extend the king23 command
line tool within your application
it assumes that you have read
http://devedge.wordpress.com/2010/05/29/king23-getting-started/
To demonstrate a few things that can be done with the King23 tasks,
we will fetch some data from this blog, and display the headlines in the command line.
The Task
If you run the king23 command line tool, it will allways check the current path
for a subdirectory named “tasks”, and if that one exists add it to the King23 autoloader.
it will then make a list of all files that end with “_Task.php”, assuming that everything
before _Task.php is the name of the task module.
if you used the King23:create_project task, then you allready have a task module named “EXAMPLE”
in your tasks folder (EXAMPLE_Task.php)
A task module is a class with the same name as the file
(in the case of the existing module, the classname is EXAMPLE_Task.php).
task modules should allways be derived from King23_CLI_Task, since that one provides
basic functionality like the info task, and access to the documentation array of the module,
however it is possible to make task modules that are not derived.
For our tutorial, we are going too create an own module named MyApp,
so the filename is tasks/MyApp_Task.php
our task module extends King23_CLI_Task
class MyApp_Task extends King23_CLI_Task
The next thing we do is that we overload King23_CLI_Tasks protected member $tasks, and fill it
with informations on our own tasks
protected $tasks = array(
"info" => "General Informative Task", // this is a buildin Task to King23_CLI_Task and available in all Tasks
"fetch_data" => "fetch the data from the url that needs to be given as a parameter", // describing our task
);
The info task needs to know about the name of the module,
so we overload the protected $name member aswell:
protected $name = "MyApp"; // this is used by the info task
now the next part is where the fun happens,
all actual tasks are methods on a task module object, and take an array as parameter,
this array gets filled with all parameters that follow after a method call.
king23 MyApp:imaginarytask one two three
would call a method named “imaginarytask”, handing over an array containing the elements “one”, “two”, and “three”.
since we want to fetch from an url which is given as a parameter,
probably the first thing we want todo is check if the right amount of parameters is given,
and if not print out an error and end the run.
since we extend King23_CLI_Task, we have an instance of King23_CLI as a member of the current object,
which allows us a conveniant way of printing out different types of messages:
- header($message)
for printing out a header (bold/brighter)
- message($message)
for pretty much all sorts of messages
- warning($message)
for warnings
- error($message)
for errors
- positive($message)
success/ok message
all those will print out what ever we tell it to print out, but each of them will color the line a bit different.
Also, each of them will prefix the output with a current timestamp.
after we ensured that the amount of parameters is correct, we call
the method “execFetch($params[0])” to make the actuall fetch.
i wont describe that method in detail, its just a quick (and dirty)
fetch of a rss file, reading all titles and returning those as an array.
this is not a good way todo it, i ignore all error handling, but it will
do for the example. The implementation of said method is in the
complete script, which you can find at the bottom of this article.
we will print a header and then iterate over the titles,
and output them one by one:
public function fetch_data(array $params)
{
if(count($params) != 1)
{
$this->cli->error("wrong amount of parameters given, this task takes exactly one.");
return;
}
$data = $this->execFetch($params[0]);
$this->cli->header("The titles for " . $params[0]);
foreach($data as $title)
$this->cli->message($title);
return;
}
this pretty much concludes this small tutorial
the complete script
<?php
class MyApp_Task extends King23_CLI_Task
{
/**
* this member should list all tasks that are available through this task module
* and give a short documentation for the help at commandline
* @var array
*/
protected $tasks = array(
"info" => "General Informative Task", // this is a buildin Task to King23_CLI_Task and available in all Tasks
"fetch_data" => "fetch the data from the url, takes an url as parameter", // describing our task
);
/**
* Name of the module
*/
protected $name = "MyApp"; // this is used by the info task
public function fetch_data(array $params)
{
if(count($params) != 1)
{
$this->cli->error("wrong amount of parameters given, this task takes exactly one.");
return;
}
$data = $this->execFetch($params[0]);
$this->cli->header("The titles for " . $params[0]);
foreach($data as $title)
$this->cli->message($title);
}
private function execFetch($url)
{
$data = join('', file($url));
$xml = new SimpleXMLElement($data);
foreach($xml->channel->item as $item)
$titles[] = $item->title;
return $titles;
}
}
