Controller for handling resources.

Extends the base AbstractRestfulController in order to provide very specific semantics for building a RESTful JSON service. All operations return either

  • a HAL-compliant response with appropriate hypermedia links
  • a Problem API-compliant response for reporting an error condition

You may specify what specific HTTP method types you wish to respond to, and OPTIONS will then report those; attempting any HTTP method falling outside that list will result in a 405 (Method Not Allowed) response.

I recommend using resource-specific factories when using this controller, to allow injecting the specific resource you wish to use (and its listeners), which will also allow you to have multiple instances of the controller when desired.

see \PhlyRestfully\http://tools.ietf.org/html/draft-kelly-json-hal-03
see \PhlyRestfully\http://tools.ietf.org/html/draft-nottingham-http-problem-02

 Methods

Constructor

__construct(null | string $eventIdentifier) 

Allows you to set the event identifier, which can be useful to allow multiple instances of this controller to react to different sets of shared events.

Parameters

$eventIdentifier

nullstring

Create a new resource

create(array $data) : \Zend\Http\Response | \PhlyRestfully\ApiProblem | \PhlyRestfully\HalResource

Parameters

$data

array

Returns

Delete an existing resource

delete(int | string $id) : \Zend\Http\Response | \PhlyRestfully\ApiProblem

Parameters

$id

intstring

Returns

\Zend\Http\Response\PhlyRestfully\ApiProblem

deleteList()

deleteList() 

Return single resource

get(int | string $id) : \Zend\Http\Response | \PhlyRestfully\ApiProblem | \PhlyRestfully\HalResource

Parameters

$id

intstring

Returns

getIdentifierName()

getIdentifierName() : string

Returns

string

Return collection of resources

getList() : \Zend\Http\Response | \PhlyRestfully\HalCollection

Returns

\Zend\Http\Response\PhlyRestfully\HalCollection

Returns the resource

getResource() : \PhlyRestfully\ResourceInterface

Exceptions

\PhlyRestfully\Exception\DomainException If no resource has been set

Returns

Retrieve HEAD metadata for the resource and/or collection

head(null | mixed $id) : \Zend\Http\Response | \PhlyRestfully\ApiProblem | \PhlyRestfully\HalResource | \PhlyRestfully\HalCollection

Parameters

$id

nullmixed

Returns

Handle the dispatch event

onDispatch(\Zend\Mvc\MvcEvent $e) : mixed

Does several "pre-flight" checks: - Raises an exception if no resource is composed. - Raises an exception if no route is composed. - Returns a 405 response if the current HTTP request method is not in $options

When the dispatch is complete, it will check to see if an array was returned; if so, it will cast it to a view model using the AcceptableViewModelSelector plugin, and the $acceptCriteria property.

Parameters

$e

\Zend\Mvc\MvcEvent

Exceptions

\PhlyRestfully\Exception\DomainException

Returns

mixed

Respond to OPTIONS request

options() : \Zend\Http\Response

Uses $options to set the Allow header line and return an empty response.

Returns

\Zend\Http\Response

Respond to the PATCH method (partial update of existing resource)

patch(int | string $id, array $data) : \Zend\Http\Response | \PhlyRestfully\ApiProblem | \PhlyRestfully\HalResource

Parameters

$id

intstring

$data

array

Returns

Update an existing collection of resources

replaceList(array $data) : array

Parameters

$data

array

Returns

array

Set the Accept header criteria for use with the AcceptableViewModelSelector

setAcceptCriteria(array $criteria) 

Parameters

$criteria

array

Set the allowed HTTP OPTIONS for the resource (collection)

setCollectionHttpOptions(array $options) 

Parameters

$options

array

Set the name to which to assign a collection in a HalCollection

setCollectionName(string $name) 

Parameters

$name

string

Set the allowed content types for the resource (collection)

setContentTypes(array $contentTypes) 

Parameters

$contentTypes

array

Set the route match segment or query string parameter indicating the resource identifier

setIdentifierName(string $name) 

Parameters

$name

string

Set the default page size for paginated responses

setPageSize(int $count) 

Parameters

$count

int

Inject the resource with which this controller will communicate.

setResource(\PhlyRestfully\ResourceInterface $resource) 

Parameters

Set the allowed HTTP OPTIONS for a resource

setResourceHttpOptions(array $options) 

Parameters

$options

array

Inject the route name for this resource.

setRoute(string $route) 

Parameters

$route

string

Update an existing resource

update(int | string $id, array $data) : \Zend\Http\Response | \PhlyRestfully\ApiProblem | \PhlyRestfully\HalResource

Parameters

$id

intstring

$data

array

Returns