S365 Id Mapping Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require amitrev/bash-s365-id-mapping-bundle
   

2. Configure Environment Add the required .env variables (see README) and copy the config template:

   mkdir -p config/packages && cp vendor/amitrev/bash-s365-id-mapping-bundle/recipe/config/packages/s365_id_mapping.yaml config/packages/
   

3. First Use Case Inject the S365IdMappingClientInterface into a service/controller:

   use Amitrev\S365IdMappingBundle\Client\S365IdMappingClientInterface;
   
   public function __construct(
       private S365IdMappingClientInterface $client
   ) {}
   
   public function mapId(string $externalId): array
   {
       return $this->client->mapId($externalId);
   }
   

Implementation Patterns

Core Workflows

1. Direct API Calls Use the S365IdMappingClientInterface for typed responses:

   $mapping = $this->client->getMappingByExternalId('ext_123');
   // Returns a structured object (e.g., `MappingResult`).
   

2. Proxy Controller Enable the proxy endpoint (via s365_id_mapping.yaml) to forward requests:

   s365_id_mapping:
       proxy: true
   

   Access via /api/s365/proxy with payload:

   { "method": "GET", "endpoint": "/mappings", "params": {} }
   

3. Correlation IDs Pass a X-Correlation-ID header for traceability:

   $this->client->mapId('ext_123', ['headers' => ['X-Correlation-ID' => 'abc123']]);
   

Integration Tips

• Dependency Injection Prefer constructor injection for the client interface to swap implementations (e.g., mocks in tests).
• Caching Leverage Symfony’s cache system for OAuth tokens (configure in s365_id_mapping.yaml):

  s365_id_mapping:
      cache:
          enabled: true
          pool: cache.app
  

• Event Listeners Extend the bundle’s S365IdMappingEvent for custom logic (e.g., logging):

  use Amitrev\S365IdMappingBundle\Event\S365IdMappingEvent;
  
  public function onMappingRequest(S365IdMappingEvent $event) {
      $this->logger->info('Mapping request', ['id' => $event->getExternalId()]);
  }
  

Gotchas and Tips

Pitfalls

1. OAuth Token Expiry

   • The bundle caches tokens by default, but invalid tokens may cause silent failures.
   • Fix: Clear cache or adjust token_ttl in config:

     s365_id_mapping:
         auth:
             token_ttl: 3500  # 58 minutes (S365’s default)
     

2. Proxy Controller Security

   • The proxy endpoint exposes raw API calls. Restrict access via firewall:

     # config/packages/security.yaml
     access_control:
         - { path: ^/api/s365/proxy, roles: ROLE_TRUSTED }
     

3. Type Safety

   • Raw API responses are converted to objects, but malformed data may throw JsonException.
   • Tip: Use try-catch or validate inputs:

     try {
         $mapping = $this->client->getMappingByInternalId('int_123');
     } catch (\JsonException $e) {
         $this->logger->error('Invalid S365 response', ['error' => $e->getMessage()]);
     }
     

Debugging

• Enable API Logging Add to s365_id_mapping.yaml:

  s365_id_mapping:
      debug: true
  

  Logs will appear in var/log/dev.log.

• Inspect Headers Use S365IdMappingEvent to debug request/response headers:

  $event->getRequestHeaders(); // Before request
  $event->getResponseHeaders(); // After response
  

Extension Points

1. Custom Responses Override the default MappingResult DTO by binding your class to amitrev.s365_id_mapping.response.mapping:

   # config/services.yaml
   services:
       App\Dto\CustomMappingResult:
           tags:
               - { name: amitrev.s365_id_mapping.response.mapping }
   

2. Auth Provider Replace the OAuth handler by implementing S365AuthProviderInterface and configure:

   s365_id_mapping:
       auth:
           provider: App\Auth\CustomS365AuthProvider
   

3. HTTP Client Use Symfony’s HttpClientInterface for custom transport (e.g., retries):

   $client = new \Symfony\Contracts\HttpClient\HttpClient(
       ['timeout' => 30, 'max_retries' => 3]
   );
   $this->client->setHttpClient($client);