Posts Tagged REST

Creating a PHP REST API Using the Zend Framework

Posted by Chris Danielson in PHP on September 2nd, 2009

I don’t know about you, but I spent hours pouring over the Zend documentation and searching the Internet for some sort of understanding or example regarding how to do REST the correct way in PHP.  I found a handful of one-offs, where everyone was writing their own core REST engine from scratch. I figure why write all the code to handle this, if you already have the Zend Framework in your code base. I believe that the ideal solution will effectively use the the Zend_Rest_Controller and ContextSwitch objects as well as offering JSON and XML formatting options. My goal here is simple. I want to give you the building blocks to aid in writing an easily maintainable REST API in PHP using the Zend Framework.

This code example will support REST data in the format of XML and JSON.

Prerequisites:

  1. PHP version > 5
  2. Zend Framework 1.9.2 (at the minimum) The generic download page can found here.

Download ZendRestExample Source. You will want to download this example in order to effectively run and better understand the project. Make sure to rename the 1.htaccess file to .htaccess (if interested in using it). As well, take note that there are other files not listed below that are required to run this project. These are contained within the zip’d source code. Finally, the Zend framework is not zip’d into the source code. You’ll need to download this and install it on your own.

Basic Directory Structure:

/
/.htaccess
/index.php
/applications/
/applications/configs/
/applications/controllers/
/applications/forms/
/applications/layouts/
/applications/views/
/library/  (optional where the Zend folder containing the framework should reside)

URLS used in this example:


http://yourSite/version/format/xml

http://yourSite/version/format/json

//with other parameters you can do:

http://yourSite/version/format/xml/id/1234/param2/6789

One of the tricky things with REST is that the URLs need to be formatted properly. In Apache, all you need is the mod_rewrite module enabled and a .htaccess in the root of your current web project.

Download .htaccess
SetEnv APPLICATION_ENV development
 
RewriteEngine On
#RewriteBase /~myUserName/myDirectory
RewriteBase /
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]

Now that we have adjusted the .htaccess, let’s look into the application/configs/application.ini as well as the important Bootstrap.php.

Download application.ini
[production]
phpSettings.display_startup_errors = 0
phpSettings.display_errors = 0
bootstrap.path = APPLICATION_PATH "/Bootstrap.php"
resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"
bootstrap.class = "Bootstrap"
 
[staging : production]
 
[testing : production]
phpSettings.display_startup_errors = 1
phpSettings.display_errors = 1
 
[development : production]
phpSettings.display_startup_errors = 1
phpSettings.display_errors = 1

The core kick-start of this whole REST application is contained in the applications/Bootstrap.php

Download Bootstrap.php
<?php
 
class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
	protected function _initAutoload()
    {
        $autoloader = new Zend_Application_Module_Autoloader(array(
            'namespace' => 'Default_',
            'basePath'  => dirname(__FILE__),
        ));
        return $autoloader;
    } 
 
	protected function _initRestRoute()
	{
		$this->bootstrap('Request');	
		$front = $this->getResource('FrontController');
		$restRoute = new Zend_Rest_Route($front, array(), array(
			'default' => array('version')
		));
		$front->getRouter()->addRoute('rest', $restRoute);
	} 
 
	protected function _initRequest()
    {
        $this->bootstrap('FrontController');
        $front = $this->getResource('FrontController');
        $request = $front->getRequest();
    	if (null === $front->getRequest()) {
            $request = new Zend_Controller_Request_Http();
            $front->setRequest($request);
        }
    	return $request;        
    } 		
 
}

Now we need to wire up the ability for web requests to move through this engine. We do this in our /index.php file.

Download index.php
<?php
// Define path to application directory
defined('APPLICATION_PATH')
    || define('APPLICATION_PATH', realpath(dirname(__FILE__) . '/application'));
 
// Define application environment
defined('APPLICATION_ENV')
    || define('APPLICATION_ENV', (getenv('APPLICATION_ENV') ? getenv('APPLICATION_ENV') : 'production'));
 
// Ensure library/ is on include_path
/*
If you do not have the Zend library already included in your PHP installation...
 
1.  Create a directory named library and place the Zend Framework into it.
 
NOTE: In my instance, I have the Zend library residing under /usr/share/php/   
Because of this, the following lines are commented.
*/
/*set_include_path(implode(PATH_SEPARATOR, array(
    realpath(APPLICATION_PATH . '/library'),
    get_include_path(),
)));
*/
 
/** Zend_Application */
require_once 'Zend/Application.php'; 
 
// Create application, bootstrap, and run
$application = new Zend_Application(
    APPLICATION_ENV, 
    APPLICATION_PATH . '/configs/application.ini'
);
$application->bootstrap()->run();

Well now that the core is in place, all we need is to integrate our controllers. This is where our business logic will reside.

Download VersionController.php
<?php
 
class VersionController extends Zend_Rest_Controller
{  
	public function init()
    {
        $bootstrap = $this->getInvokeArg('bootstrap');
 
		$options = $bootstrap->getOption('resources');
 
		$contextSwitch = $this->_helper->getHelper('contextSwitch');
		$contextSwitch->addActionContext('index', array('xml','json'))->initContext();
 
		//$this->_helper->viewRenderer->setNeverRender();	
		$this->view->success = "true";
		$this->view->version = "1.0";
	}
 
    /**
     * The index action handles index/list requests; it should respond with a
     * list of the requested resources.
     */ 
    public function indexAction()
    {
		//if you want to have access to a particular paramater use the helper function as follows:
		//print $this->_helper->getParam('abc');
               //To test with this use:  http://myURL/format/xml/abc/1002
	}
 
    public function listAction()
    {
        $this->_forward('index');
    }
 
    public function getAction()
    {
		$this->_forward('index');
    }
 
    public function newAction() {   	
		$this->_forward('index');
    }
    public function postAction() {
		$this->_forward('index');
    }
    public function editAction() {    	 
		$this->_forward('index');
    }
    public function putAction() {
		$this->_forward('index');
    } 
    public function deleteAction() {
		$this->_forward('index');
    }
}

Now that we’ve done this, the URL for format of JSON just works as-is thanks to the Zend ContextSwitch engine. No other changes are needed. If you are interested in having the output in XML format, then you’ll need to make a few additions. Now that we’ve taken care of the Controller, we’re going to have to add in the views to make the XML work with the ContextSwitch. So under /applications/views/scripts/version/ you’ll need a file: index.xml.phtml

View Code PHP
<?php
$doc = new DOMDocument();
$doc->formatOutput = true;
$root_element = $doc->createElement("response");
$doc->appendChild($root_element);
 
$statusElement = $doc->createElement("success");
$statusElement->appendChild($doc->createTextNode($this->success));
$root_element->appendChild($statusElement);
 
$versionElement = $doc->createElement("version");
$versionElement->appendChild($doc->createTextNode($this->version));
$root_element->appendChild($versionElement);
 
print $doc->saveXML();
?>

And that is all there is to it. We’ve now made a basic index/list REST API for listing the version of your product. This is an overly simple example of how to integrate quickly the Zend REST engine.

, , , , , , ,

24 Comments