Freshdesk Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require fabatek/freshdesk-laravel
   

   Publish the config file:

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

2. Configure .env Add Freshdesk credentials:

   FRESHDESK_DOMAIN=yourdomain.freshdesk.com
   FRESHDESK_API_KEY=your_api_key_here
   

3. First Use Case: Fetching Tickets Inject the Fabatek\Freshdesk\Contracts\Freshdesk facade into a controller or service:

   use Fabatek\Freshdesk\Facades\Freshdesk;
   
   public function getTickets()
   {
       $tickets = Freshdesk::tickets()->list();
       return response()->json($tickets);
   }
   

Implementation Patterns

Common Workflows

1. Ticket Management

   • Create a Ticket:

     Freshdesk::tickets()->create([
         'subject' => 'New Issue',
         'description' => 'Details here...',
         'priority' => 2,
     ]);
     

   • Update a Ticket:

     Freshdesk::tickets()->update(123, ['status' => 2]);
     

   • Fetch Ticket by ID:

     $ticket = Freshdesk::tickets()->show(123);
     

2. Contacts & Organizations

   • List Contacts:

     $contacts = Freshdesk::contacts()->list();
     

   • Create Contact:

     Freshdesk::contacts()->create(['name' => 'John Doe', 'email' => 'john@example.com']);
     

3. Responses & Comments

   • Add Comment to Ticket:

     Freshdesk::tickets()->comments()->create(123, ['comment' => 'Reply here...']);
     

4. Searching

   • Search Tickets:

     $results = Freshdesk::tickets()->search('subject:"urgent"');
     

Integration Tips

• Laravel Events: Trigger Freshdesk actions on Laravel events (e.g., user.created):

  event(new UserRegistered($user));
  // In a listener:
  Freshdesk::contacts()->create($user->toFreshdeskArray());
  

• API Rate Limiting: Use Laravel’s throttle middleware if hitting Freshdesk’s API limits.
• Queue Jobs: Offload Freshdesk API calls to queues for async processing:

  dispatch(new SyncFreshdeskTicketsJob());
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never hardcode FRESHDESK_API_KEY in config files. Use Laravel’s .env and restrict file permissions.
   • Validate the key in config/freshdesk.php:

     'api_key' => env('FRESHDESK_API_KEY', false),
     

     Then add a check in a service provider:

     if (empty(config('freshdesk.api_key'))) {
         throw new \RuntimeException('Freshdesk API key not configured.');
     }
     

2. Rate Limits

   • Freshdesk enforces rate limits. Cache responses aggressively:

     $tickets = Cache::remember('freshdesk_tickets', now()->addMinutes(5), function () {
         return Freshdesk::tickets()->list();
     });
     

3. Pagination

   • The package doesn’t auto-paginate. Handle pagination manually:

     $page = 1;
     $perPage = 20;
     $tickets = Freshdesk::tickets()->list(['page' => $page, 'per_page' => $perPage]);
     

4. Error Handling

   • Wrap API calls in try-catch blocks:

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

Debugging Tips

• Enable Debug Mode: Set FRESHDESK_DEBUG=true in .env to log API requests/responses.
• Inspect Raw Responses: Use the underlying Guzzle client for debugging:

  $client = Freshdesk::getClient();
  $response = $client->request('GET', '/api/v2/tickets');
  

Extension Points

1. Custom Endpoints Extend the package by adding new methods to the Freshdesk facade:

   // In a service provider:
   Freshdesk::extend('custom', function ($app) {
       return new CustomFreshdeskService();
   });
   

   Then use:

   Freshdesk::custom()->someMethod();
   

2. Override API Client Bind a custom HTTP client in the service provider:

   $this->app->singleton(\Fabatek\Freshdesk\Contracts\FreshdeskClient::class, function ($app) {
       return new CustomGuzzleClient();
   });
   

3. Webhooks Use Laravel’s route:webhook to handle Freshdesk webhook payloads:

   Route::post('/freshdesk/webhook', function (Request $request) {
       $payload = $request->json()->all();
       // Process webhook (e.g., update local DB)
   });