Klanten Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Bundle Run in your Symfony project root:

   composer require common-gateway/klanten-bundle:dev-main
   

   For Dockerized environments:

   docker-compose exec php composer require common-gateway/klanten-bundle:dev-main
   

2. Install Entities & Schemas Execute the installation command to generate entities and database schemas:

   php bin/console commongateway:install common-gateway/klanten-bundle
   

   Or in Docker:

   docker-compose exec php bin/console commongateway:install common-gateway/klanten-bundle
   

3. Verify Installation Check if the bundle’s routes, entities, and migrations are registered:

   php bin/console debug:container | grep klanten
   

4. First Use Case: CRUD Operations The bundle likely includes a Klanten entity (Dutch for "clients"). Test basic CRUD via:

   php bin/console make:crud KlantenBundle:Klanten
   

   (If the bundle provides a custom API, refer to its src/Resources/config/routes.yaml.)

Implementation Patterns

Core Workflows

1. Plugin-Based Architecture

   • Treat the bundle as a modular extension. Use it to add client management features (e.g., profiles, permissions) without modifying core logic.
   • Example: Extend Symfony’s security system to integrate Klanten entities as user providers:

     # config/packages/security.yaml
     providers:
         klanten_provider:
             id: KlantenBundle\Security\KlantenUserProvider
     

2. Command-Driven Setup

   • Leverage the commongateway:install command to automate schema/entity generation. Override it in your bundle:

     // src/Command/InstallCommand.php
     class InstallCommand extends CommonGatewayInstallCommand {
         protected function configure(): void {
             $this->setName('app:install-klanten');
         }
     }
     

3. Event Listeners for Integration

   • Hook into Symfony events to react to Klanten changes. Example:

     // src/EventListener/KlantenListener.php
     class KlantenListener implements EventSubscriber {
         public static function getSubscribedEvents(): array {
             return [
                 KernelEvents::VIEW => ['onKernelView', 20],
             ];
         }
         public function onKernelView(ViewEvent $event) { ... }
     }
     

4. API/Controller Layer

   • Use the bundle’s built-in routes (check src/Resources/config/routes.yaml) or create custom controllers:

     // src/Controller/KlantenController.php
     class KlantenController extends AbstractController {
         #[Route('/api/klanten', name: 'klanten_list')]
         public function list(KlantenRepository $repo): Response {
             return $this->json($repo->findAll());
         }
     }
     

5. Doctrine Entity Extensions

   • Extend the Klanten entity with custom fields or behaviors:

     // src/Entity/KlantenExtension.php
     #[ORM\Entity]
     class KlantenExtension {
         #[ORM\ManyToOne(targetEntity: User::class)]
         private ?User $owner = null;
     }
     

Integration Tips

• Database Migrations: Run php bin/console doctrine:migrations:diff after installing the bundle to generate migrations for new tables.
• Symfony Flex Recipes: If the bundle includes a recipe (e.g., for auto-configuration), check composer.json for extra.symfony.endpoint or extra.symfony.recipe.
• Testing: Use the bundle’s entities in PHPUnit tests:

  public function testKlantenEntity(): void {
      $klant = new Klanten();
      $this->assertInstanceOf(Klanten::class, $klant);
  }
  

• Translation: If the bundle supports i18n, configure it in config/packages/translation.yaml:

  imports:
      - { resource: "@KlantenBundle/Resources/config/translation.yaml" }
  

Gotchas and Tips

Pitfalls

1. Dev-Main Dependency

   • The package is installed from dev-main. Ensure your composer.json has:

     "minimum-stability": "dev",
     "prefer-stable": false
     

   • Avoid in production; pin to a stable release when available.

2. Namespace Collisions

   • The bundle may use KlantenBundle namespace. If your project also uses Klanten, rename the bundle’s namespace in composer.json:

     "autoload": {
         "psr-4": {
             "App\\": "src/",
             "CommonGateway\\Klanten\\": "vendor/common-gateway/klanten-bundle/src/"
         }
     }
     

3. Missing Documentation

   • The README lacks details on the admin UI integration (@todo!). Assume the bundle provides:
     • A Klanten entity with basic fields (e.g., name, email, createdAt).
     • CRUD routes under /klanten.
   • Check src/Resources/config/doctrine/ for entity definitions.

4. Command Overrides

   • If you extend commongateway:install, ensure your command’s class is autoloaded. Add to composer.json:

     "autoload-dev": {
         "psr-4": {
             "App\\Command\\": "src/Command/"
         }
     }
     

5. Doctrine Lifecycle Callbacks

   • The bundle may use callbacks (e.g., @ORM\PrePersist). Test these with:

     $klant = new Klanten();
     $entityManager->persist($klant);
     $entityManager->flush(); // Triggers callbacks
     

Debugging Tips

1. Check Bundle Registration

   • Verify the bundle is loaded:

     php bin/console debug:container KlantenBundle
     

   • If missing, ensure it’s in config/bundles.php:

     return [
         // ...
         CommonGateway\KlantenBundle\KlantenBundle::class => ['all' => true],
     ];
     

2. Database Schema Issues

   • If migrations fail, dump the schema manually:

     php bin/console doctrine:schema:update --dump-sql
     

   • Compare with the bundle’s expected schema in src/Resources/config/doctrine/Klanten.orm.xml.

3. Route Conflicts

   • Dump routes to debug conflicts:

     php bin/console debug:router | grep klanten
     

   • Exclude the bundle’s routes if needed:

     # config/routes.yaml
     _klanten:
         resource: "@KlantenBundle/Resources/config/routes.yaml"
         prefix: "/admin" # Isolate routes
     

4. Event Dispatcher Issues

   • Listen for events to debug bundle interactions:

     $dispatcher->addListener(KernelEvents::CONTROLLER, function (ControllerEvent $event) {
         error_log("Controller: " . $event->getController()[0]::class);
     });
     

Extension Points

1. Custom Entities

   • Extend the Klanten entity by creating a new entity that references it:

     #[ORM\Entity]
     class ClientProfile {
         #[ORM\OneToOne(targetEntity: Klanten::class, inversedBy: "profile")]
         private ?Klanten $klanten;
     }
     

2. API Platform Integration

   • If using API Platform, expose the Klanten entity:

     # config/api_platform/resources.yaml
     resources:
         CommonGateway\KlantenBundle\Entity\Klanten:
             collectionOperations:
                 get:
                     method: GET
                     path: /klanten
     

3. Symfony UX Integration

   • Use the bundle’s data with Symfony UX (e.g., Turbo):

     {# templates/klanten/index.html.twig #}
     <turbo-frame id="klanten-list">
         {% for klant in klanten %}
             <div>{{ klant.name }}</div>
         {% endfor %}
     </turbo-frame>
     

4. Messenger Integration

   • Dispatch events when Klanten entities are created/updated:

     $klant->addEvent(new KlantenCreatedEvent($klant));
     $dispatcher->dispatch($klant->getEvents());
     

5. Custom Admin UI

   • Override the bundle’s admin templates by copying its resources:

     mkdir -p templates/bundles/KlantenBundle/
     cp vendor/common-gateway/klanten-bundle/templates/* templates/bundles/KlantenBundle/