PHP Action() class

I use this simple Action() class tostandardise interactive features, status messages and Ajax responses on my PHP-based sites pages.

Background

When doing interactive features on websites you usually do one task or 'action' per page load. Examples of actions include:

Logging in
Adding a new item to a database
Performing a remote call to another server
Uploading a picture
Sending a message to someone

For most actions, you usually want to provide feedback to the person who requested that action by clicking the link or button. Usually that feedback falls neatly into one of the following four categories:

Success - The server completed the action successfully.
Error - The server tried to do the action, but there was some reason why it couldn't (incorrect password on login, failed database connection etc).
Info - The server didn't do the action because there was no reason for it to bother (deleting an item that has already been deleted etc).
Warning - The server completed the action, but that created another problem (message was sent, but now you have no more message credits).

Usually, with those feedback status messages, you'll want to provide an expanded explanation, telling the user what happened in more detail, and/or what to do next.

I wrote this little Action() class to standardise those status success/error messages, and to return those messages in a similar format for Ajax calls.

Source code

class Action
{
	var $a; // Action.
	var $s; // Status boolean (true and false).
	var $status; // Status as a string ('success', 'info', 'error', and 'warning').
	var $result; // What happened in as few words as possible (eg. 'Object created.').
	var $explanation; // An explanation of why that happened and what to do next (eg. 'You may now <a href="">edit the object</a>.').

	function Action($action)
	{
		$this->a = $action;
	}

	function success($result = false, $explanation = false)
	{
		$this->s = true;
		$this->status = 'success';
		$this->result = $result;
		$this->explanation = $explanation;
	}

	function error($result = false, $explanation = false)
	{
		$this->s = false;
		$this->status = 'error';
		$this->result = $result;
		$this->explanation = $explanation;
	}

	function info($result = false, $explanation = false)
	{
		$this->s = false;
		$this->status = 'info';
		$this->result = $result;
		$this->explanation = $explanation;
	}

	function warning($result = false, $explanation = false)
	{
		$this->s = false;
		$this->status = 'warning';
		$this->result = $result;
		$this->explanation = $explanation;
	}

	function e()
	{
		if (!$this->status) return false;

		echo '<p class="' . $this->status . '"><strong>';

		if ($this->result) echo $this->result;
		else echo ucfirst($this->status) . '.';

		echo '</strong>';

		if ($this->explanation) echo ' ' . $this->explanation;

		echo '</p>';

		return $return;
	}

	function response($vars = false)
	{
		global $_site;

		echo '<?xml version="1.0" encoding="utf-8" ?>' . EOL;
		echo '<response>' . EOL;

		if ($_GET['time']) echo "\t" . '<time>' . $_GET['time'] . '</time>' . EOL;
		echo "\t" . '<action>' . $this->a . '</action>' . EOL;

		if ($this->status)
		{
			echo "\t" . '<status>' . $this->status . '</status>' . EOL;
			if ($this->result) echo "\t" . '<result>' . $this->result . '</result>' . EOL;
			if ($this->explanation) echo "\t" . '<explanation>' . $this->result . '</explanation>' . EOL;
			if ($vars) echo array_to_xml($vars, 1);
		}
		else
		{
			echo "\t" . '<status>error</status>' . EOL;
			echo "\t" . '<result>No status yet.</result>' . EOL;
		}

		echo '</response>';

		exit();
	}
}

// Array to XML.
function array_to_xml($array, $num_tabs = 0)
{
	if ($num_tabs) $tabs = str_repeat("\t", $num_tabs);

	if (is_array($array)) foreach ($array as $name => $value)
	{
		if (is_array($value)) $return .= $tabs . '<' . $name . '>' . EOL . array_to_xml($value, $num_tabs + 1) . $tabs . '</' . $name . '>' . EOL;
		else $return .= $tabs . '<' . $name . '>' . $value . '</' . $name . '>' . EOL;
	}
	return $return;
}

Process outline

1. Add a query argument

When doing actions on my sites I add an ?a= query argument based on that action. For example:

?a=add - Add something.
?a=save - Save something.
?a=delete - Delete something.

Then I add additional query arguments to specify WHAT I want to delete/add/save.

2. Create action object

I check for the ?a= query argument on every page. If one is found, create a new Action() object.

if ($_GET['a']) $a = new Action($_GET['a']);

3. Do action and set status

Check what action was requested and do it. Usually I do this before the page has started doing output.

if ($a->a == 'delete')
{
	// Delete something.
	$num_deleted = your_delete_function();

	if ($num_deleted === 1) $a->success('Thing deleted.', 'You did it, it was deleted!');
	elseif ($num_deleted === 0) $a->info('Already deleted.', 'You already deleted that thing.');
	else $a->error('Thing not deleted.', 'The thing could not be deleted, sorry. Try again or something.');
}

4. Show the error message

Once you've tried to do the action, you can wait until the page starts doing output, and then show the status message that goes with the action.

<h1>Page Title<h1>
<?php $a->e(); // Show the error message. ?>

Alternatively, if this action is done as the response part of an Ajax call, return an XML status response.

$a->response(); // Output an Ajax XML response and exit().

If this XML status is picked up through my Javascript Ajax functions and the action was successful, it will return the additional variables as a Javascript array to the specified output function.

If the action was error/info or warning, it alert()s the error message.