Warning: pretty advanced Symfony ahead: if you’re not familiar with the framework, this wouldn’t make sense.

I recently developed a bare-bones API for Mobshare (it’s not yet live), and to keep everything clean, I abstracted away the rendering bit from the controller to an external class. It ended up being a sweet solution, so here it is!

I wanted this to be a JSONP API (the major use case would be a JS client, and parsing XML etc. via JS is a pain. Besides JSON is much shorter over the wire). I didn’t want to rewrite a lot of code: checking for a callback parameter and wrapping the returned string around the JSON output was just begging to be refactored away. So here it is, a generic Symfony JSON API wrapper class:

<?php

class JSONPAPI {

	const CALLBACK_PARAMETER = 'callback';

	var $status;
	var $data;
	var $callback;


	public function __construct($status, $data) {
		$this->status = $status;
		$this->data = $data;

		$callback_parameter_value = $this->getCurrentAction()->getRequestParameter(self::CALLBACK_PARAMETER);
		if($callback_parameter_value)
			$this->callback = $callback_parameter_value;
	}

	public function render() {
		$render_text = json_encode(array($this->status => $this->data));

		if($this->callback)
			$render_text = $this->callback . '(' . $render_text . ');';

		$this->setJavascriptHeaders();
		return $this->getCurrentAction()->renderText($render_text);
	}

	//hack to get the current action
	private function getCurrentAction() {
		return sfContext::getInstance()->getActionStack()->getLastEntry()->getActionInstance();
	}

	private function setJavascriptHeaders() {
		sfContext::getInstance()->getResponse()->setParameter('Content-Type', 'application/javascript', 'symfony/response/http/headers');
	}
}

The bits of magic here are the getCurrentAction() function and the render() call. It works on one very simple idea: everything in Symfony can be accessed from the sfContext::getInstance() object, you just need to dig deep enough.

Once you write this boiler-plate code, using it is very elegant. First, subclass it for your API:

<?php

require_once('JSONPAPI.class.php');

class MobshareAPI extends JSONPAPI {


}

And then, use it like so within your controller:

<?php
class userActions extends sfActions
{

	public function executeAuthenticate() {
		$valid_user = UserPeer::authenticate($this->getRequestParameter('alias'),
			$this->getRequestParameter('mobile_no'), $this->getRequestParameter('password'));
		if($valid_user instanceOf User) {
			$success = new MobshareAPI('success', $valid_user->toArray());
			return $success->render();
		} else {
			$error = new MobshareAPI('error', 'Authentication failed: Alias, mobile number or password invalid.');
			return $error->render();
		}
	}

}

Note: the rendering has been delegated to the $success and $error MobshareAPI objects. This allows for a really maintainable API. Adding functionality is much simpler since you don’t have to worry about the boilerplate.

You end up calling the API like this:

http://api.mobshare/user/authenticate?alias=vish&password=xxx&callback=handler

and you get back data which looks like this:

handler({"success":{"alias":"vish","name":"Vishnu Gopal","photo_mini": ...);

Note that callback handling is done entirely by the API and the controller needn’t worry about this parameter at all!