Allow returning HAL collections and entities from resources

[weierophinney]

This patch alters RestController to allow returning ZF\Hal\Entity and/or ZF\Hal\Collection instances from resources, allowing the ability to fully craft the payload before returning.

In particular, and specific to the issue this addresses, the create() method was updated to allow returning a Collection instance (which it didn't handle before).

When an Entity or Collection is returned, they are passed to one of createHalEntity() or createHalCollection():

• createHalEntity() returns the instance unchanged if it already has a self relational link or does not have an identifier; otherwise, it passes it to the Hal plugin's createEntity() method, which ensures that a self relational link is injected.
• createHalCollection() passes the instance on to a new method, prepareHalCollection(), which does the following:
  • Injects a self relational link if none is present.
  • Injects the controller-specific metadata (routing information, collection name, page size, and page).

These changes will simplify batch POST operations, as well as allow any method responsible for returning an entity or collection to return a specifically crafted one without requiring also creating the response.

This patch addresses both:

• Batch POST response does not include collection name #79
• Wrong response code for creating entities without id or with id = 0 #82