Freshdesk Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require hasfoug/freshdesk-laravel
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Hasfoug\Freshdesk\FreshdeskServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Hasfoug\Freshdesk\FreshdeskServiceProvider" --tag="freshdesk-config"
   

   Update .env with your Freshdesk credentials:

   FRESHDESK_DOMAIN=yourdomain.freshdesk.com
   FRESHDESK_API_KEY=your_api_key_here
   

3. First Use Case Inject the Freshdesk facade into a controller or service:

   use Hasfoug\Freshdesk\Facades\Freshdesk;
   
   public function createTicket()
   {
       $ticket = Freshdesk::ticket()->create([
           'subject' => 'Test Ticket',
           'description' => 'This is a test ticket created via Laravel.',
           'priority' => 2,
       ]);
       return response()->json($ticket);
   }
   

Implementation Patterns

Common Workflows

1. Ticket Management

   • Create a Ticket:

     Freshdesk::ticket()->create($ticketData);
     

   • List Tickets:

     Freshdesk::ticket()->all(['page' => 1, 'per_page' => 20]);
     

   • Update/Delete:

     Freshdesk::ticket()->update($ticketId, $data);
     Freshdesk::ticket()->delete($ticketId);
     

2. Contact Management

   • Create/Update Contacts:

     Freshdesk::contact()->create($contactData);
     Freshdesk::contact()->update($contactId, $data);
     

   • Fetch Contacts:

     Freshdesk::contact()->all(['email' => 'user@example.com']);
     

3. Integration with Laravel Events Use Laravel's event system to trigger Freshdesk actions:

   // In an event listener
   event(new TicketCreated($ticket));
   

   // In the listener
   public function handle(TicketCreated $event)
   {
       Freshdesk::ticket()->create($event->ticketData);
   }
   

4. API Response Handling Wrap Freshdesk calls in a service layer for consistency:

   class FreshdeskService
   {
       public function createSupportTicket(array $data)
       {
           try {
               return Freshdesk::ticket()->create($data);
           } catch (\Exception $e) {
               Log::error("Freshdesk API Error: " . $e->getMessage());
               throw new \RuntimeException("Failed to create ticket.");
           }
       }
   }
   

Integration Tips

• Middleware for Authentication Use middleware to validate Freshdesk API responses:

  namespace App\Http\Middleware;
  
  use Closure;
  use Hasfoug\Freshdesk\Exceptions\FreshdeskException;
  
  class HandleFreshdeskErrors
  {
      public function handle($request, Closure $next)
      {
          try {
              return $next($request);
          } catch (FreshdeskException $e) {
              return response()->json(['error' => $e->getMessage()], 500);
          }
      }
  }
  

• Queue Delayed Actions Offload Freshdesk API calls to queues for performance:

  // Dispatch a job
  CreateFreshdeskTicket::dispatch($ticketData);
  
  // Job class
  class CreateFreshdeskTicket implements ShouldQueue
  {
      public function handle()
      {
          Freshdesk::ticket()->create($this->ticketData);
      }
  }
  

Gotchas and Tips

Pitfalls

1. API Rate Limits Freshdesk enforces rate limits (e.g., 60 requests/minute). Cache responses aggressively:

   $tickets = Cache::remember("freshdesk_tickets_{$page}", now()->addMinutes(5), function () use ($page) {
       return Freshdesk::ticket()->all(['page' => $page]);
   });
   

2. Error Handling The package throws Hasfoug\Freshdesk\Exceptions\FreshdeskException. Always catch and log these:

   try {
       Freshdesk::ticket()->create($data);
   } catch (FreshdeskException $e) {
       Log::error('Freshdesk Error: ' . $e->getResponseBody());
   }
   

3. Domain Configuration Ensure FRESHDESK_DOMAIN in .env matches your Freshdesk subdomain exactly (e.g., yourdomain.freshdesk.com, not yourdomain).

4. API Key Permissions The API key must have admin or agent permissions for full functionality. Test with a restricted key first.

Debugging

• Enable Debug Mode Set FRESHDESK_DEBUG=true in .env to log raw API requests/responses:

  FRESHDESK_DEBUG=true
  

• Check Response Headers Use dd() to inspect the full response:

  $response = Freshdesk::ticket()->create($data);
  dd($response->getHeaders());
  

• Common HTTP Errors

  • 401 Unauthorized: Invalid API key or domain.
  • 403 Forbidden: Insufficient permissions.
  • 429 Too Many Requests: Hit rate limits.

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();
   });
   

2. Override API Client Replace the underlying Guzzle client for custom logic:

   $client = new \GuzzleHttp\Client([
       'base_uri' => 'https://' . config('freshdesk.domain'),
       'headers' => [
           'Authorization' => 'Basic ' . base64_encode(config('freshdesk.api_key') . ':X'),
       ],
   ]);
   
   Freshdesk::setClient($client);
   

3. Add Custom Fields Use the custom_fields parameter in requests:

   Freshdesk::ticket()->create([
       'subject' => 'Custom Field Test',
       'custom_fields' => [
           'field_12345' => 'Custom Value',
       ],
   ]);
   

Configuration Quirks

• Default Per-Page Limit The package defaults to 20 tickets/contacts per page. Adjust in .env:

  FRESHDESK_PER_PAGE=50
  

• Timezone Handling Freshdesk uses UTC. Convert timestamps explicitly:

  $createdAt = now()->timezone('UTC')->toDateTimeString();