RPC with HAL JSON

gistfile1.php

<?php
namespace Test\V1\Rpc\Test;

use Zend\Mvc\Controller\AbstractActionController;
use ZF\ContentNegotiation\ViewModel;
use ZF\Hal\Entity;
use ZF\Hal\Link\Link;

class TestController extends AbstractActionController
{
    public function testAction()
    {
        $id   = 1;
        $data = array ( 'name' => 'Enrico Zimuel', 'id' => $id );

        $entity = new Entity($data, $id);
        $entity->getLinks()->add(Link::factory(array(
            'rel' => 'contacts',
            'route' => array(
                'name' => 'test.rest.user',
            )
        )));
        return new ViewModel(array(
            'payload' => $entity
        )); 
    }
}

I figured out why this has no self relational link!

In ZF\Rest\Rest\Controller, we always call the createEntity() method of the HAL plugin -- which injects the self relational link! Since you're not doing that here, no such link is created.

I discovered this when looking into another issue reported this week, and I'm strongly considering moving the link injection to renderEntity() and potentiallyrenderCollection()`.

@ezimuel In reading up on HAL and looking through our Hal plugin, two things:

• The "self" relational link is not strictly required, just strongly recommended (a SHOULD in IETF parlance, but not a MUST). As such, we do not, and should not, inject a self relational link for entities created in RPC controllers, and instead leave it up to the user whether or not they want to inject one.

• As to that latter point, this can be accomplished using the HAL plugin's injectSelfLink() method:

  $this->plugin('hal')->injectSelfLink($entity, $routeName, $routeIdentifierName);

  This will use the provided route name and route identifier name to create the self relational link.

Alternately, another approach is to use the plugin's createEntity() method. This takes the object you're exposing, plus the route and route identifier names, and returns a ZF\Hal\Entity instance with the self relational link injected:

$entity = $this->plugin('hal')->createEntity($data, $routeName, $routeIdentifierName);

So, now the question is: where should we put this in the manual! :)

I think we can add this information in this recipe https://www.apigility.org/documentation/recipes/hal-from-rpc, what do you think?