Halapi Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bigz/halapibundle
   

2. Register Bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   Bigz\HalapiBundle\BigzHalapiBundle::class => ['all' => true],
   

3. First Use Case:
   • Ensure your controller returns an entity or array. The bundle automatically injects HATEOAS links via JmsSerializer.
   • Example:

     use Symfony\Component\HttpFoundation\Response;
     
     public function showAction($id)
     {
         $entity = $this->getDoctrine()->getRepository(Entity::class)->find($id);
         return new Response($entity); // Serialized with HAL links
     }
     

Key Files to Review

• Configuration: Check config/packages/bigz_halapi.yaml (if auto-generated) or app/config/config.yml for overrides.
• Serializer: Extend Bigz\HalapiBundle\Serializer\HalapiSerializer if custom metadata is needed.
• Documentation: Refer to BigZ/Halapi for HAL/JSON:API specs.

Implementation Patterns

Core Workflow

1. Automatic HAL Injection:

   • The bundle hooks into JmsSerializer to append _links to serialized responses.
   • Example output:

     {
       "id": 1,
       "name": "Test",
       "_links": {
         "self": { "href": "/api/entities/1" }
       }
     }
     

2. JSON:API Mode (Experimental):

   • Set Content-Type: application/vnd.api+json header to transform output to JSON:API format.
   • Useful for APIs requiring strict JSON:API compliance.

3. Custom Link Providers:

   • Extend Bigz\HalapiBundle\LinkProvider\LinkProviderInterface to add dynamic links (e.g., admin actions).
   • Register via dependency injection:

     # config/services.yaml
     services:
         App\LinkProvider\CustomLinkProvider:
             tags: ['bigz_halapi.link_provider']
     

Integration Tips

• Doctrine Entities:
  • Use @Halapi\Link annotations (from BigZ/Halapi) on entity properties to define links:

    use BigZ\HalapiBundle\Annotation\Link;
    
    /**
     * @Link("self", route="entity_show", parameters={"id"="id"})
     */
    private $id;
    

• Symfony Events:
  • Listen to bigz_halapi.pre_serialization to modify HAL data before output:

    $eventDispatcher->addListener(
        'bigz_halapi.pre_serialization',
        function ($event) {
            $event->getData()->addLink('custom', '/custom-path');
        }
    );
    

• API Platform Integration:
  • Disable API Platform’s built-in HATEOAS if conflicts arise (configure via api_platform.metadata.extractor services).

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • Last release in 2018; test thoroughly. May require patches for Symfony 5+/6+.
   • Workaround: Fork and update dependencies (e.g., jms/serializer-bundle, symfony/framework-bundle).

2. JSON:API Limitations:

   • The "experimental" JSON:API mode may not fully comply with spec. Validate output against jsonapi.org.
   • Tip: Use a library like api for production JSON:API needs.

3. Link Provider Conflicts:

   • Multiple link providers may override each other. Prioritize via service tags or manual ordering:

     tags: ['bigz_halapi.link_provider', { priority: 100 }]
     

4. Caching Issues:

   • HAL links are generated per-request. Avoid caching serialized responses with dynamic links.

Debugging

• Check Serialization:
  • Enable JMS_SERIALIZER_DEBUG in .env to inspect serialization groups/metadata.
  • Log the final HAL data:

    $eventDispatcher->addListener('bigz_halapi.post_serialization', function ($event) {
        error_log(print_r($event->getData()->getLinks(), true));
    });
    

Extension Points

1. Custom Serializers:

   • Override the default serializer by configuring a custom serializer service:

     bigz_halapi:
         serializer: app.custom_serializer
     

   • Implement Bigz\HalapiBundle\Serializer\HalapiSerializerInterface.

2. Dynamic Link Generation:

   • Use bigz_halapi.link_provider events to inject links conditionally:

     $event->getData()->addLinkIf(
         'edit',
         '/edit',
         fn ($entity) => $entity->isEditable()
     );
     

3. Configuration Overrides:

   • Customize default link templates in config/packages/bigz_halapi.yaml:

     bigz_halapi:
         default_links:
             self: { route: "api_entity", parameters: { id: "id" } }