Kunstmaan Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require devigner/kunstmaan-api-bundle
   

   Ensure KunstmaanBundlesCMS is installed as a dependency.

2. Bundle Configuration Add to config/bundles.php:

   return [
       // ...
       Devigner\KunstmaanApiBundle\DevignerKunstmaanApiBundle::class => ['all' => true],
   ];
   

3. First Use Case: Expose a Page

   • Create a PageModel class implementing PageModelInterface:

     use Devigner\KunstmaanApiBundle\Model\PageEntityInterface;
     
     class MyPageModel implements PageEntityInterface {
         // Implement required methods (e.g., getTitle(), getContent())
     }
     

   • Extend your Page entity to implement PageModelInterface:

     use Devigner\KunstmaanApiBundle\Entity\PageModelInterface;
     
     class MyPage implements PageInterface, PageModelInterface {
         // Delegate API methods to MyPageModel
     }
     

   • Register the model in services.yaml:

     services:
         App\Model\MyPageModel:
             tags: ['kunstmaan_api.page_model']
     

Implementation Patterns

Core Workflows

1. Page Exposure

   • Model-Driven API: Use PageEntityInterface to define API contracts (e.g., getTitle(), getSlug()).
   • Serialization: Leverage Symfony’s Serializer component (auto-configured) for JSON output.
   • Example:

     // In a controller
     $page = $this->getDoctrine()->getRepository(MyPage::class)->find($id);
     return $this->json($page->getApiModel()); // Returns PageModelInterface
     

2. PageParts Integration

   • PagePart Models: Implement PagePartsModelInterface for custom page parts:

     class MyPagePartModel implements PagePartsModelInterface {
         public function getData(): array {
             return ['key' => 'value'];
         }
     }
     

   • Entity Binding: Extend PagePartInterface and bind the model:

     class MyPagePart implements PagePartInterface, PagePartsModelInterface {
         private MyPagePartModel $model;
     
         public function __construct(MyPagePartModel $model) {
             $this->model = $model;
         }
     
         public function getApiModel(): PagePartsModelInterface {
             return $this->model;
         }
     }
     

3. Overview Pages (e.g., Newspages)

   • Entity Injection: Implement EntityInjectionInterface to customize API responses:

     class NewsPage implements EntityInjectionInterface {
         public function injectEntities(array $entities): array {
             return array_map(fn($entity) => $entity->getApiModel(), $entities);
         }
     }
     

4. Slug Handling

   • Event Listener: The SlugEventListener (auto-registered) ensures slugs are resolved for API routes.
   • Customization: Override slug logic in services.yaml:

     Devigner\KunstmaanApiBundle\EventListener\SlugEventListener:
         arguments:
             - ['@my_custom_menu_service'] # Replace with your menu service
     

Gotchas and Tips

Pitfalls

1. Missing Model Implementations

   • Error: Class "App\Model\MyPageModel" does not implement "Devigner\KunstmaanApiBundle\Model\PageEntityInterface".
   • Fix: Ensure all required methods (e.g., getTitle(), getSlug()) are implemented. Use PageEntityInterface as a base class if possible.

2. Circular Dependencies

   • Error: Cannot autowire service "App\Entity\MyPage": Argument "$model" not found.
   • Fix: Explicitly define model dependencies in services.yaml:

     App\Entity\MyPage:
         arguments:
             $model: '@App\Model\MyPageModel'
     

3. Slug Resolution Failures

   • Error: No menu found for slug resolution.
   • Fix: Verify kunstmaan_menu.menus service is properly configured in services.yaml or override the SlugEventListener arguments.

4. Deprecated Kunstmaan Version

   • Warning: The bundle was last updated in 2019 and may not support newer Kunstmaan versions (e.g., v4+).
   • Workaround: Check compatibility or fork the bundle for updates.

Debugging Tips

1. API Response Validation Use Symfony’s Serializer debug tool to validate output:

   php bin/console debug:serializer
   

2. Event Listener Debugging Enable debug mode to trace SlugEventListener:

   // In config/packages/dev.php
   framework:
       profiler: { only_exceptions: false }
   

3. Model Binding Dump model bindings to verify injection:

   $page = $this->getDoctrine()->getRepository(MyPage::class)->find(1);
   dump(get_class_methods($page->getApiModel())); // Check implemented methods
   

Extension Points

1. Custom Serialization Groups Annotate models to control serialized fields:

   use Symfony\Component\Serializer\Annotation\Groups;
   
   class MyPageModel implements PageEntityInterface {
       #[Groups(['api'])]
       public function getTitle(): string { ... }
   }
   

2. API Route Customization Override the default API routes by extending the bundle’s routing loader:

   # config/routes.yaml
   kunstmaan_api:
       resource: "@DevignerKunstmaanApiBundle/Resources/config/routing.yaml"
       prefix: /api
       defaults: { _controller: "App\Controller\ApiController::index" }
   

3. Dynamic Model Resolution Use a factory pattern to resolve models dynamically:

   class PageModelFactory {
       public function createFromEntity(PageInterface $page): PageEntityInterface {
           return new MyPageModel($page->getTitle(), $page->getSlug());
       }
   }