Freshdesk Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require keepcloud/freshdesk-laravel
   

2. Register Provider & Facade: Add to config/app.php:

   'providers' => [
       Keepcloud\Laravel\Freshdesk\FreshdeskServiceProvider::class,
   ],
   'aliases' => [
       'Freshdesk' => Keepcloud\Laravel\Freshdesk\FreshdeskFacade::class,
   ]
   

3. Publish Config:

   php artisan vendor:publish --provider="Keepcloud\Laravel\Freshdesk\FreshdeskServiceProvider"
   

   Update config/freshdesk.php with your API key and domain.

First Use Case: Fetching a Ticket

use Freshdesk;

$ticket = Freshdesk::ticket()->find(123);
return response()->json($ticket);

Implementation Patterns

Common Workflows

1. CRUD Operations:

   // Create
   $ticket = Freshdesk::ticket()->create(['subject' => 'Test', 'description' => 'Hello']);
   
   // Update
   Freshdesk::ticket()->update(123, ['status' => 2]);
   
   // Delete
   Freshdesk::ticket()->delete(123);
   

2. Querying with Filters:

   $tickets = Freshdesk::ticket()->all(['query' => 'status:open']);
   

3. Attachments:

   $attachment = Freshdesk::attachment()->create(123, 'path/to/file.pdf');
   

4. Contacts & Groups:

   $contact = Freshdesk::contact()->find(456);
   $group = Freshdesk::group()->find(789);
   

Integration Tips

• Event Listeners: Use Laravel’s event system to trigger actions on Freshdesk webhooks (e.g., ticket.created).
• Jobs: Offload API calls to queues for long-running operations:

  dispatch(new SyncTicketsJob());
  

• API Rate Limiting: Cache responses aggressively (e.g., Cache::remember()) to avoid hitting Freshdesk’s limits.

Gotchas and Tips

Pitfalls

1. API Key Permissions:

   • Ensure your API key has the correct permissions (e.g., Tickets:Read, Tickets:Write). Test with a restricted key first.
   • Debug: Check Freshdesk’s API logs for 403 Forbidden errors.

2. Domain Configuration:

   • The domain in config/freshdesk.php must match your Freshdesk subdomain (e.g., yourcompany.freshdesk.com → yourcompany).
   • Debug: Use Freshdesk::getClient()->getBaseUri() to verify the constructed URL.

3. Pagination:

   • The SDK may not handle pagination automatically. Use ->all() with ['page' => 1, 'per_page' => 50] for large datasets.
   • Tip: Implement recursive pagination in a helper:

     function getAllTickets() {
         $tickets = [];
         $page = 1;
         do {
             $tickets = array_merge($tickets, Freshdesk::ticket()->all(['page' => $page, 'per_page' => 50]));
             $page++;
         } while (count($tickets) >= $page * 50);
         return $tickets;
     }
     

4. Error Handling:

   • Wrap API calls in try-catch blocks to handle Keepcloud\Freshdesk\Exceptions\FreshdeskException:

     try {
         Freshdesk::ticket()->find(123);
     } catch (\Exception $e) {
         Log::error('Freshdesk error: ' . $e->getMessage());
         return response()->json(['error' => 'Failed to fetch ticket'], 500);
     }
     

Tips

1. Environment Variables:

   • Store api_key and domain in .env:

     FRESHDESK_API_KEY=your_key
     FRESHDESK_DOMAIN=yourdomain
     

   • Update config/freshdesk.php to use them:

     'api_key' => env('FRESHDESK_API_KEY'),
     'domain' => env('FRESHDESK_DOMAIN'),
     

2. Testing:

   • Use Laravel’s Mockery to stub the Freshdesk client in tests:

     $mock = Mockery::mock('overload:Keepcloud\Freshdesk\Client');
     $mock->shouldReceive('ticket')->andReturnSelf();
     $mock->shouldReceive('find')->andReturn(['id' => 123, 'subject' => 'Test']);
     

3. Extending the SDK:

   • Create a custom facade or service class to wrap repetitive calls:

     class FreshdeskService {
         public function createTicketFromForm(Request $request) {
             return Freshdesk::ticket()->create([
                 'subject' => $request->subject,
                 'description' => $request->description,
                 'priority' => $request->priority ?? 2,
             ]);
         }
     }
     

4. Webhooks:

   • Validate webhook signatures using Freshdesk’s X-Freshworks-Signature header:

     $signature = request()->header('X-Freshworks-Signature');
     $payload = request()->getContent();
     if (!hash_equals($signature, hash_hmac('sha256', $payload, config('freshdesk.webhook_secret')))) {
         abort(401);
     }