Freshdesk Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mohamed-fathy/freshdesk-laravel
   

   Publish the config file:

   php artisan vendor:publish --provider="MohamedFathy\FreshdeskLaravel\FreshdeskServiceProvider"
   

2. Configuration Edit .env with Freshdesk credentials:

   FRESHDESK_DOMAIN=yourdomain.freshdesk.com
   FRESHDESK_API_KEY=your_api_key_here
   FRESHDESK_API_VERSION=v2
   

3. First Use Case Fetch a ticket by ID in a controller:

   use MohamedFathy\FreshdeskLaravel\Facades\Freshdesk;
   
   public function showTicket($id) {
       $ticket = Freshdesk::ticket()->show($id);
       return response()->json($ticket);
   }
   

Implementation Patterns

Core Workflows

1. Ticket Management

   • Create: Freshdesk::ticket()->create(['subject' => 'Test', 'description' => 'Hello']).
   • Update: Freshdesk::ticket()->update($id, ['status' => 2]).
   • List: Freshdesk::ticket()->list(['page' => 1, 'per_page' => 20]).

2. Contact Integration

   • Fetch contacts: Freshdesk::contact()->list().
   • Create/update contacts before ticket creation to link them.

3. Response Handling Wrap API calls in try-catch for error handling:

   try {
       $response = Freshdesk::ticket()->show($id);
   } catch (\MohamedFathy\FreshdeskLaravel\Exceptions\FreshdeskException $e) {
       return response()->json(['error' => $e->getMessage()], 400);
   }
   

Integration Tips

• Laravel Events: Trigger events on ticket updates (e.g., ticket.updated) via observers.
• Queues: Offload API calls to queues for long-running operations:

  dispatch(new FreshdeskTicketSyncJob($ticketId));
  

• Caching: Cache frequent API responses (e.g., contacts list) with Laravel’s cache:

  $contacts = Cache::remember('freshdesk_contacts', now()->addHours(1), function () {
      return Freshdesk::contact()->list();
  });
  

Gotchas and Tips

Pitfalls

1. Deprecated API Version

   • The package uses Freshdesk API v2, which is outdated. Monitor for breaking changes if Freshdesk sunsets v2.
   • Workaround: Fork the package and update the base URL to https://{domain}.freshdesk.com/api/v2/.

2. Rate Limiting

   • Freshdesk enforces rate limits (e.g., 60 requests/minute). Implement exponential backoff:

   use Symfony\Component\HttpClient\RetryableHttpClient;
   use Symfony\Component\HttpClient\RetryableHttpClientInterface;
   
   $client = new RetryableHttpClient(
       new RetryableHttpClientInterface(),
       [
           'max_retries' => 3,
           'delay' => 1000,
           'multiplier' => 2,
           'statuses' => [429],
       ]
   );
   

3. Missing Facade Methods

   • Not all Freshdesk v2 endpoints are exposed. Extend the facade:

   // app/Providers/FreshdeskServiceProvider.php
   Freshdesk::extend('custom_endpoint', function ($app) {
       return new CustomEndpoint($app['freshdesk.http_client']);
   });
   

Debugging

• Enable Logging Add to config/freshdesk.php:

  'debug' => env('FRESHDESK_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• Raw Responses Access raw responses for debugging:

  $response = Freshdesk::ticket()->show($id);
  \Log::debug($response->originalResponse->getContent());
  

Extension Points

1. Custom HTTP Client Bind a custom Guzzle client in AppServiceProvider:

   $this->app->bind('freshdesk.http_client', function () {
       return new \GuzzleHttp\Client([
           'timeout' => 30,
           'headers' => ['User-Agent' => 'MyApp/1.0'],
       ]);
   });
   

2. Response Transformers Override response handling in app/Providers/FreshdeskServiceProvider.php:

   Freshdesk::macro('transformResponse', function ($response) {
       return json_decode($response->getBody(), true);
   });
   

3. Webhooks Use Laravel’s HasApiTokens for webhook verification:

   public function handleWebhook(Request $request) {
       $payload = $request->json()->all();
       $signature = $request->header('X-Freshdesk-Signature');
   
       if (!hash_equals(
           hash_hmac('sha256', $request->getContent(), config('freshdesk.webhook_secret')),
           $signature
       )) {
           abort(401);
       }
       // Process payload
   }