Crm Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require banckle/crm-sdk-php banckle/crm-bundle
   

   Update AppKernel.php to register the bundle:

   new Banckle\Bundle\CRMBundle\BanckleCRMBundle(),
   

2. Configuration: Add to config.yml:

   banckle_crm:
       apiKey: "%env(BANCKLE_API_KEY)%"  # Use env vars for security
       banckleAccountUri: "https://apps.banckle.com/api/v2"
       banckleCRMUri: "https://crm.banckle.com/api/v1.0"
   

3. First Use Case: Fetch a token and list contacts in a controller:

   use Symfony\Component\DependencyInjection\ContainerInterface;
   
   class ContactController extends Controller
   {
       public function index(ContainerInterface $container)
       {
           $banckleCRM = $container->get('bancklecrm.api');
           $token = $banckleCRM->getToken('user@example.com', 'password');
           $contacts = $banckleCRM->createInstance('ContactsApi', $token)->getContacts();
           return $this->render('contact/index.html.twig', ['contacts' => $contacts]);
       }
   }
   

Implementation Patterns

Dependency Injection

• Service Injection: Prefer injecting bancklecrm.api via constructor or setter:

  public function __construct(private BanckleCRMService $banckleCRM) {}
  

• Token Management: Cache tokens (e.g., using Symfony’s cache component) to avoid repeated authentication:

  $token = $this->banckleCRM->getToken($email, $password);
  $this->cache->set('banckle_token', $token, 3600); // Cache for 1 hour
  

API Workflows

1. CRUD Operations:

   // Create
   $contactApi = $this->banckleCRM->createInstance('ContactsApi', $token);
   $contact = $contactApi->createContact(['firstName' => 'John']);
   
   // Read
   $contacts = $contactApi->getContacts(['limit' => 10]);
   
   // Update
   $contactApi->updateContact($contact->id, ['lastName' => 'Doe']);
   
   // Delete
   $contactApi->deleteContact($contact->id);
   

2. Pagination: Handle paginated responses with limit and offset:

   $contacts = $contactApi->getContacts(['limit' => 50, 'offset' => 0]);
   while ($contacts->data) {
       // Process data
       $contacts = $contactApi->getContacts(['limit' => 50, 'offset' => $contacts->offset + 50]);
   }
   

3. Error Handling: Wrap API calls in try-catch blocks:

   try {
       $result = $contactApi->getContacts();
   } catch (\Banckle\CRM\Exception\ApiException $e) {
       $this->addFlash('error', $e->getMessage());
       return $this->redirectToRoute('home');
   }
   

Integration Tips

• Symfony Forms: Bind CRM data to forms for user input:

  $builder->add('firstName', TextType::class, [
      'data' => $contact->firstName ?? null,
  ]);
  

• Event Listeners: Trigger actions on CRM events (e.g., new contact):

  // src/EventListener/BanckleCRMListener.php
  public function onContactCreated(ContactEvent $event) {
      $this->mailer->sendEmail('admin@example.com', 'New Contact', $event->getContact());
  }
  

• Doctrine Entities: Sync CRM data with Doctrine models:

  // Sync contacts to database
  foreach ($contacts->data as $contact) {
      $entityManager->persist(new ContactEntity($contact));
  }
  $entityManager->flush();
  

Gotchas and Tips

Pitfalls

1. Token Expiry:

   • Tokens expire after 1 hour. Implement a refresh mechanism or cache with short TTL.
   • Fix: Use getToken() dynamically or store tokens with expiry checks.

2. API Rate Limits:

   • Banckle’s API may throttle requests. Implement exponential backoff:

   $attempts = 0;
   while ($attempts < 3) {
       try {
           $result = $contactApi->getContacts();
           break;
       } catch (\Banckle\CRM\Exception\RateLimitException $e) {
           sleep(2 ** $attempts);
           $attempts++;
       }
   }
   

3. Configuration Overrides:

   • Avoid hardcoding apiKey in config.yml. Use environment variables or parameter bags:

   # config/packages/banckle_crm.yaml
   banckle_crm:
       apiKey: "%env(BANCKLE_API_KEY)%"
   

4. Deprecated Methods:

   • The SDK may change. Check the Banckle CRM SDK docs for updates.

Debugging

• Enable Debug Mode: Set debug: true in config.yml to log API requests/responses:

  banckle_crm:
      debug: true
  

• Logging: Use Symfony’s logger to track API calls:

  $this->logger->info('Banckle CRM Request', ['url' => $requestUrl, 'data' => $data]);
  

Extension Points

1. Custom API Clients: Extend the bundle to add domain-specific methods:

   // src/Service/CustomBanckleCRM.php
   class CustomBanckleCRM extends BanckleCRMService
   {
       public function getActiveContacts()
       {
           $contacts = $this->createInstance('ContactsApi', $this->token)->getContacts(['status' => 'active']);
           return array_filter($contacts->data, fn($c) => $c->status === 'active');
       }
   }
   

   Register as a service in services.yaml:

   services:
       App\Service\CustomBanckleCRM:
           arguments:
               $apiKey: "%banckle_crm.apiKey%"
               $accountUri: "%banckle_crm.banckleAccountUri%"
               $crmUri: "%banckle_crm.banckleCRMUri%"
   

2. Event Dispatching: Dispatch Symfony events for CRM actions:

   // After creating a contact
   $this->eventDispatcher->dispatch(new ContactCreatedEvent($contact));
   

3. Testing: Mock the BanckleCRMService in tests:

   $mockCRM = $this->createMock(BanckleCRMService::class);
   $mockCRM->method('getToken')->willReturn('mock_token');
   $mockCRM->method('createInstance')->willReturn($mockContactsApi);
   $this->container->set('bancklecrm.api', $mockCRM);
   

Performance Tips

• Batch Processing: Use bulk operations where possible (e.g., createContacts instead of individual createContact calls).
• Async Processing: Offload CRM operations to a queue (e.g., Symfony Messenger) for long-running tasks:

  $this->messageBus->dispatch(new SyncContactsMessage($token));