Insightlybundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require cekurte/insightlybundle
   

   Enable the bundle in config/bundles.php:

   Cekurte\InsightlyBundle\CekurteInsightBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php bin/console insightly:install
   

   Update config/packages/cekurte_insightly.yaml with your Insightly API credentials:

   cekurte_insightly:
       api_key: 'your_api_key_here'
       api_secret: 'your_api_secret_here'
       base_url: 'https://api.insightly.com/v3.1'
   

3. First Use Case Fetch a contact by ID:

   use Cekurte\InsightlyBundle\Service\InsightlyService;
   
   class SomeController extends AbstractController
   {
       public function showContact(InsightlyService $insightly)
       {
           $contact = $insightly->getContact(12345);
           return $this->render('contact/show.html.twig', ['contact' => $contact]);
       }
   }
   

Implementation Patterns

Common Workflows

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

   // Create
   $contact = $insightly->createContact(['firstName' => 'John', 'lastName' => 'Doe']);
   // Read
   $contact = $insightly->getContact($id);
   // Update
   $insightly->updateContact($id, ['email' => '[email protected]']);
   // Delete
   $insightly->deleteContact($id);
   

2. Querying with Filters Fetch contacts with custom filters:

   $contacts = $insightly->getContacts([
       'filter' => [
           'firstName' => 'John',
           'email' => '[email protected]'
       ]
   ]);
   

3. Relationships Link entities (e.g., contacts to organizations):

   $insightly->linkContactToOrganization($contactId, $orgId);
   

4. Webhooks Configure webhook subscriptions via CLI:

   php bin/console insightly:webhook:subscribe contact.created
   

Integration Tips

• Symfony Forms Use the InsightlyType form type for API-driven forms:

  $builder->add('contact', InsightlyType::class, [
      'class' => Contact::class,
      'api_service' => $insightly,
  ]);
  

• Event Listeners Sync Insightly data on entity events:

  // src/EventListener/InsightlySyncListener.php
  public function onContactPersist(Contact $contact, InsightlyService $insightly)
  {
      $insightly->createContact($contact->toArray());
  }
  

• Caching Cache API responses for performance:

   # config/packages/cache.yaml
   insightly:
       cache: cache.adapter.redis
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • Insightly enforces rate limits (e.g., 100 requests/minute). Implement exponential backoff:

     try {
         $response = $insightly->getContacts();
     } catch (RateLimitExceededException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

2. Authentication Failures

   • Ensure api_key and api_secret are correct and not hardcoded. Use environment variables:

     # .env
     INSIGHTLY_API_KEY=%env(INSIGHTLY_API_KEY)%
     

3. Data Mapping

   • The bundle assumes Insightly’s default field names. Custom fields require explicit mapping:

     cekurte_insightly:
         custom_fields:
             contact:
                 'custom_field_123' => 'custom_field_name'
     

4. Webhook Delays

   • Webhook processing may lag. Use a queue (e.g., Symfony Messenger) for async handling.

Debugging

• Enable API Logging

  cekurte_insightly:
      debug: true
  

  Logs will appear in var/log/insightly.log.

• Validate Responses Check for Insightly’s errors array in responses:

  if (isset($response['errors'])) {
      throw new \RuntimeException(implode(', ', $response['errors']));
  }
  

Extension Points

1. Custom Services Extend the base service for domain-specific logic:

   class CustomInsightlyService extends InsightlyService
   {
       public function getActiveContacts()
       {
           return $this->getContacts(['filter' => ['status' => 'Active']]);
       }
   }
   

2. Event Dispatching Trigger Symfony events for Insightly actions:

   $dispatcher->dispatch(new InsightlyEvent('contact.created', $contact));
   

3. Custom API Endpoints Add unsupported endpoints via a decorator:

   class CustomInsightlyServiceDecorator implements InsightlyServiceInterface
   {
       public function __construct(private InsightlyService $decorated) {}
   
       public function getCustomEndpoint()
       {
           return $this->decorated->callApi('GET', '/custom/endpoint');
       }
   }
   

4. Testing Mock the service in tests:

   $mock = $this->createMock(InsightlyService::class);
   $mock->method('getContact')->willReturn(['id' => 123, 'name' => 'Test']);