Brevo Php Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   Update to the latest version via Composer:
   ```bash
   composer require getbrevo/brevo-php:^5.0.1

Include the autoloader (unchanged):

require __DIR__ . '/vendor/autoload.php';

2. First API Call (Updated) Configure API key (replace YOUR_API_KEY):

   $config = Brevo\Client\Configuration::getDefaultConfiguration()
       ->setApiKey('api-key', 'YOUR_API_KEY');
   
   $apiInstance = new Brevo\Client\Api\ContactsApi(new GuzzleHttp\Client(), $config);
   

3. First Use Case: Fetch Contacts (with Consent Groups)

   try {
       $result = $apiInstance->getContacts();
       // New: Check for consentGroups in contact details
       if (isset($result['contacts'][0]['consentGroups'])) {
           print_r($result['contacts'][0]['consentGroups']);
       }
       print_r($result);
   } catch (Exception $e) {
       echo 'Error: ' . $e->getMessage();
   }
   

4. New: Consent Groups Management

   $consentGroupsApi = new Brevo\Client\Api\ConsentGroupsApi(new GuzzleHttp\Client(), $config);
   try {
       // List consent groups
       $groups = $consentGroupsApi->getConsentGroups();
       print_r($groups);
   
       // Create a new consent group
       $newGroup = new \Brevo\Client\Model\ConsentGroup([
           'name' => 'Marketing Newsletter',
           'description' => 'Consent for marketing emails',
           'signupMode' => 'SINGLE_OPTIN'
       ]);
       $createdGroup = $consentGroupsApi->createConsentGroup($newGroup);
       print_r($createdGroup);
   } catch (Exception $e) {
       echo 'Error: ' . $e->getMessage();
   }
   

Implementation Patterns

Common Workflows

1. Consent Groups Management (New)

• List Consent Groups:

  $consentGroupsApi = new Brevo\Client\Api\ConsentGroupsApi(new GuzzleHttp\Client(), $config);
  $groups = $consentGroupsApi->getConsentGroups();
  

• Create/Update Consent Group:

  $group = new \Brevo\Client\Model\ConsentGroup([
      'name' => 'Promotions',
      'description' => 'Opt-in for promotional offers',
      'signupMode' => 'DOUBLE_OPTIN' // SINGLE_OPTIN or DOUBLE_OPTIN
  ]);
  $created = $consentGroupsApi->createConsentGroup($group);
  

• Add Contacts to Consent Group:

  $consentGroupsApi->addContactsToConsentGroup($groupId, ['user1@example.com', 'user2@example.com']);
  

2. Contact Management (Updated)

• Import Contacts with Consent Groups:

  $importData = new \Brevo\Client\Model\ImportContactsRequest([
      'contacts' => [
          ['email' => 'user1@example.com', 'attributes' => ['AGE' => '30']],
          ['email' => 'user2@example.com', 'attributes' => ['AGE' => '25']]
      ],
      'consentGroupIds' => [123, 456] // Assign to multiple consent groups
  ]);
  $apiInstance->importContacts($importData);
  

• Fetch Contact with Consent Status:

  $contact = $apiInstance->getContact('user@example.com');
  print_r($contact['consentGroups']); // Array of consent group subscriptions
  

3. Wallet Integration (New)

• Generate Wallet Installation URL:

  $walletApi = new Brevo\Client\Api\WalletApi(new GuzzleHttp\Client(), $config);
  $installUrl = $walletApi->getPassInstallUrl($passId, $contactId);
  // Example URL: https://your-app.com/wallet/install?token=...
  

4. Laravel-Specific: Service Provider Update

Update AppServiceProvider to include new APIs:

public function register()
{
    $this->app->singleton('brevo.contacts', function ($app) {
        $config = Brevo\Client\Configuration::getDefaultConfiguration()
            ->setApiKey('api-key', config('services.brevo.api_key'));
        return new Brevo\Client\Api\ContactsApi(new GuzzleHttp\Client(), $config);
    });

    $this->app->singleton('brevo.consent-groups', function ($app) {
        $config = Brevo\Client\Configuration::getDefaultConfiguration()
            ->setApiKey('api-key', config('services.brevo.api_key'));
        return new Brevo\Client\Api\ConsentGroupsApi(new GuzzleHttp\Client(), $config);
    });

    $this->app->singleton('brevo.wallet', function ($app) {
        $config = Brevo\Client\Configuration::getDefaultConfiguration()
            ->setApiKey('api-key', config('services.brevo.api_key'));
        return new Brevo\Client\Api\WalletApi(new GuzzleHttp\Client(), $config);
    });
}

5. Facade for New APIs

Extend BrevoFacade to support new methods:

class BrevoFacade extends Facade
{
    protected static function getFacadeAccessor() { return 'brevo'; }

    public static function consentGroups()
    {
        return app('brevo.consent-groups');
    }

    public static function wallet()
    {
        return app('brevo.wallet');
    }
}

Usage:

Brevo::consentGroups()->getConsentGroups();
Brevo::wallet()->getPassInstallUrl($passId, $contactId);

Gotchas and Tips

Pitfalls

1. Empty Object Serialization (Fixed in v5.0.1)

   • Issue: Previous versions could fail when sending empty optional objects (e.g., {} vs []).
   • Fix: Now correctly serializes empty objects to {} (e.g., {"attributes": {}}).

2. Consent Groups vs. Lists

   • Issue: Confusing consentGroups (new) with lists (existing). They serve different purposes:
     • Lists: For email segmentation.
     • Consent Groups: For GDPR/CCPA compliance tracking.
   • Fix: Use both where applicable (e.g., assign contacts to a list and a consent group).

3. Wallet Feature Limitations

   • Issue: Wallet integration requires:
     • Apple Wallet/Google Wallet setup in Brevo dashboard.
     • Contact must have a valid contactId (not just email).
   • Fix: Verify setup in Brevo dashboard before using WalletApi.

4. Consent Group Signup Modes

   • Issue: signupMode must be set to SINGLE_OPTIN or DOUBLE_OPTIN. Defaults may vary.
   • Fix: Explicitly define signupMode when creating groups:

     $group = new \Brevo\Client\Model\ConsentGroup([
         'name' => 'Newsletter',
         'signupMode' => 'DOUBLE_OPTIN' // Required
     ]);
     

5. Import Contacts with Consent Groups

   • Issue: consentGroupIds in importContacts is optional but requires:
     • Pre-existing consent groups.
     • Valid contactId or email for assignment.
   • Fix: Validate group IDs exist before importing:

     $groups = Brevo::consentGroups()->getConsentGroups();
     $validGroupIds = array_column($groups->getData(), 'id');
     if (!in_array($groupId, $validGroupIds)) {
         throw new \InvalidArgumentException("Invalid consent group ID");
     }
     

6. Deprecation Warning

   • Issue: While v5.x is backward compatible, plan to migrate to v6 when released (check Brevo’s roadmap).
   • Fix: Monitor release notes and test new versions in staging.

Debugging Tips

1. Consent Group Validation Errors

   • Symptom: 400 Bad Request when creating/updating consent groups.
   • Debug:
     • Ensure name is provided (required field).
     • Validate signupMode is SINGLE_OPTIN or DOUBLE_OPTIN.
     • Check for duplicate name if using PUT to update.

2. Wallet URL Generation Failures

   • Symptom: 404 Not Found for getPassInstallUrl.
   • Debug:
     • Verify passId exists in Brevo’s Wallet section.