Mailchimpbundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alexgoncharcherkassy/mailchimpbundle
   

   Add the bundle to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   AlexCk\MailchimpBundle\AlexCkMailchimpBundle::class => ['all' => true],
   

2. Configuration: Define Mailchimp credentials in config/packages/alexck_mailchimp.yaml (Symfony 4+):

   alexck_mailchimp:
       username: '%env(MAILCHIMP_USERNAME)%'
       api_key: '%env(MAILCHIMP_API_KEY)%'
       version: '3.0'
   

   Or configure dynamically in a service:

   $mailchimp = $this->get('alexck_mailchimp.client');
   $mailchimp->configure('username', 'api_key', '3.0');
   

3. First Use Case: Fetch all Mailchimp lists to verify connectivity:

   $lists = $mailchimp->getLists();
   dd($lists); // Debug the response
   

Implementation Patterns

Core Workflows

1. List Management:

   • Create a List:

     $contact = (new ListItemContact())->setEmail('user@example.com');
     $campaign = (new ListItemCampaignDefaults())->setFromName('Newsletter');
     $listItem = (new ListItem())
         ->setName('My List')
         ->setContact($contact)
         ->setCampaignDefaults($campaign);
     $createdList = $mailchimp->createList($listItem);
     

   • Batch Operations:

     $members = [
         (new Member())->setEmail('user1@example.com')->setMergeFields((new MemberMergeFields())->setFName('John')),
         (new Member())->setEmail('user2@example.com')->setMergeFields((new MemberMergeFields())->setFName('Jane')),
     ];
     $batchResp = $mailchimp->createBatchMember('list_id', $members);
     

2. Member Lifecycle:

   • Subscribe/Update:

     $member = (new Member())
         ->setEmail('user@example.com')
         ->setStatus('subscribed')
         ->setMergeFields((new MemberMergeFields())->setFName('John'));
     $mailchimp->createMember($member, 'list_id');
     

   • Unsubscribe:

     $mailchimp->createWebHookEventUnsubscribe('list_id', 'user@example.com');
     

   • Soft Delete:

     $member = (new Member())->setEmail('user@example.com');
     $mailchimp->deleteMember($member, 'list_id');
     

3. Event-Driven Integrations:

   • Use webhooks to trigger Laravel events (e.g., MemberUnsubscribed). Example:

     // In a controller or command
     $mailchimp->createWebHookEventUnsubscribe('list_id', 'user@example.com');
     event(new MemberUnsubscribed($member));
     

Integration Tips

• Service Container: Bind the client to a custom interface for easier testing/mocking:

  # config/services.yaml
  services:
      App\Service\MailchimpClientInterface: '@alexck_mailchimp.client'
  

• DTOs: Reuse ListItem, Member, and MemberMergeFields DTOs across services (e.g., API responses → Mailchimp sync).
• Error Handling: Wrap API calls in a try-catch to handle GuzzleHttp\Exception\RequestException:

  try {
      $mailchimp->createMember($member, 'list_id');
  } catch (\Exception $e) {
      $this->logger->error('Mailchimp error: ' . $e->getMessage());
      throw new \RuntimeException('Failed to sync with Mailchimp', 0, $e);
  }
  

Gotchas and Tips

Pitfalls

1. API Version Lock:

   • The package defaults to 3.0. Ensure your Mailchimp account supports this version; otherwise, update the configure() call:

     $mailchimp->configure('user', 'key', '2.0'); // Fallback to v2 if needed
     

   • Debugging: Check Mailchimp’s API status page for outages.

2. Rate Limits:

   • Mailchimp enforces rate limits. Batch operations (e.g., createBatchMember) help mitigate this, but log throttled requests:

     if ($batchResp->getStatusCode() === 429) {
         $this->logger->warning('Mailchimp rate limit exceeded');
     }
     

3. ID vs. Email:

   • The package uses Member::setId() for updates/deletes, but Mailchimp’s API often relies on email. Always verify the old_email parameter in updateMember():

     // Wrong: May fail if 'id1' doesn’t match the email
     $mailchimp->updateMember($member, 'list_id', 'wrong_email@example.com');
     

   • Fix: Fetch the member first to get the correct id:

     $member = $mailchimp->getMember('user@example.com', 'list_id');
     $member->setMergeFields((new MemberMergeFields())->setFName('Updated'));
     $mailchimp->updateMember($member, 'list_id', 'user@example.com');
     

4. Webhook Delays:

   • Webhook events (e.g., unsubscribes) may take seconds to minutes to process. Avoid relying on them for real-time syncs.

Tips

1. Environment Variables: Use .env for credentials:

   MAILCHIMP_USERNAME=your_username
   MAILCHIMP_API_KEY=your_api_key-us12
   

   Then reference them in alexck_mailchimp.yaml:

   alexck_mailchimp:
       username: '%env(MAILCHIMP_USERNAME)%'
       api_key: '%env(MAILCHIMP_API_KEY)%'
   

2. Testing:

   • Mock the client in PHPUnit:

     $this->mockBuilder()
         ->getContainer()
         ->andReturn($this->createMock(MailchimpClient::class));
     

   • Use Mailchimp’s sandbox environment for testing.

3. Extension Points:

   • Custom Endpoints: Extend the client to support unsupported endpoints (e.g., campaigns):

     $mailchimp->get('campaigns', [], 'campaigns');
     

   • Response Transformers: Decorate the client to transform responses (e.g., flatten arrays):

     $mailchimp->setResponseTransformer(function ($response) {
         return json_decode($response->getBody(), true);
     });
     

4. Logging: Enable Guzzle logging to debug API calls:

   $mailchimp->setClient(new \GuzzleHttp\Client([
       'handler' => \GuzzleHttp\HandlerStack::create(new \GuzzleHttp\Middleware::tap(function ($request) {
           $this->logger->debug('Mailchimp Request:', ['url' => (string) $request->getUri()]);
       }))
   ]));
   

5. Data Validation: Validate DTOs before sending to Mailchimp (e.g., ensure email is present in Member):

   if (empty($member->getEmail())) {
       throw new \InvalidArgumentException('Member email is required');
   }