Insightlytaskbundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require cekurte/insightlytaskbundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Cekurte\InsightlyTaskBundle\CekurteInsightlyTaskBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console insightly:install
   

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

   cekurte_insightly_task:
       api_key: '%env(INSIGHTLY_API_KEY)%'
       api_secret: '%env(INSIGHTLY_API_SECRET)%'
       base_url: 'https://api.insight.ly/v3.1'
   

3. First Use Case Fetch a task by ID:

   use Cekurte\InsightlyTaskBundle\Service\TaskService;
   
   $taskService = $this->container->get('cekurte_insightly_task.task_service');
   $task = $taskService->getTask(123);
   

Implementation Patterns

Common Workflows

1. Task CRUD Operations

   • Create: Use createTask() with an array of task data.

     $taskData = [
         'name' => 'Follow up with client',
         'due_date' => '2023-12-31',
         'status' => 'Open',
     ];
     $task = $taskService->createTask($taskData);
     

   • Update: Pass the task ID and updated data to updateTask().

     $taskService->updateTask(123, ['status' => 'Closed']);
     

   • Delete: Use deleteTask() with the task ID.

     $taskService->deleteTask(123);
     

2. Querying Tasks

   • Filter tasks with getTasks():

     $tasks = $taskService->getTasks([
         'filter' => ['status' => 'Open'],
         'limit' => 10,
     ]);
     

3. Event Integration

   • Listen for task events (e.g., task.created) via Symfony’s event dispatcher:

     # config/services.yaml
     services:
         App\EventListener\InsightlyTaskListener:
             tags:
                 - { name: kernel.event_listener, event: task.created, method: onTaskCreated }
     

4. Dependency Injection

   • Inject TaskService into controllers/services:

     public function __construct(private TaskService $taskService) {}
     

Integration Tips

• API Rate Limiting: Cache responses aggressively (e.g., using Symfony’s cache component) to avoid hitting Insightly’s rate limits.
• Error Handling: Wrap API calls in try-catch blocks to handle InsightlyApiException:

  try {
      $task = $taskService->getTask(123);
  } catch (InsightlyApiException $e) {
      $this->addFlash('error', $e->getMessage());
  }
  

• Testing: Use the InsightlyTaskBundleTest trait in your PHPUnit tests to mock API responses:

  use Cekurte\InsightlyTaskBundle\Tests\InsightlyTaskBundleTest;
  
  class MyTest extends TestCase {
      use InsightlyTaskBundleTest;
  
      public function testTaskCreation() {
          $this->mockApiResponse('tasks', ['id' => 123]);
          $task = $this->taskService->createTask(['name' => 'Test']);
          $this->assertEquals(123, $task['id']);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Authentication Issues

   • Symptom: 401 Unauthorized errors.
   • Fix: Verify api_key and api_secret in config/packages/cekurte_insightly_task.yaml. Ensure they match Insightly’s API credentials.
   • Debug: Enable debug mode (APP_DEBUG=true) to log raw API responses.

2. Deprecated API Endpoints

   • The bundle assumes v3.1 of Insightly’s API. If Insightly updates their API, the bundle may break. Check the Insightly API changelog for compatibility.

3. Missing Dependencies

   • The bundle requires guzzlehttp/guzzle (v6.x). If your project uses v7.x, conflicts may arise. Pin the version in composer.json:

     "guzzlehttp/guzzle": "^6.5"
     

4. Pagination Quirks

   • The getTasks() method may not handle pagination automatically. For large datasets, manually paginate using offset and limit:

     $tasks = $taskService->getTasks(['limit' => 50, 'offset' => 0]);
     

Debugging Tips

• Enable API Logging Add this to config/packages/cekurte_insightly_task.yaml:

  cekurte_insightly_task:
      debug: true
  

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

• Insightly API Explorer Use Insightly’s API Explorer to test endpoints manually before integrating them into your code.

Extension Points

1. Custom Fields

   • Extend the Task entity by overriding the TaskService:

     class CustomTaskService extends TaskService {
         public function getCustomTasks(array $filters) {
             $tasks = $this->getTasks($filters);
             return array_map([$this, 'addCustomField'], $tasks);
         }
     
         private function addCustomField(array $task) {
             $task['custom_field'] = $this->fetchCustomField($task['id']);
             return $task;
         }
     }
     

   • Register the service in config/services.yaml:

     services:
         App\Service\CustomTaskService:
             decorates: 'cekurte_insightly_task.task_service'
             arguments: ['@.inner']
     

2. Webhook Integration

   • Listen for Insightly webhook events (e.g., task updates) by extending the WebhookListener:

     class CustomWebhookListener extends WebhookListener {
         public function onWebhookReceived(array $payload) {
             if ($payload['event'] === 'task.updated') {
                 $this->handleTaskUpdate($payload['data']);
             }
         }
     }
     

   • Register the listener in config/services.yaml:

     services:
         App\EventListener\CustomWebhookListener:
             tags:
                 - { name: kernel.event_listener, event: insightly.webhook, method: onWebhookReceived }
     

3. Batch Operations

   • For bulk operations (e.g., updating 100+ tasks), use Insightly’s batch API by extending the TaskService:

     public function batchUpdateTasks(array $taskIds, array $updates) {
         $batch = [];
         foreach ($taskIds as $id) {
             $batch[] = ['id' => $id, 'data' => $updates];
         }
         return $this->client->request('POST', '/Tasks/batch', [
             'json' => ['batch' => $batch],
         ]);
     }