Freshdesk Php Sdk Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require keepcloud/freshdesk-php-sdk
   

   (Note: Use a stable version instead of dev-master in production.)

2. Initialize the API:

   use Freshdesk\Api;
   
   $api = new Api(config('services.freshdesk.api_key'), config('services.freshdesk.domain'));
   

   (Store credentials in .env for security.)

3. First Use Case: Fetch all tickets with pagination:

   $tickets = $api->tickets->all(['page' => 1, 'per_page' => 20]);
   

Where to Look First

• API Overview Docs – Lists all endpoints (e.g., tickets, contacts, groups).
• Laravel Integration – Use keepcloud/freshdesk-laravel for service providers, facades, and caching.

Implementation Patterns

Core Workflows

1. CRUD Operations:

   // Create
   $ticket = $api->tickets->create(['subject' => 'Test', 'description' => 'Hello']);
   
   // Read
   $ticket = $api->tickets->view($ticket['id']);
   
   // Update
   $updated = $api->tickets->update($ticket['id'], ['status' => 2]);
   
   // Delete
   $api->tickets->delete($ticket['id']);
   

2. Pagination & Filtering:

   // Paginated results
   $tickets = $api->tickets->all(['page' => 2, 'per_page' => 50]);
   
   // Filter by status (e.g., 'open')
   $tickets = $api->tickets->all(['query' => 'status:open']);
   

3. Attachments & Related Data:

   // Upload attachment
   $attachment = $api->attachments->create($ticket['id'], '/path/to/file.pdf');
   
   // Fetch replies
   $replies = $api->tickets->replies->all($ticket['id']);
   

Laravel-Specific Patterns

• Service Provider Binding:

  // config/services.php
  'freshdesk' => [
      'api_key' => env('FRESHDESK_API_KEY'),
      'domain' => env('FRESHDESK_DOMAIN'),
  ];
  
  // AppServiceProvider.php
  $this->app->singleton(Api::class, function ($app) {
      return new Api(
          $app['config']['services.freshdesk.api_key'],
          $app['config']['services.freshdesk.domain']
      );
  });
  

• Facade Usage (if using the Laravel package):

  use Freshdesk\Facades\Freshdesk;
  
  $tickets = Freshdesk::tickets()->all();
  

• Caching Responses:

  // Cache for 10 minutes
  $tickets = Cache::remember('freshdesk_tickets', 600, function () {
      return $api->tickets->all();
  });
  

• Queueing Long-Running Tasks:

  // Dispatch a job to update tickets asynchronously
  UpdateTicketsJob::dispatch($api, $ticketIds)->onQueue('freshdesk');
  

Error Handling

Wrap API calls in a try-catch to handle HTTP errors:

try {
    $ticket = $api->tickets->view($id);
} catch (\Freshdesk\Exception\ApiException $e) {
    Log::error('Freshdesk API Error: ' . $e->getMessage());
    return response()->json(['error' => 'Failed to fetch ticket'], 500);
}

Gotchas and Tips

Pitfalls

1. API Key & Domain Sensitivity:

   • Hardcoding credentials violates security best practices. Always use .env:

     FRESHDESK_API_KEY=your_key_here
     FRESHDESK_DOMAIN=yourdomain.freshdesk.com
     

   • Gotcha: The domain must include the subdomain (e.g., yourdomain.freshdesk.com, not just yourdomain).

2. Rate Limiting:

   • Freshdesk enforces rate limits. Cache responses aggressively or implement exponential backoff:

     $retryAfter = $e->getRetryAfter();
     sleep($retryAfter);
     

3. Pagination Quirks:

   • per_page max is 250 (Freshdesk’s API limit). Avoid fetching large datasets without pagination.
   • Gotcha: The SDK doesn’t auto-paginate; manually loop through pages if needed:

     $allTickets = [];
     $page = 1;
     do {
         $tickets = $api->tickets->all(['page' => $page, 'per_page' => 100]);
         $allTickets = array_merge($allTickets, $tickets);
         $page++;
     } while (!empty($tickets));
     

4. Data Validation:

   • Freshdesk’s API rejects malformed requests. Validate data before sending:

     $validator = Validator::make($data, [
         'subject' => 'required|string|max:255',
         'description' => 'required|string',
     ]);
     

5. Time Zones:

   • Freshdesk uses UTC for timestamps. Convert to local time if needed:

     $createdAt = Carbon::parse($ticket['created_time'])->tz('America/New_York');
     

Debugging Tips

1. Enable Debugging: Add this to your Api initialization to log requests/responses:

   $api = new Api($key, $domain, [
       'debug' => true,
       'logger' => function ($message) {
           Log::debug($message);
       }
   ]);
   

2. Common HTTP Errors:

   • 401 Unauthorized: Invalid API key or domain.
   • 404 Not Found: Resource doesn’t exist (e.g., ticket ID mismatch).
   • 429 Too Many Requests: Hit rate limits. Check Retry-After header.

3. Testing:

   • Use Freshdesk’s Sandbox for testing.
   • Mock the SDK in PHPUnit:

     $mockApi = Mockery::mock(Api::class);
     $mockApi->shouldReceive('tickets->view')->andReturn(['id' => 123]);
     

Extension Points

1. Custom Endpoints: The SDK is thin; extend it for unsupported endpoints:

   $response = $api->request('GET', '/api/v2/contacts/{id}/tickets', ['id' => 123]);
   

2. Middleware: Add request/response middleware:

   $api->setMiddleware(function ($request) {
       $request->headers['X-Custom-Header'] = 'value';
   });
   

3. Event Dispatching: Trigger Laravel events after API calls:

   $api->tickets->create($data);
   event(new TicketCreated($ticket));
   

4. Webhooks: Use the SDK to verify Freshdesk webhook signatures:

   $signature = hash_hmac('sha256', $payload, config('services.freshdesk.webhook_secret'));
   if ($signature !== $_SERVER['HTTP_X_FRESHDESK_SIGNATURE']) {
       abort(403);
   }