Amun development

A record represents an row of an table. It must extend the class Amun_Data_RecordAbstract. The record is a data object wich is used to create or receive entries from a database. Here an example howto create a new record.

$news = Amun_Sql_Table_Registry::get('Service_News')->getRecord();
$news->setPageId(1);
$news->setTitle('Foobar');
$news->setText('<p>lorem ipsum</p>');

In this example you can be sure that the page id exists and that the title and text contains valid values.

The Table class represents an database table. It must extend the class Amun_Sql_TableAbstract. It contains all informations about the table what columns are available and how they are connected to other tables. The table class can be used to CRUD (Create, Receive, Update and Delete) records on the table. Here an example howto receive a list of Vendor_News records.

$result = Amun_Sql_Table_Registry::get('Vendor_News')
	->select(array('id', 'title', 'url', 'text', 'date'))
	->join(PSX_Sql_Join::INNER, Amun_Sql_Table_Registry::get('User_Account')
		->select(array('name', 'profileUrl'), 'author')
	)
	->where('pageId', '=', $this->page->id)
	->orderBy('date', PSX_Sql::SORT_DESC)
	->getAll(PSX_Sql::FETCH_OBJECT);

We use the Amun_Sql_Table_Registry class to get the table class. By default the getAll() method returns an associative array.

The handler class implements the business logic when create, update or delete a record. It contains the depending table class. If an action occurs the notify method is called wich invokes all classes wich match the table pattern in the table "amun_system_notify". If you want hook a specific action if an record is created you have to add a class to the notify table. Here an example howto insert a new record.

$handler = new Amun_Service_News_Handler($user);

$news = Amun_Sql_Table_Registry::get('Service_News')->getRecord();
$news->setPageId(1);
$news->setTitle('Foobar');
$news->setText('<p>lorem ipsum</p>');

$handler->create($news);

Amun was designed to work with an messaging queue like active mq. If the Stomp notify class was added to the "amun_system_notify" table everytime a record is inserted the notifier sends a message to the broker containing the table, type, userId and the complete record data. In this way you can implement listeners to the broker wich can do time consuming tasks so that the page load is not influenced.

Use leading tabs to ident your code and spaces to format them if necessary. That means you should only use tabs to the first sign after that use only spaces. This has the advantage that your code is good readable in any editor even if the tabs are displayed in different lengths. Here an example how it looks.

<?php
function foobar()
{
	$hello = 'foo';
	$bar   = 'world';
}

We have used one tab to indent each variable. To indent the equal sign of $bar to the same width as above we use only white spaces not tabs. You should setup your editor that trailing spaces are removed on save and that you can see leading tabs and trailing spaces.

The following examples show you howto format control structures correct.

<?php
if($x !== false || $y >= 0)
{
	echo 'action 1';
}
else
{
	echo 'action 2';
}

<?php
$foo = ($bar > 10) ? true : false;

$bar = ($x < 10) ? '&lt;' : (($x > 10) ? '&gt;' : '=');

<?php
switch($foo)
{
	case 'foo':

		echo 'action 1';
		break;

	default:

		echo 'action 2';
		break;
}

<?php
$i = 1;

while(true)
{
	if($i > 10)
	{
		break;
	}
	else
	{
		echo 'action ' . $i . "\n";

		$i++;
	}
}

<?php
do
{
	echo 'action 1';
}
while(false);

<?php
for($i = 0; $i < 10; $i++)
{
	echo 'action ' . $i;
}

The following examples show you howto call functions correct.

<?php
$foo = bar($val, $ue);

$bar = $this->foo($an, $oth, $er, null);

Here an example howto create a class with a proper document block. Note because Amun needs PHP > 5 you should always define the visibility of the method with "public", "protected" or "private".

<?php
/**
 * [class]
 *
 * [description]
 *
 * @author     [author_name] <[author_email]>
 * @license    [license_url] [license_name]
 * @link       [url]
 * @category   module
 * @package    service
 * @subpackage [service_name]
 * @version    $Revision: 619 $
 */
class index extends Amun_ApplicationAbstract
{
	public function onLoad()
	{
		echo 'some content';
	}
}

If you make an SQL query you should always use the HEREDOC syntax to declare the SQL query. This increases the readability and therefore the code is easier to maintain. The following examples shows howto make an proper SQL select.

<?php
class index extends Amun_ApplicationAbstract
{
	public function onLoad()
	{
		$foos = array();
		$sql  = <<<SQL
SELECT

	bar.id,
	bar.title,
	bar.date

	FROM tbl_bar bar

		WHERE bar.id > 10

		AND bar.id < 100

			ORDER BY bar.id DESC

			LIMIT 0, 10
SQL;

		$result = $this->sql->getAll($sql);

		foreach($result as $row)
		{
			array_push($foos, array(

				'title' => $row['title'],
				'date'  => date('r', $row['date']),

			));
		}
	}
}

All code should be developed under E_ALL | E_STRICT wich is default if you are in debug mode. That means that you code must not produce any error or warning on this error level.

The web application requests an request token.

GET /index.php/api/auth/request HTTP/1.1
Host: 127.0.0.1
Authorization: OAuth,
 oauth_consumer_key="[key]",
 oauth_signature_method="HMAC-SHA1",
 oauth_signature="[signature]",
 oauth_timestamp="[timestamp]",
 oauth_nonce="[nonce]",
 oauth_version="1.0"

On success Amun respond with an token and token secret. Note you can request max 5 valid tokens per IP.

HTTP/1.1 200 OK

oauth_token=[token]&
oauth_token_secret=[token_secret]&
oauth_callback_confirmed=true&
x_oauth_expire=[expire]

Your application should now redirect the user to Amun to authorize the request token. You must use the obtained request token in your request

GET /index.php/api/auth/authorization?oauth_token=[token] HTTP/1.1
Host: 127.0.0.1

The user must login and "Allow" or "Deny" the request for the web application.

If the user has "Allow" or "Deny" the request Amun redirects the user back to the callback. Note the callback must be from the same host as the url defined in the backend. If the request was denied the GET variable x_oauth_error is set.

Accepted:
GET [callback]?oauth_token=[token]&oauth_verifier=[verifier] HTTP/1.1

Denied:
GET [callback]?x_oauth_error=[msg] HTTP/1.1

Now we have all informations to get an access token. Note the expire time of your request token must be valid to exchange the token.

GET /index.php/api/auth/access HTTP/1.1
Host: 127.0.0.1
Authorization: OAuth,
 oauth_consumer_key="[key]",
 oauth_token="[token]",
 oauth_signature_method="HMAC-SHA1",
 oauth_signature="[signature]",
 oauth_timestamp="[timestamp]",
 oauth_nonce="[nonce]",
 oauth_version="1.0",
 oauth_verifier="[verifier]"

If all parameters are valid Amun respond with an access token and secret. You can use the token [expire] seconds to access the API.

HTTP/1.1 200 OK

oauth_token=[token]&oauth_token_secret=[token_secret]&x_oauth_expire=[expire]

Here an example how you can access the API with an access token

GET /index.php/api/news/@me/@all HTTP/1.1
Host: 127.0.0.1
Accept: application/xml
Authorization: OAuth,
 oauth_consumer_key="[key]",
 oauth_token="[token]",
 oauth_signature_method="HMAC-SHA1",
 oauth_signature="[signature]",
 oauth_timestamp="[timestamp]",
 oauth_nonce="[nonce]",
 oauth_version="1.0"

We get the latest entries from the news service

HTTP/1.1 200 OK

<resultset>
	<startIndex>1</startIndex>
	<itemsPerPage>1</itemsPerPage>
	<totalResults>1</totalResults>
	<entry>
		<id>1</id>
		<user>foo</user>
		<title>some headline</title>
		<text>and here a really great description</text>
		<date>Mon, 16 Nov 2009 12:56:11 +0100</date>
	</entry>
</resultset>

In the description we use variables like [key] etc. In this section I explain each variable.