Focus Contact Center Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require answear/focus-contact-center-bundle
   

   Ensure your composer.json meets the PHP version (^7.4 || ^8.0) and Guzzle (^6.0|^7.0) requirements.

2. Publish Configuration

   php artisan vendor:publish --provider="Answear\FocusContactCenterBundle\FocusContactCenterBundle" --tag="config"
   

   This generates config/focus_contact_center.php. Configure your API credentials (e.g., client_id, client_secret, base_uri).

3. First Use Case: Fetching a Record Inject the client into a service or controller:

   use Answear\FocusContactCenterBundle\Client\FocusContactCenterClient;
   
   public function __construct(private FocusContactCenterClient $client) {}
   
   public function getRecord(int $id) {
       return $this->client->getRecord($id);
   }
   

   Call it from a route or command:

   Route::get('/record/{id}', [YourController::class, 'getRecord']);
   

Implementation Patterns

Core Workflows

1. CRUD Operations Use the client methods for standard operations:

   // Create
   $record = $this->client->createRecord(['name' => 'John Doe', 'email' => 'john@example.com']);
   
   // Read
   $record = $this->client->getRecord(123);
   
   // Update
   $this->client->updateRecord(123, ['status' => 'completed']);
   
   // Delete
   $this->client->deleteRecord(123);
   

2. Campaign Management Attach records to campaigns (optional campaigns_id):

   $this->client->createRecord([
       'name' => 'Alice',
       'email' => 'alice@example.com',
       'campaigns_id' => 42, // Optional
   ]);
   

3. Upsert Records Use fcc-upsert-record for idempotent updates:

   $this->client->upsertRecord(123, ['phone' => '+48123456789']);
   

4. MiniCRM Integration Leverage the bundle’s MiniCRM support for lightweight contact storage:

   $this->client->createRecord(['name' => 'Bob', 'email' => 'bob@example.com'], ['mini_crm' => true]);
   

Integration Tips

• Service Layer Abstraction Create a dedicated service class to encapsulate Focus API logic:

  class FocusContactCenterService {
      public function __construct(private FocusContactCenterClient $client) {}
  
      public function syncContact(array $data) {
          return $this->client->upsertRecord($data['id'] ?? null, $data);
      }
  }
  

• Event-Driven Workflows Trigger Focus API calls from Laravel events (e.g., user.created):

  use Illuminate\Support\Facades\Event;
  
  Event::listen('user.created', function ($user) {
      app(FocusContactCenterService::class)->syncContact([
          'name' => $user->name,
          'email' => $user->email,
      ]);
  });
  

• Queue Background Jobs Offload API calls to queues for performance:

  use Illuminate\Support\Facades\Queue;
  
  Queue::push(new SyncFocusContact($userData));
  

  class SyncFocusContact implements ShouldQueue {
      public function handle() {
          app(FocusContactCenterService::class)->syncContact($this->data);
      }
  }
  

• Logging and Debugging Enable Guzzle logging via config:

  'logging' => [
      'enabled' => true,
      'file'    => storage_path('logs/focus_api.log'),
  ],
  

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Issue: 401 Unauthorized errors if client_id/client_secret are misconfigured.
   • Fix: Verify .env or config file:

     FOCUS_CONTACT_CENTER_CLIENT_ID=your_id
     FOCUS_CONTACT_CENTER_CLIENT_SECRET=your_secret
     

2. Guzzle Version Conflicts

   • Issue: Guzzle ^6.0 or ^7.0 required; mixing versions may cause errors.
   • Fix: Align dependencies in composer.json:

     "guzzlehttp/guzzle": "^7.0"
     

3. Timeouts

   • Issue: API calls hang if the server is slow.
   • Fix: Configure timeout in config/focus_contact_center.php:

     'timeout' => 30, // seconds
     

4. Reflection Warnings

   • Issue: Deprecation warnings with PHP 8.x due to reflection usage.
   • Fix: Updated in v1.1.2; ensure you’re on the latest version.

5. MiniCRM Limitations

   • Issue: campaigns_id is optional for MiniCRM but required for full CRM records.
   • Fix: Validate input before calling createRecord.

Debugging Tips

• Enable Verbose Logging Add to config/focus_contact_center.php:

  'debug' => env('APP_DEBUG', false),
  

• Inspect Raw Responses Use the getLastResponse() method for debugging:

  $response = $this->client->getRecord(123);
  \Log::debug($this->client->getLastResponse()->getBody());
  

• Handle Rate Limits Implement exponential backoff for 429 Too Many Requests:

  try {
      $this->client->getRecord($id);
  } catch (\GuzzleHttp\Exception\RequestException $e) {
      if ($e->getCode() === 429) {
          sleep(2); // Retry after 2 seconds
          retry();
      }
      throw $e;
  }
  

Extension Points

1. Custom API Endpoints Extend the client via dependency injection:

   $client = new FocusContactCenterClient($config);
   $client->setCustomEndpoint('/custom/path', 'POST');
   

2. Middleware for Requests Add headers or modify requests globally:

   $client->getHandlerStack()->push(
       \GuzzleHttp\Middleware::mapRequest(function ($request) {
           return $request->withHeader('X-Custom-Header', 'value');
       })
   );
   

3. Event Listeners Subscribe to Focus API events (e.g., record.created):

   FocusContactCenterBundle::recordCreated(function ($record) {
       \Log::info("New record created: {$record['id']}");
   });
   

4. Testing Mock the client in tests:

   $mockClient = Mockery::mock(FocusContactCenterClient::class);
   $mockClient->shouldReceive('getRecord')->andReturn(['id' => 123]);
   $this->app->instance(FocusContactCenterClient::class, $mockClient);