Getting Started

Minimal Setup

Installation

composer require mpclarkson/freshdesk-laravel

Publish the config file:

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

Configuration Edit .env with Freshdesk credentials:

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

First Use Case: Fetching a Ticket

use Freshdesk\Ticket;

$ticket = Ticket::find(123);
dd($ticket->subject); // Outputs ticket subject

Service Provider Ensure the package is registered in config/app.php under providers:
```
Freshdesk\FreshdeskServiceProvider::class,
```

Implementation Patterns

Common Workflows

1. Ticket Management

Create a Ticket

$ticket = Ticket::create([
    'subject' => 'New Issue',
    'description' => 'Problem details...',
    'priority' => 2,
    'requester_id' => 12345,
]);

Update a Ticket

$ticket = Ticket::find(123);
$ticket->update(['status' => 2, 'description' => 'Updated details...']);

Reply to a Ticket

$ticket = Ticket::find(123);
$ticket->reply('This is my response.');

2. Contact Management

Fetch a Contact

$contact = Contact::find(67890);
dd($contact->name);

Create a Contact

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

3. Searching Tickets

Search with Query Builder

$tickets = Ticket::where('subject', 'like', '%urgent%')
                 ->where('status', 1)
                 ->get();

4. Webhooks (Lumen/Laravel)

Register a Webhook Endpoint

// In routes/web.php or routes/api.php
Route::post('/freshdesk/webhook', 'WebhookController@handle');

// In WebhookController.php
public function handle(Request $request) {
    $payload = $request->all();
    // Validate and process payload (e.g., update local DB)
}

5. Attachments

Upload an Attachment

$ticket = Ticket::find(123);
$ticket->attachments()->create([
    'file_name' => 'screenshot.png',
    'file_size' => 1024,
    'file_content' => file_get_contents('path/to/screenshot.png'),
]);

Integration Tips

Laravel Eloquent Integration

Use the package’s models (Ticket, Contact, etc.) alongside Laravel’s Eloquent for seamless ORM operations.

Example: Eager-load relationships:

$ticket = Ticket::with('attachments', 'contact')->find(123);

API Rate Limiting

Freshdesk’s API has rate limits (e.g., 60 requests/minute). Cache responses aggressively:

$ticket = Cache::remember("ticket_{$id}", now()->addMinutes(5), function() use ($id) {
    return Ticket::find($id);
});

Error Handling

Wrap API calls in try-catch blocks:

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

Testing

Use Laravel’s HTTP tests to mock Freshdesk API responses:

public function test_ticket_creation() {
    $this->fake();
    $this->post('/api/tickets', ['subject' => 'Test']);
    $this->assertDatabaseHas('tickets', ['subject' => 'Test']);
}

Gotchas and Tips

Pitfalls

1. API Version Mismatch

The package defaults to v2 of the Freshdesk API. If you’re using v1, update the config:
```
FRESHDESK_API_VERSION=v1
```
Tip: Check Freshdesk’s API docs for breaking changes between versions.

2. Authentication Failures

If you get 401 Unauthorized, verify:
- The FRESHDESK_API_KEY is correct.
- The domain (FRESHDESK_DOMAIN) matches the Freshdesk subdomain (e.g., yourdomain.freshdesk.com).
- The API key has the right permissions (e.g., "API Access" enabled in Freshdesk admin settings).

3. Rate Limiting

Exceeding Freshdesk’s rate limits (e.g., >60 requests/minute) will return 429 Too Many Requests. Fix: Implement exponential backoff or use caching.

4. Missing Fields in Responses

Freshdesk’s API may return partial data for certain fields (e.g., custom_fields). Ensure your code handles null or missing keys:
```
$priority = $ticket->priority ?? 'N/A';
```

5. Webhook Verification

Freshdesk sends webhooks with a X-Freshdesk-Signature header. Always verify it to avoid spoofing:

use Freshdesk\Webhook;

public function handle(Request $request) {
    if (!Webhook::verify($request->header('X-Freshdesk-Signature'), $request->getContent())) {
        abort(403, 'Invalid webhook signature');
    }
    // Process payload
}

Debugging Tips

1. Enable Debug Mode

Set FRESHDESK_DEBUG=true in .env to log raw API responses:
```
FRESHDESK_DEBUG=true
```
Check logs in storage/logs/laravel.log.

2. Inspect Raw API Calls

Use Laravel’s HTTP client middleware to log requests:

// In AppServiceProvider boot()
$this->app['http']->macro('logRequest', function ($request) {
    \Log::debug('Freshdesk Request:', [
        'url' => $request->url(),
        'method' => $request->method(),
        'data' => $request->toArray(),
    ]);
});

3. Test with Postman/cURL

Replicate API calls manually to isolate issues:

curl -X GET \
  -H "Authorization: Basic YOUR_API_KEY" \
  "https://yourdomain.freshdesk.com/api/v2/tickets/123"

Extension Points

1. Custom API Endpoints

Extend the package to support unsupported endpoints by creating a custom client:

use Freshdesk\Client;

$client = new Client();
$response = $client->get('/api/v2/search/tickets', [
    'query' => 'subject:"urgent"'
]);

2. Model Observers

Add custom logic to Freshdesk models using Laravel’s observers:

// app/Observers/TicketObserver.php
class TicketObserver {
    public function saved(Ticket $ticket) {
        // Send Slack notification on ticket creation
    }
}

Ticket::observe(TicketObserver::class);

3. Queue Delayed API Calls

Offload API calls to queues to avoid timeouts:
```
Ticket::dispatchSyncOnConnection('freshdesk')->create([...]);
```
Configure the queue in config/queue.php.

4. Local Overrides

Override Freshdesk’s responses for testing by mocking the Client:

$this->app->bind(\Freshdesk\Client::class, function () {
    return Mockery::mock(\Freshdesk\Client::class)->makePartial();
});

Freshdesk Laravel Laravel Package