Hateoas Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require arte/hateoas-bundle
   

   Add the bundle to your config/bundles.php (Symfony):

   Arte\HateoasBundle\ArteHateoasBundle::class => ['all' => true],
   

2. Generate a Hateoas Adder Class Use the provided command to scaffold a Hateoas adder for your entity (e.g., Product):

   php bin/console arte:hateoas:generate Product
   

   This creates a class like ProductHateoasAdder in src/Entity/Product/Hateoas/.

3. First Use Case Inject the adder into your controller or service and apply it to a resource:

   use Arte\HateoasBundle\Hateoas\HateoasAdderInterface;
   
   class ProductController
   {
       public function show(Product $product, ProductHateoasAdder $adder)
       {
           $resource = new Resource($product);
           $adder->add($resource);
           return $this->jsonSerializer->serialize($resource, 'jsonld');
       }
   }
   

Implementation Patterns

Workflows

1. Entity-Centric Hateoas Generate a dedicated adder per entity (e.g., UserHateoasAdder, OrderHateoasAdder). Place them in a Hateoas sub-namespace under your entity.

2. Reusable Adders Extend base adders for shared logic (e.g., BaseCollectionHateoasAdder) and reuse them across multiple entities.

3. Dynamic Link Generation Use dependency injection to fetch routes dynamically:

   public function add(Resource $resource)
   {
       $resource->getItem()->getId(); // Access entity ID
       $resource->getUri() = $this->router->generate('product_show', ['id' => $id]);
   }
   

4. Integration with Serializers Chain the adder with your serializer (e.g., JsonLdSerializer):

   $serializer = $this->serializer->serialize($resource, 'jsonld', [
       'groups' => ['product:read'],
   ]);
   

Integration Tips

• Symfony Serializer: Ensure arte/hateoas-bundle is registered as a serializer normalizer.
• API Platform: Use the adder in ApiResource classes via serialize() or denormalize().
• Testing: Mock the adder to test HATEOAS links in unit tests:

  $adder = $this->createMock(ProductHateoasAdder::class);
  $adder->expects($this->once())->method('add');
  

Gotchas and Tips

Pitfalls

1. Circular References Avoid infinite loops when adding links to nested resources. Use Resource::getItem() carefully to check entity types.

2. Route Existence Ensure routes referenced in adders exist. Use RouteExistsListener or validate routes in tests:

   $this->assertTrue($this->router->getRouteCollection()->get('product_show'));
   

3. Overriding Defaults If extending BazingaHateoasBundle, ensure method signatures match (e.g., add() vs. addLinks()).

Debugging

• Log Missing Routes: Add a debug listener to log undefined routes:

  $this->router->getRouteCollection()->get('undefined_route'); // Throws exception
  

• Check Serialization Groups: Verify groups in your serializer context match the entity’s metadata.

Extension Points

1. Custom Link Providers Implement LinkProviderInterface for dynamic links (e.g., OAuth tokens):

   class AuthLinkProvider implements LinkProviderInterface
   {
       public function getLinks(Resource $resource): array
       {
           return ['auth' => ['href' => '/oauth/token']];
       }
   }
   

2. Event Listeners Trigger events before/after adding links (e.g., hateoas.add.links):

   $eventDispatcher->addListener('hateoas.add.links', function (HateoasEvent $event) {
       $event->getResource()->add(['custom' => ['href' => '/custom']]);
   });
   

3. Configuration Override default templates in config/packages/arte_hateoas.yaml:

   arte_hateoas:
       templates:
           link: '@ArteHateoas/link.html.twig'