Using atkConsoleController for console/shell coding in ATK

From Achievo/ATK Wiki

Writing console / shell scripts with PHP ~ why is this necessary?

Before you begin writing code for your console application or script, think about this: Is it best writing this in PHP within the ATK framework or am I better off writing this in some other language and script ? (e.g. C, Java, crontab, bash, used combined or alone). When you're doing something that takes you close to the brim of PHP userspace, chances are that you have to evaluate the trade-offs carefully against your requirement (i.e. efficiency, speed of development, reliability, etc.) and the line of choice could be quite thin. Nevertheless, PHP's CLI has plenty to offer and there are some distinctive advantages of keeping stuffs within PHP (or ATK in PHP):

• Cross-platform compatibility (in most cases) ~ PHP-only applications can be deployed on any platform without any additional chores. E.g. cron's not in Windows, so crontabs won't work (although there's pycron, but that's dependency you see). This compatibility also depends on some PHP extensions work.

• Preservation of product or platform adoption scope. Sometimes, there are no choice. The project mandates a certain array of platform / languages to be used. This is amazingly important for some development teams/projects.

• Convenience and speed: If you want to conveniently use PHP and more specifically ATK's API to do stuffs (see [1] on the range of possibilities).

Defining the scope of console in this wiki

Just about more than a decade ago, it would be funny to start defining the scope of a chunk of console code, it will be normal to define web applications, there being so many commercial effort to drive this new gale of creative destruction, which continues to this day. But nevertheless, this wiki describes the creation of console based scripts to perform tasks that requires heavier interaction with the server AND lesser interaction with the browser. Tasks such as time-based automation, or even some degree of system administration are good examples. For further details of such tasks, and for a list of scenarios where it will be better to use PHP console scripts than bash or etc., see http://tldp.org/LDP/abs/html/why-shell.html.

Execution components

There are 3 components that is involved in an execution sequence of a console application written within ATK:

What you need to create is ONLY your own <Your>Controller extends atkConsoleController, see below. The three things you'll need to take note of is:

1. How to start the console process and where vital files are located (see section Console.php below).

2. The API available for classes that extends atkConsoleController (see The ATK Console class below).

3. Extending atkConsoleController (see <Your>Controller extends atkConsoleController below).

Console.php

Console.php is packaged under the skel directory. You can copy it to wherever you like but it is best placed in your base directory where your atk is installed (Hint: Find the directory where the atk.inc file resides). If you place console.php in any other directory, you may need to change the include paths within the file.

Once your console.php file is placed correctly, the way to start it is as follows:

 % php console.php [--list] [--debug] modules.<your-module>.console.<your-controller> [yourAction] [param=value ...]

--list when provided, rather than executing the commands in your controller the atkConsoleController will display a list of all available actions.

--debug when provided the $this->info calls in your controller will be display. When left out the messages will only be logged but not displayed.

<your-module> is a mandatory field to supply. It is the name of the ATK module that the console application is part of.

<your-controller> is the class name of the controller class that you had defined (see below). It is not the file name.

The ATK Console class

The atkConsoleController class contains two functions that are helpful in console application / script development:

info()

Useful method for outputting log data to a log file. If you provided --debug during your call, this output will also be displayed live when executing the script. Files will be placed in the ATK temp directory in a subdirectory called console/. Each file will have the following name <controller>_<yyyymmdd>_info.log. The controller part will be replaced by a lower case version of the controller class name, the yyyymmdd should be replaced by the current date. If the console directory doesn't exist yet inside the ATK temp directory it will be created automatically.

 @param string $message info message
 @param mixed  $data    data that should be logged (will be outputted using print_r)

error()

Useful method for outputting error data to a log file. Files will be placed in the ATK temp directory in a subdirectory called console/. Each file will have the following name <controller>_<yyyymmdd>_error.log. The controller part will be replaced by a lower case version of the controller class name, the yyyymmdd will be replaced by the current date.If the console directory doesn't exist yet inside the ATK temp directory it will be created automatically.

 @param string $message error message
 @param mixed  $data    data that should be logged (will be outputted using print_r)

On top of this, you are able to access the vast amount of tool and helper functions and classes within ATK conveniently [2].

<Your>Controller extends atkConsoleController

This shall be placed in a console folder in your module directory. Typically, this should be /modules/<your-module-dir>/console/ from the base directory where ATK is installed. A skeleton code of such a class is as follows:

  atkimport('atk.console.atkconsolecontroller');
  class MyController extends atkConsoleController
  {
    public function defaultAction()
    {
      $this->info("Default Action Called",$this);
      $this->error("Default Error Message Test Called"); 
    }
  
    public function yourAction()
    {
      $this->info("Custom Action Called");
      $this->error("Custom Error Message Test Called"); 
    }
  }

defaultAction() is the the action/method that will be called if you or the user of your console class did not specify any action to be called. If you do not implement this method, then make sure the action/method name is specified when starting a console script. The yourAction() action/method shows a typical custom method that can be included in a console controller class. Note how a call to $this->info('your_message',$some_data) or $this->error('some_error_message',$some_data) allows output . Some ideas on the use of defaultAction: you can implement some kind of while loop within defaultAction which calls a range of custom methods to do automated tasks, making intervals with PHP's built in sleep(). Other obvious possibilities: retrieve/modify database, setup config files, sends e-mails, log statuses.

Note:

Diagrams created with http://argouml.tigris.org.

Further Reading

Reusable Shell Scripting by Timothy Boronczyk (http://www.phparch.com/c/magazine/issue/78)

http://www.atk-framework.com/docs/atk/trunk/atk/console/atkConsoleController.html