zf-fr/ZfrRest — pull request #37 by bakura10 (2013-04-04 20:16:29+00:00)
Title: Cleanup and add collection annotation

Hi,

As stated on IRC with @ocramius, this PR includes a new metadata part for resource called "Collection". This hints ZfrRest how to handle things when resource is a collection. This metadata can be added with an annotation, like this:

```php
/**
* @REST\Controller(name="Application\Controller\UserItemController")
* @REST\Collection(controller="Application\Controller\UsersController", paginate=true)
*/
class User
```

The paginate property is optional and default to true. If this is to true, the route will automatically paginate any Collection/Selectable around a Zend\Paginator. Speaking about metadata, I'd like people to check the ZfrRest\Resource\Metadata\ResourceMetadataInterface. I'm really not sure about the naming, this interface starts to become quite big.

Concerning the Route, I cleaned it up a bit but I think we can make some simplifcations. Most of all, I think that the fact we swap continuously $this->resource incrementally can lead to problem, because this means that the initial resource is lost (and it will be a problem if we call assemble, because it won't have the initial resource as $this->resource, but the last one when we accessed the route). However, I'm having a hard time changing that because of the $resource confusion ($resource can be the resource, or a resource interface... it makes eveyrthing complicated to follow).

The route still have two methods :

* getAssembledParams: I have absolutely no idea how to write it and how we should return it.
* assemble: same problem I have no idea about how to it correctly. The problem is that because associations are discovered by the route and metadata, an hypotetical "/users" route won't have any child routes. Instead, /users/4/tweets will be available because of the resource metadata. This means that $this->url()->fromRoute('users/tweets') won't work.

I've thought about super complicated syntaxes like this:

```php
$this->url()->fromRoute('users', array('id' => 5), array(
'associations' => array(
array('name' => 'tweets', 'id' = > 6),
array('name' => 'retweets')
)
);
```

As you can see this is just super long just to output /users/5/tweets/6/retweets. And the syntax is weird (what this code would so is get the $this->route, append id, then check from metadata if it has association with tweets, then append id 6, and do this recursively until no association's left). But this is unintuitive, and I don't like it.

Well, once we have polished this route, I'll start write tests.