Restful Storm

This application aim to provide restful access to Storm enabled models.

Installation

Requirements

You need Apache with rewrite module, PHP 5.4+ and MySQL 5+.

Obviously you also need Storm.

This application defines a git submodule for Storm which itself defines a submodule for a customized Zend Framework 1.6. Please see git documentation to learn more about submodules.

tip : /build.sh contains commands to init and update them recursively

Storm models

Creating Storm models for your datas is trivial.

class My_Model extends Storm_Model_Abstract {
      protected $_table_name = 'my_table_name';
      protected $_table_primary = 'id_table_name'; // needed only if PK is not named 'id'
}

From here you can use Storm super powers to access and manipulate your datas.

See Storm documentation to learn more.

Configuration

Copy /config.php.dist to /config.php and edit it.

sgbd section should be self explanatory

modelspath should contain base path to your Storm enabled models.

They should follow Zend Framework 1.x class loader naming convention : My_Storm_Model should reside in My/Storm/Model.php file.

models contains access and capabilities configuration array.

• key contains model's name
• value is an array
  • caps contains capabilities name separated by ';' between index, show, create, update, delete
  • fields contains fields name separated by ';', those fields will be included in JSON responses, 'id' field is always included

'models' => [
	 Class_Album' => [
		'caps' => 'index;show',
		'fields' => 'titre']]

'*' can be used as an "allow all" wildcard.

• as a model name allow access to all your models
• as a caps value allow all capabilities
• as a fields value allow display of all fields in JSON response

Then you can define a read all access as

'models' => [
	 '*' => [
		'caps' => 'index;show',
		'fields' => '*']]

And you can combine default access with specifics.

'models' => [
	 '*' => [ // any models
		'caps' => 'index;show', // is searchable and showable
		'fields' => ''], // but only show its id, no other fields

	'Class_Album' => [ // this model
		'caps' => '*', // is fully handled in this app
		'fields' => '*', // and show all its fields
	]]

Usage

Catalog

Accessing /catalog URL will show a page reflecting your configuration.

For each model it will display

• allowed methods and their URLs
• displayed fields

Index

URL : /[model name]/

http://localhost/Restful/Class_Batch

Output : JSON array containing matching models JSON representations.

[{"type":"MOISSONNAGE_ARTEVOD","last_run":"2014-07-30 22:02:05","id":3}]

Responses are limited to 100 results, to get next results you should specify a page number.

URL : /[model name]/page/[page number]

http://localhost/Restful/Class_Notice/page/45

When a response returns an empty array there is no more results.

You can specify order clause

URL : /[model name]/order/[order clause]

http://localhost/Restful/Class_Notice/order/id%20desc

You can find models matching exact properties values

URL : /[model name]/[property name]/[exact value]

http://localhost/Restful/Class_Album/titre/La%20tulipe%20noire

or

http://localhost/Restful/Class_Album/titre/La%20tulipe%20noire/genre/roman

You can even specify an SQL where clause

URL : /[model name]/[property name]/[exact value]

http://localhost/Restful/Class_Album/where/titre%20like%20'La%25'

But you have to choose between simple property exact value matching or where clause.

Full featured query

http://localhost/Restful/Class_Album/where/titre%20like%20'La%25'/order/id%20desc/page/2

Show

When you already know the primary key of a model, you can access it directly with

URL : /[model name]/[primary key value]

http://localhost/Restful/Class_Batch/3

Output : matching model JSON representation.

{"type":"MOISSONNAGE_ARTEVOD","last_run":"2014-07-30 22:02:05","id":3}

Create, Update, Delete are not implemented yet

As a module plugin in existing Storm/ZendFramework application

Restful storm can be integrated in an existing MVC ZendFramework application.

Add restful source

We recommend to clone out of your application and then symlink to it, for example in a "restful/" directory. Then you have to tell php to include the path to restful library.

set_include_path([your root path] . '/restful/library' . PATH_SEPARATOR .
									 get_include_path());

Bootstrap as plugin

When your application bootstrap you need to pass the models configuration to Restful_Model_Configuration:

$config = new Zend_Config(include //path to your config file);
Restful_Model_Configuration::setConfig($config);

Then you can bootstrap restful

Restful_Bootstrap::asPlugin(Zend_Controller_Front::getInstance(),
															'rest',
															Zend_Controller_Action_HelperBroker::getExistingHelper('ViewRenderer'));

Front controller is needed to add restful routes to its router.

'rest' is the name of the module used to bind Restful_Controller in your application.

ViewRenderer is needed to add Restful view helpers path.