Freshdesk Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require zenichanin/freshdesk-laravel
   

2. Publish Configuration

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

   This generates a freshdesk.php config file in config/.

3. Configure .env Add Freshdesk credentials:

   FRESHDESK_DOMAIN=yourdomain.freshdesk.com
   FRESHDESK_API_KEY=your_api_key_here
   

4. Register Service Provider Ensure Zenichanin\Freshdesk\FreshdeskServiceProvider::class is in config/app.php under providers.

5. First Use Case: Create a Ticket

   use Zenichanin\Freshdesk\Facades\Freshdesk;
   
   $ticket = Freshdesk::ticket()->create([
       'subject' => 'Test Ticket',
       'description' => 'This is a test ticket from Laravel.',
       'priority' => 2,
   ]);
   

Implementation Patterns

Common Workflows

1. Ticket Management

• Create a Ticket

  Freshdesk::ticket()->create(['subject' => 'Issue', 'description' => 'Details...']);
  

• Fetch a Ticket

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

• Update a Ticket

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

• List Tickets

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

2. Contact Management

• Create a Contact

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

• Fetch a Contact

  $contact = Freshdesk::contact()->findByEmail('john@example.com');
  

3. Integration with Laravel Jobs/Queues

Use Laravel's queue system to defer Freshdesk operations:

use Zenichanin\Freshdesk\Jobs\CreateTicket;

CreateTicket::dispatch(['subject' => 'Async Ticket', 'description' => 'Processed later...']);

4. Middleware for API Calls

Wrap Freshdesk calls in middleware for logging/retries:

// app/Http/Middleware/FreshdeskLogger.php
public function handle($request, Closure $next) {
    $response = $next($request);
    \Log::info('Freshdesk API Response:', ['status' => $response->status()]);
    return $response;
}

5. Event-Driven Updates

Listen to Laravel events (e.g., order.created) and trigger Freshdesk tickets:

Event::listen('order.created', function ($order) {
    Freshdesk::ticket()->create([
        'subject' => 'New Order #' . $order->id,
        'description' => 'Order details: ' . $order->details,
    ]);
});

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • Freshdesk enforces rate limits (~60 requests/minute). Cache responses aggressively:

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

2. Domain vs. Subdomain

   • Ensure FRESHDESK_DOMAIN matches your Freshdesk instance (e.g., company.freshdesk.com, not freshdesk.com/company).

3. API Key Permissions

   • The API key must have admin or agent permissions. Test with a restricted key first.

4. Error Handling

   • The package throws Zenichanin\Freshdesk\Exceptions\FreshdeskException. Catch and log:

     try {
         Freshdesk::ticket()->create([...]);
     } catch (\Exception $e) {
         \Log::error('Freshdesk Error:', ['message' => $e->getMessage()]);
         abort(500, 'Failed to create ticket.');
     }
     

5. Pagination Quirks

   • all() returns a Collection but may paginate results. Always check ->total() for counts.

Debugging Tips

• Enable API Logging Add to config/freshdesk.php:

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

  Logs requests/responses to storage/logs/freshdesk.log.

• Test with Postman Validate API keys and endpoints manually before integrating:

  GET https://{domain}.freshdesk.com/api/v2/tickets
  Headers: X-Api-Key: {your_key}
  

Extension Points

1. Custom Endpoints Extend the client for unsupported endpoints:

   // app/Services/FreshdeskClient.php
   use Zenichanin\Freshdesk\Client;
   
   class CustomFreshdeskClient extends Client {
       public function customEndpoint($data) {
           return $this->request('POST', '/api/v2/custom_endpoint', $data);
       }
   }
   

2. Override Config Bind the client in AppServiceProvider:

   $this->app->bind('freshdesk.client', function ($app) {
       return new CustomFreshdeskClient(config('freshdesk'));
   });
   

3. Webhook Listeners Use Laravel's HandleIncomingWebhook to process Freshdesk webhooks:

   // routes/web.php
   Route::post('/freshdesk/webhook', [FreshdeskWebhookController::class, 'handle']);