Sylius Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require splash/sylius-bundle
   

   Ensure Splash\Bundle\SplashBundle() is registered in config/bundles.php (or AppKernel.php for older Sylius versions).

2. Configuration Add Splash Sync credentials to config/packages/splash.yaml:

   splash:
       api_key: '%env(SPLASH_API_KEY)%'
       secret_key: '%env(SPLASH_SECRET_KEY)%'
       endpoint: '%env(SPLASH_ENDPOINT)%'
   

   Populate .env with your Splash Sync credentials.

3. First Use Case Sync a single product to Splash Sync:

   use Splash\Bundle\SplashBundle\Service\SplashSyncService;
   
   class ProductSyncCommand extends Command
   {
       protected static $defaultName = 'splash:sync:product';
   
       public function handle(SplashSyncService $splashSync)
       {
           $product = $this->productRepository->find(1);
           $splashSync->syncProduct($product);
       }
   }
   

Implementation Patterns

Core Workflows

1. Entity Synchronization Use the SplashSyncService to sync Sylius entities (products, orders, customers) via decorators:

   // Sync a product with custom mappings
   $splashSync->syncProduct($product, [
       'custom_field' => $product->getSomeAttribute(),
   ]);
   

2. Event-Driven Sync Subscribe to Sylius events to auto-sync on changes:

   // src/EventListener/SplashSyncListener.php
   class SplashSyncListener
   {
       public function __construct(private SplashSyncService $splashSync) {}
   
       public function onProductUpdate(ProductUpdateEvent $event)
       {
           $this->splashSync->syncProduct($event->getProduct());
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\SplashSyncListener:
           tags:
               - { name: kernel.event_listener, event: sylius.product.update }
   

3. Batch Processing Sync multiple entities efficiently:

   $products = $this->productRepository->findBy([], null, 50);
   $this->splashSync->syncProducts($products);
   

Integration Tips

• Sylius Extensions: Extend existing Sylius entities (e.g., Product, Order) to add Splash-specific fields:

  // src/Entity/ProductExtension.php
  class ProductExtension extends AbstractExtension
  {
      public function loadClassMetadata(ClassMetadata $metadata)
      {
          $metadata->mapFieldWithCustomType('splash_sync_id', 'string');
      }
  }
  

• API Versioning: Use Splash Sync’s API versioning via config:

  splash:
      api_version: v2
  

• Webhooks: Configure Splash Sync webhooks in config/packages/splash.yaml to handle external updates:

  splash:
      webhook:
          enabled: true
          secret: '%env(SPLASH_WEBHOOK_SECRET)%'
  

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Issue: 401 Unauthorized errors if API keys/secrets are misconfigured.
   • Fix: Verify .env and splash.yaml values. Use:

     php bin/console splash:validate-credentials
     

2. Rate Limiting

   • Issue: Splash Sync may throttle requests during bulk syncs.
   • Fix: Implement exponential backoff in custom sync logic:

     try {
         $splashSync->syncProduct($product);
     } catch (RateLimitException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

3. Entity Mapping Mismatches

   • Issue: Sync failures due to mismatched field names between Sylius and Splash Sync.
   • Fix: Override mappings in config/packages/splash.yaml:

     splash:
         mappings:
             product:
                 splash_field: sylius_field
     

4. Event Ordering

   • Issue: Race conditions if syncing during entity creation/updates.
   • Fix: Use kernel.event_dispatcher priority in listeners:

     tags:
         - { name: kernel.event_listener, event: sylius.product.create, priority: -10 }
     

Debugging

• Enable Debug Mode

  splash:
      debug: true
  

  Logs detailed sync operations to var/log/splash.log.

• Dry Runs Use the dry_run option to test syncs without committing:

  $splashSync->syncProduct($product, [], true); // Dry run
  

Extension Points

1. Custom Sync Handlers Extend SplashSyncService to handle custom entities:

   // src/Service/CustomSplashSyncService.php
   class CustomSplashSyncService extends SplashSyncService
   {
       public function syncCustomEntity($entity, array $options = [])
       {
           $this->client->post('/custom-endpoint', $this->mapEntity($entity, $options));
       }
   }
   

2. Webhook Handlers Create custom webhook subscribers:

   // src/EventListener/SplashWebhookListener.php
   class SplashWebhookListener
   {
       public function onWebhook(SplashWebhookEvent $event)
       {
           if ($event->getType() === 'order_updated') {
               $this->orderRepository->updateFromSplash($event->getData());
           }
       }
   }
   

3. Async Processing Offload syncs to a queue (e.g., Symfony Messenger):

   # config/packages/messenger.yaml
   framework:
       messenger:
           transports:
               splash: '%env(MESSENGER_TRANSPORT_DSN)%'
           routing:
               'Splash\Bundle\SplashBundle\Message\SyncProductMessage': splash