Getting Started and Technical Overview

This page discusses the technical overview of the code and how it works.

These are the basic steps to getting started with Tarzan:

1. Download the latest version (currently the SVN trunk)
2. You can move the contents of the trunk directory wherever you want, provided the files stay in the same directory together.
3. Rename config-sample.inc.php to config.inc.php.
4. Edit the config.inc.php file, adding all of the relevant information about your AWS account.
5. In your application (e.g. a specific PHP document), simply use require_once() (or require() or include_once() or include()) to add the tarzan.class.php file to your page. This will load the core Tarzan API.
6. Create a new instance of whichever class object you want to use. i.e.:

   $s3 = new AmazonS3();

7. This will load (assuming you've left the file structure alone) the s3.class.php file which contains the AmazonS3 class, and all of the methods from that class will be available to you.

Tarzan uses a specific file structure in an effort to promote convention over configuration (a concept popularized by the Ruby on Rails crowd). By maintaining this file structure, Tarzan can utilize PHP's spl_autoload_register() functionality, which can load classes on-the-fly based on their need.

Using this system, you should only need to load the tarzan/tarzan.class.php file into your page before initializing the various classes.

In general, the API follows these guidelines:

• All API-specific classes are named “Amazon{initials-as-caps}”.
• All API classes extend the main TarzanCore class.
• All responses are returned as TarzanHTTPReponse objects containing three properties: header, body, and status.
  • header is always an array of HTTP response headers, plus a few extras that are useful for debugging.
  • body is always a SimpleXMLElement object containing the body response.
• Required parameters (in the AWS API) are also required in the Tarzan API.
• Optional parameters are always passed in last.
  • If there is only one optional parameter, it can be passed in directly.
  • If there are multiple optional parameters, they are passed in as an associative array (i.e. key-value pairs).
• All classes share the following properties:
  • service – The name of the current class (e.g. AmazonSQS).
  • api_version – The Amazon version of the API that is supported by Tarzan.
  • util – An instance of TarzanUtilities, which contains a variety of helpful utilities for connecting to, and working with, the Amazon APIs.
• With only one or two exceptions, Tarzan's methods follow the same naming conventions as the Amazon API actions.

Here is a quick-and-dirty example using the SQS class. The example here assumes that you've set your AWS key and secret key in the config.inc.php file (Tarzan Configuration).

<?php
// Include the main Tarzan class
require_once('tarzan/tarzan.class.php');
 
// Set the headers to plain text with a UTF-8 character set (so that we can read the output more easily).
header('Content-type: text/html; charset=utf-8');
 
// Instantiate a new AmazonSQS object.
$sqs = new AmazonSQS();
 
// Create a new SQS queue
$create = $sqs->create_queue('tarzan-test');
 
// Check that the last request was successful. (HTTP status code 200 means everything was okay.)
if ($create->isOK())
{
	// Get the URL of the SQS queue we just created. We'll re-use this a lot.
	$queue = $create->body->CreateQueueResult->QueueUrl;
 
	// Send a message to the queue.
	$send = $sqs->send_message($queue, 'Hello world!');
 
	// Check that the message was sent successfully.
	if ($send->isOK())
	{
		// Yay!
		echo 'Queue was created and message was sent successfully!';
	}
 
	// If not, explode horribly.
	else
	{
		print_r($send);
		exit('Ka-BOOM!');
	}
}
 
// If not, explode horribly.
else
{
	print_r($create);
	exit('Ka-BOOM!');
}
 
?>