Download the PHP package aeris/zend-rest-module without Composer

ZendRestModule

A Zend Framework 2 module to help you create RESTful web services.

Installation

ZendRestModule can be installed via composer.

Then add 'Aeris\ZendRestModule' to the 'modules' config in /config/application.config.php.

Features

ZendRestModule provides a number of features to facilitate creating a RESTful web service.

• Entity serialization
• RESTful Exception handling
• Test Helpers

Serializer

ZendRestModule uses the popular JMS Serializer to serialize and deserialize application models.

The JMS Serializer allows you to use Annotations, XML, or YML to configure how objects are serialized and deserialized from raw data.

While you can use the JMS serializer on its own, ZendRestModule introduces behaviors to make serialization/deserialization a lot easier in the context of Zend APIs.

Here's how a RESTful controller might look without the ZendRestModule:

Automatic Enitity Serialization

Using the ZendRestModule, you can simply return the raw model:

The ZendRestModule will intercept the return value, convert the model to a SerializedJsonModel, then serialize the data according to your JMS Serializer configuration.

Deserialize onto Existing Entities

Out of the box, the JMS Serializer allows you to deserialize raw data into entity objects.

ZendRestModule includes a JMS object constructor extension, which allows you to deserialize data onto an existing entity. This is very useful for PUT requests, where the request data my not be a fully defined entity.

See this article for a long rant about how and why this works.

Serialization Groups

The JMS Serializer allows you to configure serialization groups for entities. This is useful for setting what data different request return. For example, I may only want to see an animal's id and name in a getList response, but see more details in a get response:

The Aeris\ZendRestModule\View\Annotation\Groups annotation allows you to configure which serialization groups will be used for each controller action.

You can also configure serialization groups in the zend_rest config:

Other Serializer Components

DateTimeTimestampHandler

Serializes/deserializes between unix timestamps and \DateTime objects.

The serializer will now deserialize birthDate timestamps into \DateTime objects, and serialize birthDate as a timestamp.

Serializer Configuration Reference

RESTful Exception Handling

ZendRestModule catches errors and exceptions thrown during the MVC event cycle, and converts the errors into JSON responses.

Example

This example configures JSON output for errors occuring in the Animals Web Service.

A GET request to /animals/narwhal would return a JSON object so:

The error would also be written to the server log, by way of the on_error callback.

Similarly a request to /not/an/endpoint would return a 404 error, with a invalid_request JSON application code.

AbstractTestCase

The \Aeris\ZendRestModuleTest\AbstractTestCase is an extension of the \Zend\Test\PHPUnit\Controller\AbstractHttpControllerTestCase. It provides a few utilities for testing restful APIs, and a number of new assertions. It is not necessary to use this test case class when working with the ZendRestModule.

Configuration Reference

Have fun!