Rolling out an API for your cakePHP app Part 3: Handling Errors

<?php
App::import('Vendor', 'api/api');
class AppError extends ErrorHandler {
 
private $apiError = false;
 
 /**
 * HTTP response codes array
 *
 * @var array
 * @see http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
 **/
var $codes = array(
    200 => 'OK',
    400 => 'Bad Request',
    401 => 'Unauthorized',
    402 => 'Payment Required',
    403 => 'Forbidden',
    404 => 'Not Found',
    405 => 'Method Not Allowed',
    406 => 'Not Acceptable',
    407 => 'Proxy Authentication Required',
    408 => 'Request Time-out',
    500 => 'Internal Server Error',
    501 => 'Not Implemented',
    502 => 'Bad Gateway',
    503 => 'Service Unavailable',
    504 => 'Gateway Time-out'
);
 
/**
 * Class constructor, overloading to make minor ammendment.
 *
 * @param string $method Method producing the error
 * @param array $messages Error messages
 */
function __construct($method, $messages) {
    App::import('Core', 'Sanitize');
    static $__previousError = null;
 
    if ($__previousError != array($method, $messages)) {
        $__previousError = array($method, $messages);
        $this->controller =& new CakeErrorController();
    } else {
        $this->controller =& new Controller();
        $this->controller->viewPath = 'errors';
    }
 
    $options = array('escape' => false);
    $messages = Sanitize::clean($messages, $options);
 
    if (!isset($messages[0])) {
        $messages = array($messages);
    }
 
    if (method_exists($this->controller, 'apperror')) {
        return $this->controller->appError($method, $messages);
    }
 
    if (!in_array(strtolower($method), array_map('strtolower', get_class_methods($this)))) {
        $method = 'error';
    }
 
    //Need to ammend below so that custom methods are triggered in production environments
    //if ($method !== 'error') {
    if (!in_array($method, get_class_methods('AppError'))) {
        if (Configure::read() == 0) {
            $method = 'error404';
            if (isset($code) && $code == 500) {
                $method = 'error500';
            }
        }
    }
    $this->dispatchMethod($method, $messages);
    $this->_stop();
}
 
/**
 * Error
 *
 * Handles the error with the right response code
 *
 * @param array $params
 * @return void
 * @author primeminister
 * @access public
 * @see http://apiwiki.twitter.com/REST+API+Documentation#HTTPStatusCodes
 */
public function error($params) {
 
    extract($params, EXTR_OVERWRITE);
    if (!isset($name)) {
        $name = $this->codes[$code];
    }
    if (!isset($url)) {
        $url = $this->controller->here;
    }
    // set header
    header("HTTP/1.x $code $name");
    $this->controller->set(array(
        'code'      => $code,
        'name'      => $name,
        'message'   => $message,
        'title'     => $code . ' ' . $name,
        'request'   => $url
    ));
 
 
    //If API error handle in a different way
    if ($this->apiError) {
        $this->controller->set(compact('apiErrorCode'));
    	$this->renderApiError();
    }
    else {
    	if ($this->controller->RequestHandler->isXml()) {
            $this->controller->RequestHandler->renderAs($this->controller, 'xml');
        }
 
        $this->_outputMessage('error');
    }
}
 
/**
 * Throw an API error, additionally passing an api error code.
 * 
 * @param Array $data Data sent by calling method, optionally includes apiErrorCode
 * 
 * @return void
 */
function apiError($data) {
 
    $this->apiError = true;
 
    //Get correct message and code based on API error code
    $apiErrorCode = 500;
    if (isset($data['apiErrorCode'])) {
    	$apiErrorCode = $data['apiErrorCode'];
    }
 
    $api = new Api();
    $errorData = $api->getError($apiErrorCode);
 
    $code = (isset($errorData['httpCode']))?$errorData['httpCode']:500;
 
    $message = __('API error.', true);
    if (isset($errorData['errorMessage'])) {
    	$message = $errorData['errorMessage'];
    }
    elseif (in_array($apiErrorCode, array_keys($this->codes))) {
    	$message = $this->codes[$apiErrorCode];
    }
 
    $this->error(array('code'=>$code,'message'=>$message, 'apiErrorCode'=>$apiErrorCode));
}
 
/**
 * Render an API error using correct error view based on current API version.
 * 
 * @return void
 */
function renderApiError() {
 
    //Retrieve the correct view
    $version = '0.3';
    $folder = $this->controller->RequestHandler->prefers();
    $view = 'error';
 
    if (isset($this->controller->params['version'])) {
    	$version = $this->controller->params['version'];
    }
 
    if ($this->controller->RequestHandler->isXml()) {
        $this->controller->RequestHandler->renderAs($this->controller, 'xml');
    }
 
    $errorFile = new File(VIEWS . "/errors/api/$version/$folder/error.ctp");
    if ($errorFile->exists()) {
        $view = "/errors/api/$version/$folder/error";
    }
    else {
 
        //Get error view for previous API version
        $version = substr(strstr($version, '.'), 1);
 
        //NOTE: again please note that the version of my API started at 0.3, you might need to alter the for loop below for your case
        for ($i = $version; $i >= 3; $i--) {
            $viewFile = new File(VIEWS . "/errors/api/0.$i/$folder/error.ctp");
            if ($viewFile->exists()) {
                $view = "/errors/api/0.$i/$folder/error";
                break;
            }
        }
    }
    $this->_outputMessage($view); 
}
}   
?>

    /**
     * Error codes for API errors
     */
    private $errorCodes = array(
        1001 => array('httpCode'=>500, 'errorMessage'=>'Version does not exist.'),
        1002 => array('httpCode'=>500, 'errorMessage'=>'Unknown output file.'),
        1003 => array('httpCode'=>500, 'errorMessage'=>'Unrecognised method.'),
    );
 
    /**
     * Retrieve data relating to an API error code
     * 
     * @param $errorCode Int API error code
     * @return Array Data associated with the error code.
     */
    public function getError($errorCode) {
        if (in_array($errorCode, array_keys($this->errorCodes))) {
        	return $this->errorCodes[$errorCode];
        }
    	return false;
    }

$this->cakeError('apiError', array('apiErrorCode'=>1001));

<Error Code="1001" Request="/0.3/posts/get.xml">Version does not exist.</Error>

<Error Code="<?php echo h($apiErrorCode) ?>" Request="<?php echo h($request) ?>"><?php echo h($message) ?></Error>