Relay Base Organization Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dbp/relay-base-organization-bundle
   

   Add to config/bundles.php before DbpRelayCoreBundle:

   Dbp\Relay\BaseOrganizationBundle\DbpRelayBaseOrganizationBundle::class => ['all' => true],
   

2. Clear Caches

   php bin/console cache:clear
   

3. First Use Case Implement OrganizationProviderInterface to fetch organizations. Example:

   // src/Service/OrganizationProvider.php
   namespace App\Service;
   
   use Dbp\Relay\BaseOrganizationBundle\API\OrganizationProviderInterface;
   use Dbp\Relay\BaseOrganizationBundle\Entity\Organization;
   
   class OrganizationProvider implements OrganizationProviderInterface
   {
       public function getOrganization(string $id): ?Organization
       {
           // Fetch from DB/API/cache (e.g., Doctrine, API client)
           return $this->fetchFromYourSource($id);
       }
   }
   

4. Register Service Add to services.yaml:

   services:
       App\Service\OrganizationProvider:
           tags: ['relay.organization_provider']
   

Implementation Patterns

Core Workflows

1. Organization Resolution Use the bundle’s dependency-injected OrganizationProvider to resolve organizations in controllers/services:

   use Dbp\Relay\BaseOrganizationBundle\API\OrganizationProviderInterface;
   
   class MyController
   {
       public function __construct(private OrganizationProviderInterface $orgProvider) {}
   
       public function show(Organization $org)
       {
           $orgData = $this->orgProvider->getOrganization($org->getId());
           // ...
       }
   }
   

2. Event-Driven Extensions Listen to OrganizationEvents (if provided) to extend behavior:

   // src/EventListener/OrganizationListener.php
   use Dbp\Relay\BaseOrganizationBundle\Event\OrganizationEvent;
   
   class OrganizationListener
   {
       public function onOrganizationFetch(OrganizationEvent $event)
       {
           $event->setOrganization($this->enrichOrganization($event->getOrganization()));
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\OrganizationListener:
           tags: ['kernel.event_listener', { event: 'relay.organization.fetch', method: 'onOrganizationFetch' }]
   

3. API Integration For Relay API responses, use the bundle’s serializers (if available) to normalize Organization entities:

   use Dbp\Relay\BaseOrganizationBundle\Serializer\OrganizationNormalizer;
   
   $normalizer = new OrganizationNormalizer($this->orgProvider);
   $data = $normalizer->normalize($organization);
   

4. Caching Layer Decorate OrganizationProviderInterface to add caching:

   class CachedOrganizationProvider implements OrganizationProviderInterface
   {
       public function __construct(
           private OrganizationProviderInterface $decorated,
           private CacheInterface $cache
       ) {}
   
       public function getOrganization(string $id): ?Organization
       {
           return $this->cache->get($id, fn() => $this->decorated->getOrganization($id));
       }
   }
   

Gotchas and Tips

Pitfalls

1. Bundle Loading Order

   • Critical: The bundle must be loaded before DbpRelayCoreBundle. Misordering causes OrganizationProvider to fail silently.

2. Missing Service Tag

   • Forgetting to tag the service with relay.organization_provider prevents the bundle from autowiring it. Verify with:

     php bin/console debug:container App\Service\OrganizationProvider
     

3. Entity Mismatch

   • The bundle expects Organization entities to match its Entity\Organization structure. Override or extend carefully to avoid serialization errors.

4. No Built-in CRUD

   • The bundle provides fetching only. Use Doctrine or another ORM for persistence logic.

5. Relay API Dependency

   • Assumes integration with DbpRelayCoreBundle. Standalone use may require manual setup of serializers/validators.

Debugging Tips

1. Check Provider Availability Dump the registered providers:

   php bin/console debug:container relay.organization_provider
   

2. Validate Entity Structure Compare your Organization entity with the bundle’s Entity\Organization to catch serialization issues:

   $reflection = new ReflectionClass($yourOrgEntity);
   $bundleReflection = new ReflectionClass(\Dbp\Relay\BaseOrganizationBundle\Entity\Organization::class);
   

3. Enable Relay Debugging Add to .env:

   RELAY_DEBUG=true
   

   To log provider calls.

4. Test Provider Isolation Mock the provider in tests to avoid DB/API calls:

   $this->mockBuilder->disableOriginalConstructor()
       ->getMockBuilder(OrganizationProviderInterface::class)
       ->addMethods(['getOrganization'])
       ->getMock();
   

Extension Points

1. Custom Providers Implement OrganizationProviderInterface for multi-source fetching (e.g., DB + external API):

   class HybridOrganizationProvider implements OrganizationProviderInterface
   {
       public function getOrganization(string $id): ?Organization
       {
           $dbOrg = $this->dbProvider->getOrganization($id);
           if ($dbOrg) return $dbOrg;
   
           return $this->apiProvider->fetchFromExternal($id);
       }
   }
   

2. Event Subscribers Extend OrganizationEvent (if available) to add pre/post-fetch logic:

   class AuditOrganizationSubscriber
   {
       public function onOrganizationFetched(OrganizationEvent $event)
       {
           $this->auditLogger->log(
               'organization.fetched',
               ['id' => $event->getOrganization()->getId()]
           );
       }
   }
   

3. Serializer Overrides Customize JSON:XML output by extending the normalizer:

   class CustomOrganizationNormalizer extends OrganizationNormalizer
   {
       public function normalize($object, $format = null, array $context = [])
       {
           $data = parent::normalize($object, $format, $context);
           $data['custom_field'] = $this->getCustomField($object);
           return $data;
       }
   }
   

   Register in services.yaml:

   services:
       App\Serializer\CustomOrganizationNormalizer:
           decorates: 'relay.organization_normalizer'
           arguments: ['@.inner']