Pipedrive Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require benhawker/pipedrive
   composer require touiliy/pipedrive-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       YannisTouili\PipeDriveBundle\PipeDriveBundle::class => ['all' => true],
   ];
   

2. Configuration Add credentials to config/packages/pipedrive.yaml:

   pipedrive:
       api_token: '%env(PIPEDRIVE_API_TOKEN)%'
       base_url: 'https://api.pipedrive.com/v1'
   

   Ensure .env contains:

   PIPEDRIVE_API_TOKEN=your_api_token_here
   

3. First Use Case: Fetching Deals Inject the client in a service/controller:

   use YannisTouili\PipeDriveBundle\Service\PipeDriveClient;
   
   public function __construct(private PipeDriveClient $client) {}
   
   public function getDeals() {
       return $this->client->get('deals');
   }
   

Implementation Patterns

Common Workflows

1. CRUD Operations Use the client for standard API calls:

   // Create
   $deal = $this->client->post('deals', ['title' => 'New Deal']);
   
   // Read
   $deal = $this->client->get('deals/123');
   
   // Update
   $this->client->put('deals/123', ['title' => 'Updated Deal']);
   
   // Delete
   $this->client->delete('deals/123');
   

2. Querying with Filters Pass query parameters for filtering:

   $deals = $this->client->get('deals', [
       'start_date' => '2023-01-01',
       'status' => 'won',
   ]);
   

3. Handling Files Upload files via the upload method:

   $filePath = '/path/to/file.pdf';
   $fileData = file_get_contents($filePath);
   $upload = $this->client->upload('files', [
       'file' => new \CuyZ\Valinor\Mapper\Source\UploadedFileSource($fileData, 'file.pdf'),
   ]);
   

4. Webhooks Configure webhooks via the client (if supported):

   $webhook = $this->client->post('webhooks', [
       'url' => 'https://your-app.com/pipedrive/webhook',
       'events' => ['deal.won'],
   ]);
   

Integration Tips

• Dependency Injection: Prefer injecting PipeDriveClient over instantiating it directly.
• Error Handling: Wrap API calls in try-catch blocks to handle PipeDriveException:

  try {
      $this->client->get('deals/nonexistent');
  } catch (\YannisTouili\PipeDriveBundle\Exception\PipeDriveException $e) {
      // Log or handle error
  }
  

• Pagination: Use the get method with start and limit for pagination:

  $deals = $this->client->get('deals', ['start' => 0, 'limit' => 50]);
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle

   • The touiliy/pipedrive-bundle is outdated (Symfony2/3) and lacks maintenance. Prefer using benhawker/pipedrive directly for modern Laravel/Symfony projects.
   • Workaround: Use the underlying benhawker/pipedrive library directly:

     use Benhawker\Pipedrive\Client;
     
     $client = new Client([
         'token' => env('PIPEDRIVE_API_TOKEN'),
         'base_url' => 'https://api.pipedrive.com/v1',
     ]);
     

2. Authentication Issues

   • Ensure the API token has the correct permissions (e.g., read_deals, write_deals).
   • Debug: Check the token via the PipeDrive API docs.

3. Rate Limiting

   • PipeDrive enforces rate limits (e.g., 60 requests/minute). Cache responses aggressively:

     $deals = Cache::remember('pipedrive_deals', now()->addMinutes(5), function () {
         return $this->client->get('deals');
     });
     

4. File Uploads

   • The upload method may require additional headers or file validation. Refer to the PipeDrive API docs for specifics.

Debugging

• Enable Debugging: Set the debug config option to true in pipedrive.yaml:

  pipedrive:
      debug: true
  

  This logs raw API requests/responses to var/log/pipedrive.log.

• Logging: Use Laravel's logging to track API calls:

  \Log::debug('PipeDrive Request', [
      'url' => $this->client->getBaseUrl() . '/deals',
      'data' => $params,
  ]);
  

Extension Points

1. Custom API Endpoints Extend the client by creating a decorator:

   use Benhawker\Pipedrive\Client as BaseClient;
   
   class CustomPipeDriveClient extends BaseClient {
       public function getCustomDeals() {
           return $this->get('deals', ['custom_field' => 'value']);
       }
   }
   

2. Event Listeners Subscribe to PipeDrive webhook events in Laravel:

   // routes/web.php
   Route::post('/pipedrive/webhook', [WebhookController::class, 'handle']);
   
   // app/Http/Controllers/WebhookController.php
   public function handle(Request $request) {
       $payload = $request->json()->all();
       // Process webhook (e.g., deal.won)
   }
   

3. Testing Mock the client in tests:

   $mockClient = Mockery::mock('Benhawker\Pipedrive\Client');
   $mockClient->shouldReceive('get')->andReturn(['data' => []]);
   
   $this->app->instance(PipeDriveClient::class, $mockClient);