Ecircle Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require bigfoot/ecircle-bundle:dev-master
   

   Ensure dev-master is used, as this is the only available version.

2. Configuration Add the required parameters to config/packages/bigfoot_ecircle.yaml (or app/config.yml in older Laravel versions):

   bigfoot_ecircle:
       client:
           wsdl_url: 'http://webservices.ecircle-ag.com/soap/ecm.wsdl'
           request:
               account_1:
                   realm: 'http://your-ecircle-url.com'
                   user: 'your_username'
                   passwd: 'your_password'
   

3. First Use Case Subscribe a member by email:

   use Bigfoot\Bundle\EcircleBundle\Services\BigfootEcircleClient;
   
   $client = $container->get('bigfoot_ecircle.client');
   $client->subscribeMemberByEmail('user@example.com', 123);
   

Implementation Patterns

Usage Patterns

1. Service Integration Inject BigfootEcircleClient into your services via Laravel's container:

   public function __construct(BigfootEcircleClient $ecircleClient) {
       $this->ecircleClient = $ecircleClient;
   }
   

2. Options Classes For complex requests, create dedicated *Options classes (e.g., SubscribeMemberByEmailOptions) in src/Bigfoot/Bundle/EcircleBundle/Options/. Mirror the Ecircle API method parameters exactly.

3. Session Management Ensure session initialization before calling methods:

   if (!$this->ecircleClient->getSessionId()) {
       $this->ecircleClient->connect();
   }
   

4. Error Handling Wrap calls in try-catch blocks to handle SOAP exceptions:

   try {
       $this->ecircleClient->subscribeMemberByEmail($email, $groupId);
   } catch (\Exception $e) {
       Log::error("Ecircle error: " . $e->getMessage());
   }
   

Workflows

1. Member Management Use the bundle to automate member subscriptions, updates, or deletions via Ecircle’s SOAP API.

2. Batch Processing Loop through a collection of emails/groups and process them sequentially:

   foreach ($members as $member) {
       $this->ecircleClient->subscribeMemberByEmail($member->email, $member->groupId);
   }
   

3. Event Triggers Hook into Laravel events (e.g., registered) to sync users with Ecircle:

   public function handle(Registered $event) {
       $this->ecircleClient->subscribeMemberByEmail($event->user->email, 1);
   }
   

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last updated in 2014; verify Ecircle’s API compatibility.
   • No Laravel 8/9 support; may require polyfills or manual adjustments.

2. Session Handling

   • Always check $this->sessionId before calling methods. Uninitialized sessions throw exceptions.

3. WSDL URL Changes

   • If Ecircle updates their WSDL, the bundle may break. Monitor their API docs.

4. Namespace Conflicts

   • The bundle assumes a specific directory structure (Options/, Services/). Customize paths in Resources/config/services.xml if needed.

5. No Built-in Logging

   • Add debug logging for SOAP requests/responses:

     $client->setDebug(true); // If available; otherwise, log manually.
     

Debugging

1. SOAP Errors

   • Enable PHP’s SOAP error handling:

     ini_set('soap.wsdl_cache_enabled', '0');
     

   • Check Laravel logs for SOAP fault details.

2. Configuration Issues

   • Validate realm, user, and passwd in config/packages/bigfoot_ecircle.yaml. Typos here will cause silent failures.

3. Method Parameters

   • Double-check *Options classes match Ecircle’s API exactly (case-sensitive, required fields).

Extension Points

1. Custom Methods Extend BigfootEcircleClient to add unsupported Ecircle methods:

   public function customMethod($param1, $param2) {
       $options = new CustomMethodOptions();
       $options->param1 = $param1;
       // ... map other params ...
       return $this->client->__soapCall('CustomMethod', [$options]);
   }
   

2. Middleware Add middleware to validate Ecircle responses or retry failed requests:

   $client->getKernel()->pushMiddleware(function ($event) {
       if ($event->hasError()) {
           // Retry logic or fallback
       }
   });
   

3. Testing Mock the SOAP client in tests:

   $mock = $this->createMock(\SoapClient::class);
   $client = new BigfootEcircleClient($mock, $config);