Customerio Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require dubture/customerio-bundle

Register the bundle in config/bundles.php:

return [
    // ...
    Dubture\CustomerIOBundle\DubtureCustomerIOBundle::class => ['all' => true],
];

2. Configuration: Add your site_id and api_key in config/packages/dubture_customer_io.yaml:

   dubture_customer_io:
       site_id: "%env(CUSTOMERIO_SITE_ID)%"
       api_key: "%env(CUSTOMERIO_API_KEY)%"
   

3. First Use Case:

   • Create a Customer entity implementing Dubture\CustomerIOBundle\Model\CustomerInterface.
   • Dispatch a TrackingEvent or ActionEvent via the event dispatcher to send data to Customer.io.

Implementation Patterns

Customer Model Integration

1. Implement CustomerInterface:

   use Dubture\CustomerIOBundle\Model\CustomerInterface;
   
   class AppCustomer implements CustomerInterface
   {
       public function getId(): string
       {
           return $this->id;
       }
   
       public function getEmail(): ?string
       {
           return $this->email;
       }
   
       // Other required methods (e.g., getName(), getCustomAttributes())
   }
   

2. Use in Controllers/Commands:

   use Dubture\CustomerIOBundle\Event\TrackingEvent;
   use Symfony\Component\EventDispatcher\EventDispatcherInterface;
   
   public function trackEvent(EventDispatcherInterface $dispatcher, AppCustomer $customer)
   {
       $event = new TrackingEvent($customer, 'purchase', ['amount' => 99.99]);
       $dispatcher->dispatch($event);
   }
   

Event Tracking Workflows

1. Track User Actions:

   // Example: Track a "view_product" event
   $event = new TrackingEvent($customer, 'view_product', [
       'product_id' => $product->id,
       'category' => $product->category,
   ]);
   $dispatcher->dispatch($event);
   

2. Identify Customers:

   // Example: Identify a user via email
   $event = new ActionEvent($customer, 'identify');
   $dispatcher->dispatch($event);
   

3. Batch Processing: Use Symfony’s EventSubscriber to automate tracking:

   use Dubture\CustomerIOBundle\Event\TrackingEvents;
   
   class CustomerIOSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'app.customer.purchased' => 'onCustomerPurchased',
           ];
       }
   
       public function onCustomerPurchased(TrackingEvent $event)
       {
           $event->setName('purchase');
           $event->setData(['amount' => $event->getCustomer()->getPurchaseAmount()]);
       }
   }
   

Integration Tips

• Dependency Injection: Inject Dubture\CustomerIOBundle\CustomerIO service directly for low-level API calls.
• Environment Variables: Store site_id and api_key in .env for security.
• Testing: Mock the CustomerIO service in unit tests to avoid real API calls.

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • Last release in 2015 may lack compatibility with modern Symfony (5.4+/6.x). Test thoroughly.
   • Consider forking or replacing with official Customer.io PHP SDK.

2. Event Dispatching:

   • Ensure TrackingEvent/ActionEvent are dispatched after the customer object is fully hydrated (e.g., lazy-loaded relations).
   • Example pitfall:

     // ❌ Avoid: Dispatching before loading customer data
     $dispatcher->dispatch(new TrackingEvent($customer, 'view')); // $customer->getData() may return null
     

3. Configuration Overrides:

   • The bundle expects config.yml (legacy). Use config/packages/ for Symfony 4+:

     # config/packages/dubture_customer_io.yaml
     dubture_customer_io:
         site_id: "%env(CUSTOMERIO_SITE_ID)%"
     

Debugging

1. API Errors:

   • Enable debug mode and check Symfony logs for GuzzleHttp exceptions (if used internally).
   • Validate site_id/api_key in Customer.io dashboard.

2. Event Not Firing:

   • Verify the event name matches the subscriber’s subscribed events.
   • Use debug:event-dispatcher to list active subscribers:

     php bin/console debug:event-dispatcher
     

Extension Points

1. Custom Attributes:

   • Extend CustomerInterface to add domain-specific methods (e.g., getLifetimeValue()).

2. Event Modifiers:

   • Subscribe to TrackingEvent to modify payloads before sending:

     $event->setData(array_merge($event->getData(), ['custom_flag' => true]));
     

3. API Wrapper:

   • Override Dubture\CustomerIOBundle\CustomerIO to add retries or logging:

     class CustomCustomerIO extends CustomerIO
     {
         public function sendEvent($event)
         {
             \Log::info('Sending to Customer.io:', $event);
             parent::sendEvent($event);
         }
     }
     

   • Register as a service with tags: ['customerio.client'].

Tips for Modern Laravel-Like Workflows

1. Service Providers:

   • Bind the bundle’s services to Laravel’s container (if using Symfony components):

     $this->app->bind('customerio', function ($app) {
         return new \Dubture\CustomerIOBundle\CustomerIO(
             $app['config']['dubture_customer_io.site_id'],
             $app['config']['dubture_customer_io.api_key']
         );
     });
     

2. Queue Events:

   • Dispatch events to a queue (e.g., Symfony Messenger) to avoid blocking requests:

     $dispatcher->dispatch(new TrackingEvent($customer, 'signup'));
     // Later, process via a worker
     

3. Laravel Facade:

   • Create a facade for convenience:

     use Dubture\CustomerIOBundle\CustomerIO;
     
     class CustomerIOFacade extends \Illuminate\Support\Facades\Facade
     {
         protected static function getFacadeAccessor() { return 'customerio'; }
     }
     

   • Usage:

     CustomerIO::track($customer, 'event_name', ['data']);
     

---