Developer Area/CLI Framework

To facilitate creation of Command Line Interface (CLI) scripts, a CLI framework has been created for Mahara.

This is a work in progress

Features

The CLI framework has been designed to make creating CLI scripts easier. To this end, it has a number of features. In it's basic operation it supports:

• retrieval of options by both long, and short name; and
• retrieval of additional arguments.

In it's extended operation it's features include:

• help/usage creation supporting:
  • descriptions;
  • default values;
  • example values; and
  • word wrapping of text.
• option validation;
• log level control (ability to turn on verbosity); and an
• option getter supporting:
  • long and short option names.

Usage

The CLI library is located in /htdocs/lib/cli.php and needs to be included to be used. CLI should also be defined. Standard mahara incantation still applies (e.g. you must still include init.php and define INTERNAL.

Basic Usage

For basic usage, you can retrieve settings for various options, other words (not in the valid format), and short versions of longer options.

For example, using the following command line options:

 php htdocs/admin/cli/example.php --argument=value --argument2 -x -q=n pony

with the following code:

 <?php
 
 define('CLI', true);
 define('INTERNAL', true);
 include(dirname(dirname(__FILE__)) . '/init.php');
 
 $cli = get_cli();
 $cli->set_cli_shortoptions(array('x' => 'argumentx', 'q' => 'question'));
 
 $argument = $cli->get_cli_param('argument');
 $argument2 = $cli->get_cli_param('argument2');
 $argumentx = $cli->get_cli_param('argumentx');
 $question = $cli->get_cli_param('question');
 $unmatched = $cli->get_cli_unmatched();

would mean that:

 $argument = 'value';
 $argument2 = true;
 $argumentx = true;
 $question = 'n';
 $unmatched = array('pony');

Extended Usage

The extended format requires much more setting up, but also offers a number of other features.

Basic operation:

 php htdocs/admin/cli/example.php --argument=value --argument2 -x -q=n pony

with the following code:

 <?php

 define('CLI', true);
 define('INTERNAL', true);
 include(dirname(dirname(__FILE__)) . '/init.php');

 $cli = get_cli();

 $options = array();
 $options['argument'] = new stdClass();
 $options['argument']->exampleValue = 'value';
 $options['argument']->description = 'This is an example description for argument';

 $options['argument2'] = new stdClass();
 $options['argument2']->description = 'This is an example description for argument2 - it takes no value';

 $options['argumentx'] = new stdClass();
 $options['argumentx']->description = 'This is an example description for argumentx - it takes no value and has an alias';
 $options['argumentx']->shortoptions = array('x');

 $options['question'] = new stdClass();
 $options['question']->exampleValue = 'value';
 $options['question']->description = 'This is an example description for question - it typicaly takes an argument and has an alias of q';
 $options['question']->shortoptions = array('q');

 $settings = new stdClass();
 $settings->options = $options;
 $settings->allowunmatched = true;
 $settings->info = 'Some information about what this script does';

 $cli->setup($settings);