.. _how-to-write-a-command:

######################
How to write a command
######################

All functions specified in the :ref:`backend-api` are defined in command-files
located in **src/commands**. They are grouped by their functionality, so all
functions related to one section could be disabled by not load the corresponding
command file - see :ref:`settings <backend-settings>`.

In this chapter is described how to write such a command file.

.. note::
	There is in every code block an "<?php" - just ignore it, because it's
	only for highlightning.

The scaffold
============

Each action is encapsulated in a class, which extends *SmartWFM_Command*, and
only has one method called *process* with one parameter. Then you need to
register this action in the command manager to associate it with the API name.

.. code-block:: php

	<?php

	class ExampleActions_ExampleFunctionality extends SmartWFM_Command {
		function process($params) {
			/*
			 * ... your code here ...
			 */
		}
	}

	SmartWFM_CommandManager::register('example.function1', new ExampleActions_ExampleFunctionality());

The parameter testing
=====================

Types
-----

Like in every web app you need to check the incoming data. Therefore the php
backend provides a class for easy validation.

.. code-block:: php

	<?php
	// simple data types

	// string
	$param_test = new SmartWFM_Param('string');
	// integer
	$param_test = new SmartWFM_Param('integer');
	// boolean
	$param_test = new SmartWFM_Param('boolean');
	// string or integer
	$param_test = new SmartWFM_Param('stringorinteger');

	// complex data types

	/* object (known as associative array)
	 * $items contains array of these subelements
	 * This is only for static key names! See key_data_object for dynamic
	 * key names.
	 */
	$param_test = new SmartWFM_Param(
		$type = 'object',
	 	$items = array(
			'key1' => new SmartWFM_Param('string'),
			'key2' => new SmartWFM_Param('integer')
		)
	);

	/* array
	 * $items is just the containing data type
	 */
	$param_test = new SmartWFM_Param(
		$type = 'array',
		$items = new SmartWFM_Param('string')
	);

	/* key_data_object (known as associative array)
	 * counterpart of object for dynamic key values.
	 * $items contains two named subelements "key" with the test class for
	 * the keys and "value" for the values.
	 */
	$param_test = new SmartWFM_Param(
		$type = 'key_data_object',
		$items = array(
			'key' => new SmartWFM_Param('string'),
			'value' => new SmartWFM_Param('string')
		)
	);

Here is an example to demonstrate the difference between object (upper example)
and key_data_object (lower example). The upper example has static names for the
keys which are known before runtime. In the lower example the keys are dynamic.

.. code-block:: guess

	Array
	(
		[name]		=> 'Michael'
		[age]		=> 22
	)

	Array
	(
		['Michael']	=> 22
		['James']	=> 45
	)

Validation
----------

Now you only have to initiate the tests by use of the following line, where
$params is the parameter passed to the *process* method and will be overwritten
with the validated parameter:

.. code-block:: guess

	$params = $param_test->validate($params);

Exception
---------

If the test fails an exception of the type **SmartWFM_Excaption_Params** and
with an error message will be thrown. The backend automatically handles this.

Logic and exceptions
====================

Now you can write down your logic and process the action. If an error occur
just raise an exception like this:

.. code-block:: guess

	throw new SmartWFM_Exception('Your error message here', -1);

This includes a message and the error code. The backend catch it and creates
the error response. (see :ref:`backend-api-error`)

Response
========

Returning the response is really easy. You only need to create a new
SmartWFM_Response object, save your response data to it's data variable and
return it. Everything else like create it's corresponding JSON string is done
by the backend core.

.. code-block:: guess

	$response = new SmartWFM_Response();
	$response->data = $yourData;
	return $response;

It is also possible to write this in one line:

.. code-block:: guess

	return new SmartWFM_Response($yourData);