Author: Daryle De Silva

You inherit a codebase. Every API call wrapped in try-catch. Every exception swallowed. Every error returns an empty collection.

And nobody knows when things break.

The Anti-Pattern

Here’s what I found in a legacy integration:

public function getProducts(): Collection
{
    try {
        $response = Http::get($this->apiUrl . '/products');
        return collect($response->json('data'));
    } catch (Exception $e) {
        // "Handle" the error by pretending it didn't happen
        return collect([]);
    }
}

What happens when the API is down? Nothing. The method returns empty. The caller thinks there are no products. The error disappears into the void.

Weeks later, you’re debugging why users see blank pages. The real error? A 500 from the API three weeks ago that nobody noticed because the logs were clean.

Let It Fail

The fix is brutal: delete the try-catch.

public function getProducts(): Collection
{
    $response = Http::get($this->apiUrl . '/products');
    return collect($response->json('data'));
}

Now when the API fails, the exception bubbles up. Your error tracking (Sentry, Bugsnag, whatever) catches it. You get alerted. You fix it.

But What About Graceful Degradation?

If you genuinely want to fail gracefully, make it explicit:

public function getProducts(): Collection
{
    try {
        $response = Http::timeout(5)->get($this->apiUrl . '/products');
        return collect($response->json('data'));
    } catch (RequestException $e) {
        // Log it so you know it happened
        Log::warning('Product API failed', [
            'error' => $e->getMessage(),
            'url' => $this->apiUrl
        ]);
        
        // Return cached/stale data as fallback
        return Cache::get('products.fallback', collect([]));
    }
}

Now you’re:

• Logging the failure (visibility)
• Using a fallback strategy (resilience)
• Not silently lying to callers (honesty)

When to Catch

Catch exceptions when you have a recovery strategy:

• Retry logic: API hiccup? Try again.
• Fallback data: Cache, defaults, partial results.
• User-facing context: Transform technical errors into user messages.

If you’re just catching to return empty, you’re hiding problems.

Laravel’s Global Exception Handler

Laravel already has a system for this. Exceptions bubble to App\Exceptions\Handler, where you can:

// app/Exceptions/Handler.php
public function register()
{
    $this->reportable(function (RequestException $e) {
        // Log to Sentry/Slack/etc
    });
    
    $this->renderable(function (RequestException $e) {
        return response()->json([
            'error' => 'External service unavailable'
        ], 503);
    });
}

Now all API failures follow the same pattern. No more scattered try-catch blocks pretending everything’s fine.

The Takeaway

Empty catch blocks are lies. If you can’t handle the error meaningfully, let it bubble. Your future self — the one debugging at 2 AM — will thank you.

When refactoring code that talks to external APIs, how do you know you didn’t break something subtle?

Compare both the parsed response AND the raw wire format:

// Test old implementation
$oldClient = new OldApiClient($config);
$oldParsed = $oldClient->fetchData($params);
$oldRaw = $oldClient->getLastRawResponse();

// Test new implementation  
$newClient = new NewApiClient($config);
$newParsed = $newClient->fetchData($params);
$newRaw = $newClient->getLastRawResponse();

// Compare both
assert($oldParsed == $newParsed);  // Functional behavior
assert($oldRaw === $newRaw);       // Wire-level compatibility

Why both? Because:

• Parsed objects verify functional correctness
• Raw responses catch encoding issues, header differences, whitespace handling
• Some APIs are picky about request formatting even if the parsed result looks identical

This approach caught cases where new code was adding HTTP headers the old code didn’t send, and another where namespace handling differed slightly. Both “worked” but matching exact wire format means safer deployment.

When refactoring integrations, test the bytes on the wire, not just the objects in memory.

When building API integrations, it’s tempting to put helper methods on your DTOs. I learned this creates problems.

Started with “fat” DTOs:

class Product {
    public function getUniqueVariants() { ... }
    public function isVariantAvailable($type) { ... }
    public function getDisplayType() { ... }
}

Seemed convenient — call $product->getUniqueVariants() anywhere. But issues emerged:

1. Serialization problems: DTOs with methods are harder to cache/serialize
2. Testing complexity: need to mock entire DTO structures just to test one method
3. Coupling: business logic tied to the external API’s data structure

The fix — move all logic to a service class:

class ApiClient {
    public function getUniqueVariants(Product $product) { ... }
    public function isVariantAvailable(Product $product, string $type) { ... }
}

Now DTOs are pure data containers — just public properties or readonly classes. Business logic lives in services where it belongs.

Feels less convenient at first (passing DTOs as arguments), but far more maintainable. DTOs stay simple and serializable. Services become testable in isolation.

Working with third-party APIs means writing a lot of DTOs. So I built a quick code generator that turns JSON fixtures into typed PHP classes.

The workflow:

1. Capture fixtures: add HTTP middleware to dump API responses to JSON files
2. Analyze schema: scan fixtures, merge similar structures, infer types
3. Generate DTOs: output properly typed classes with serializer annotations

php artisan generate:dtos \
  --output=app/Services/SDK/ThirdParty \
  --namespace="App\\Services\\SDK\\ThirdParty"

The generator handles:

• Type inference from JSON values (string/int/float/bool/null)
• Nullability detection: if a field is missing in any fixture, it’s nullable
• Nested objects: creates separate classes for complex types
• Array types: uses Str::singular() to name item classes (products → Product)

This saved hours of manual DTO writing. The key insight: API responses are the source of truth. Let the actual data structure define your types, not the other way around.

Sometimes the best fix is deleting old fixes.

While consolidating API client code, I found this “normalization” logic in production:

$normalized = str_replace(
    ['SOAP-ENV:', 'xmlns:SOAP-ENV', 'xmlns:ns1'],
    ['soapenv:', 'xmlns:soapenv', 'xmlns'],
    $request
);

It looked intentional. Maybe the API was picky about namespace prefixes? Nope. It was breaking everything.

Removing the normalization fixed server errors that had been happening silently. The API worked fine with standard SOAP envelopes — the str_replace was stripping namespace declarations and causing “undeclared prefix” errors on the server side.

This kind of code survives because: (1) it was probably copy-pasted from a StackOverflow answer, (2) maybe it worked once on a different API, (3) nobody questioned it because it was already there.

When refactoring, actually test the old code path independently. Sometimes those “necessary” workarounds are just ancient bugs in disguise.