Customerbridgebundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alpixel/customerbridgebundle
   

   Add to bundles.php:

   return [
       // ...
       Alpixel\CustomerBridgeBundle\AlpixelCustomerBridgeBundle::class => ['all' => true],
   ];
   

2. Configuration Override default settings in config/packages/alpixel_customer_bridge.yaml:

   alpixel_customer_bridge:
       api_endpoint: 'https://api.example.com'
       api_key: '%env(API_KEY)%'
       sonata_admin: 'sonata.admin.user' # Default Sonata admin class
   

3. First Use Case Extend a Sonata admin class to use the bridge:

   use Alpixel\CustomerBridgeBundle\Admin\BridgeableAdminInterface;
   use Alpixel\CustomerBridgeBundle\Admin\BridgeableAdminTrait;
   
   class CustomUserAdmin extends SonataAdminService
       implements BridgeableAdminInterface
   {
       use BridgeableAdminTrait;
   
       // Implement required methods:
       public function getBridgeableModel(): string { return 'User'; }
       public function getBridgeableFields(): array { return ['email', 'name']; }
   }
   

Implementation Patterns

Core Workflow

1. Bridgeable Admin Integration

   • Implement BridgeableAdminInterface in Sonata admin classes.
   • Use BridgeableAdminTrait to auto-generate bridge methods.
   • Override syncWithBridge() to customize sync logic:

     protected function syncWithBridge($object, $bridgeData): void {
         $object->setEmail($bridgeData['email']);
         $this->save($object);
     }
     

2. API Interaction

   • Use the CustomerBridgeClient service for API calls:

     $client = $this->get('alpixel_customer_bridge.client');
     $response = $client->getUser('user@example.com');
     

   • Handle responses with DTOs (extend BridgeResponse):

     class UserBridgeResponse extends BridgeResponse {
         public function getExternalId(): string { return $this->data['external_id']; }
     }
     

3. Event-Driven Sync

   • Listen to customer.bridge.sync events:

     $dispatcher->addListener('customer.bridge.sync', function (SyncEvent $event) {
         // Custom logic before/after sync
     });
     

   • Trigger manual syncs via CLI:

     php bin/console alpixel:customer-bridge:sync --admin=sonata.admin.user
     

Integration Tips

• Field Mapping: Define getBridgeableFields() to auto-map fields between Sonata and the bridge API.
• Batch Processing: Use CustomerBridgeBatchProcessor for large datasets:

  $processor = $this->get('alpixel_customer_bridge.batch_processor');
  $processor->process($adminClass, $batchSize = 50);
  

• Webhook Handling: Extend WebhookHandlerInterface for incoming webhook events:

  class CustomWebhookHandler implements WebhookHandlerInterface {
      public function handle(array $payload): void {
          // Update Sonata entities based on payload
      }
  }
  

Gotchas and Tips

Common Pitfalls

1. Deprecation Warnings

   • The bundle targets Symfony 2.8 and Sonata 2.4.x-dev. Avoid mixing with newer versions without forks.
   • Fix: Use composer require sonata-project/admin-bundle:2.4.* explicitly.

2. API Key Management

   • Hardcoding api_key in config violates security best practices.
   • Fix: Use %env(API_KEY)% and ensure .env is in .gitignore.

3. Field Mismatches

   • Undefined fields in getBridgeableFields() cause silent failures.
   • Fix: Validate fields exist in both Sonata and the bridge API schema.

4. Circular Dependencies

   • The bundle assumes Sonata is already configured. Adding it late may break routes.
   • Fix: Load Sonata bundles before AlpixelCustomerBridgeBundle in bundles.php.

Debugging Tips

• Enable API Logging Add to config/packages/monolog.yaml:

  handlers:
      customer_bridge:
          type: stream
          path: "%kernel.logs_dir%/customer_bridge.log"
          level: debug
          channels: ["alpixel_customer_bridge"]
  

• Check Sync Status Use the alpixel:customer-bridge:status command:

  php bin/console alpixel:customer-bridge:status --admin=sonata.admin.user
  

Extension Points

1. Custom Sync Strategies Override CustomerBridgeSyncStrategy to implement custom logic:

   class CustomSyncStrategy extends CustomerBridgeSyncStrategy {
       protected function resolveConflict($localData, $remoteData): array {
           // Custom conflict resolution
       }
   }
   

   Register in services.yaml:

   services:
       Alpixel\CustomerBridgeBundle\Sync\CustomerBridgeSyncStrategy:
           class: App\Sync\CustomSyncStrategy
   

2. Webhook Validation Extend WebhookValidatorInterface to add payload checks:

   class StrictWebhookValidator implements WebhookValidatorInterface {
       public function validate(array $payload): bool {
           return isset($payload['signature']) && $this->verifySignature($payload);
       }
   }
   

3. Rate Limiting Implement RateLimitStrategyInterface for API throttling:

   class GuzzleRateLimitStrategy implements RateLimitStrategyInterface {
       public function apply(GuzzleHttp\Client $client): GuzzleHttp\Client {
           return $client->withConfig(['handler' => new RateLimitHandler()]);
       }
   }