Context Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bisonlab/context-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       BisonLab\ContextBundle\BisonLabContextBundle::class => ['all' => true],
   ];
   

2. Configuration Define contexts in config/packages/bisonlab_context.yaml:

   bisonlab_context:
       contexts:
           stripe_customer:
               class: App\Entity\Customer
               external_id_field: stripe_id
               external_service: stripe
   

3. First Use Case Link an entity to an external ID (e.g., Stripe):

   $customer = new Customer();
   $customer->setStripeId('cus_123abc');
   
   $contextManager = $this->container->get('bisonlab_context.manager');
   $contextManager->link($customer, 'stripe_customer', 'cus_123abc');
   

Implementation Patterns

Core Workflows

1. Linking Entities Use the ContextManager to bind internal entities to external IDs:

   $contextManager->link($entity, 'context_name', 'external_id');
   

2. Retrieving External IDs Fetch linked external IDs for an entity:

   $externalIds = $contextManager->getExternalIds($entity);
   // Returns: ['stripe_customer' => 'cus_123abc']
   

3. Reverse Lookup Find internal entities by external ID:

   $customer = $contextManager->findByExternalId('stripe_customer', 'cus_123abc');
   

Integration Tips

• Doctrine Events Trigger context updates on entity lifecycle events (e.g., prePersist):

  $entity->addLifecycleCallback(function ($entity) {
      $this->contextManager->link($entity, 'stripe_customer', $entity->getStripeId());
  });
  

• API Responses Attach external IDs to serialized entities:

  $serializer = $this->container->get('serializer');
  $data = $serializer->serialize($entity, 'json', [
      'context' => ['groups' => ['api']],
      'external_ids' => $this->contextManager->getExternalIds($entity),
  ]);
  

• Validation Ensure external IDs are unique per context:

  $this->contextManager->validateUnique('stripe_customer', 'cus_123abc');
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides Avoid hardcoding context names in business logic. Use the configured names from bisonlab_context.yaml to prevent runtime errors.

2. Circular Dependencies If using findByExternalId in a prePersist event, ensure the context isn’t already linked to avoid infinite loops.

3. Field Mismatches The external_id_field in config must match the actual entity property name (e.g., stripe_id vs. getStripeId()).

Debugging

• Missing Contexts Check config/packages/bisonlab_context.yaml for typos or missing entries. Run:

  php bin/console debug:config bisonlab_context
  

• Duplicate Links Enable Doctrine logging to trace duplicate link attempts:

  # config/packages/dev/doctrine.yaml
  doctrine:
      dbal:
          logging: true
  

Extension Points

1. Custom Context Providers Implement BisonLab\ContextBundle\Context\ContextProviderInterface for dynamic contexts:

   class CustomContextProvider implements ContextProviderInterface {
       public function getContexts(): array {
           return ['dynamic_context' => ['class' => MyEntity::class]];
       }
   }
   

   Register in services:

   services:
       App\Context\CustomContextProvider:
           tags: ['bisonlab_context.provider']
   

2. Event Listeners Extend context behavior via events (e.g., ContextLinkedEvent):

   $eventDispatcher->addListener(ContextLinkedEvent::class, function (ContextLinkedEvent $event) {
       // Log or notify on link changes
   });
   

3. Custom Validation Override the default uniqueness check by extending ContextManager and injecting a custom validator.