Blog

Auto-Generating Test Fixtures from Real API Responses with Guzzle Middleware

When integrating with external APIs, you need test fixtures. Manually crafting them is tedious and error-prone. Here’s a better way: use Guzzle middleware to automatically dump real API responses to files.

The Problem

You’re building a service provider for a third-party API. You need:

• Realistic JSON fixtures for unit tests
• Coverage of all API endpoints you use
• Responses that match the actual API structure (not guesswork)

Manually creating these is painful. The API response structure might have dozens of fields, nested objects, edge cases you haven’t seen yet.

The Solution: Temporary Dumper Middleware

Add a Guzzle middleware to your HTTP client that intercepts responses and saves them to disk:

use GuzzleHttp\HandlerStack;
use Illuminate\Support\Facades\Storage;

// In your service provider's register/boot method
$http = $this->app->make(HttpClientFactory::class)->make($logger);

/** @var HandlerStack $handler */
$handler = $http->getConfig('handler');

$handler->push(function (callable $next) {
    return function ($request, array $options) use ($next) {
        return $next($request, $options)->then(function ($response) use ($request) {
            // Build organized directory structure based on endpoint
            $path = trim($request->getUri()->getPath(), '/');
            $dir = base_path("temp/api-fixtures/{$path}");

            if (!is_dir($dir)) {
                mkdir($dir, 0755, true);
            }

            // Filename based on request body (for POST) or 'get' for GET requests
            $body = (string) $request->getBody();
            $filename = $body ? md5($body) : 'get';

            // Decode, pretty-print, and save
            $json = json_decode((string) $response->getBody(), true);
            file_put_contents(
                "{$dir}/{$filename}.json",
                json_encode($json, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES)
            );

            // IMPORTANT: Rewind the stream so the original code can still read it
            $response->getBody()->rewind();

            return $response;
        });
    };
}, 'fixture_dumper');

How It Works

Guzzle’s middleware system uses a chain-of-responsibility pattern. This middleware:

1. Intercepts the response after the HTTP request completes
2. Extracts the endpoint path from the request URI
3. Creates an organized directory structure mirroring your API (e.g., temp/api-fixtures/users/profile/)
4. Names files by request body hash (or ‘get.json’ for GET requests)
5. Saves pretty-printed JSON to disk
6. Rewinds the response body so your actual code can still read it

Example Output

After running your integration locally, you’ll have a fixture library like:

temp/api-fixtures/
├── products/
│   ├── get.json
│   └── abc123.json (POST /products with specific body)
├── orders/
│   ├── get.json
│   ├── def456.json
└── users/
    └── profile/
        └── get.json

Each file contains the exact JSON structure returned by the real API.

Using The Fixtures In Tests

Copy the generated fixtures to your test directory:

// tests/Fixtures/ExternalApi/products/get.json
// tests/Fixtures/ExternalApi/orders/get.json

// In your tests:
$mockClient = new MockHandler([
    new Response(200, [], file_get_contents(
        __DIR__ . '/../Fixtures/ExternalApi/products/get.json'
    )),
]);

$this->app->instance(ApiClient::class, new ApiClient(
    new Client(['handler' => HandlerStack::create($mockClient)])
));

When To Remove It

This is temporary development tooling, not production code. Remove the middleware once you have your fixtures:

// ❌ Remove before committing
$handler->push(function (callable $next) { ... }, 'fixture_dumper');

Or make it conditional:

if (config('app.debug') && config('api.dump_fixtures')) {
    $handler->push($fixtureD umperMiddleware, 'fixture_dumper');
}

Benefits

• Realistic test data – Exact structure from the real API
• Comprehensive coverage – Hit every endpoint once, get perfect fixtures
• No manual JSON crafting – Let the API do the work
• Update fixtures easily – Re-run with middleware enabled when API changes
• Organized by endpoint – Easy to find the fixture you need

The Takeaway

Guzzle middleware isn’t just for adding auth headers or logging. It’s a powerful tool for development workflows. Use it to auto-generate test fixtures from real API responses, then remove it before production. Your tests get realistic data, and you save hours of manual JSON wrangling.

PHP 8.1’s backed enums are perfect for managing database statuses with compile-time safety. Unlike magic strings, enums provide IDE autocomplete, prevent typos, and centralize status logic.

Why It Matters

In production applications, hardcoded strings for statuses like 'pending' or 'in_progress' are prone to typos and difficult to refactor. Backed enums solve this by providing a single source of truth for all possible states.

Implementation

enum OrderStatus: string
{
    case PENDING = 'pending';
    case PROCESSING = 'processing';
    case COMPLETED = 'completed';
    case CANCELED = 'canceled';
    case ON_HOLD = 'on_hold';
    
    public function getLabel(): string
    {
        return match($this) {
            self::PENDING => 'Awaiting Review',
            self::PROCESSING => 'In Progress',
            self::COMPLETED => 'Successfully Completed',
            self::CANCELED => 'Order Canceled',
            self::ON_HOLD => 'Paused',
        };
    }
    
    public static function toArray(): array
    {
        return collect(self::cases())
            ->mapWithKeys(fn($status) => [
                $status->value => $status->getLabel()
            ])
            ->toArray();
    }
    
    public function canTransitionTo(self $newStatus): bool
    {
        return match($this) {
            self::PENDING => in_array($newStatus, [self::PROCESSING, self::CANCELED, self::ON_HOLD]),
            self::PROCESSING => in_array($newStatus, [self::COMPLETED, self::CANCELED]),
            self::ON_HOLD => in_array($newStatus, [self::PROCESSING, self::CANCELED]),
            default => false,
        };
    }
}

Integrating with Eloquent

Laravel makes it incredibly easy to use enums by casting the database value directly to the enum class.

class Order extends Model
{
    protected $casts = [
        'status' => OrderStatus::class,
    ];
}

// Usage
$order->status = OrderStatus::COMPLETED;  // Type-safe!
$order->status->getLabel();  // "Successfully Completed"
OrderStatus::toArray();  // Perfect for  dropdowns

By centralizing status labels and transition logic within the Enum, you keep your controllers and models clean while ensuring consistency across your entire application.

			
March 16, 2026
		
		
	

		
		

			
			
Model Audit Trails with Laravel Revisionable
			
When building business-critical applications, implementing model audit trails is essential for debugging and compliance. The venturecraft/revisionable package (or similar) automatically tracks all changes to Eloquent models.
Why It Matters
In production incidents, being able to answer “what was the previous value?” or “who changed this?” can save hours of investigation. Audit trails reveal the complete state transition history of a record, making it trivial to identify mistakes and determine the correct rollback state.
Key Methods

$model->revisions()->get() – Get all revisions
$revision->getDiff() – See what changed
$revision->executor – Who made the change
$revision->created_at – When it happened

Implementation
// In your model
use Venturecraft\Revisionable\RevisionableTrait;

class Order extends Model
{
    use RevisionableTrait;
    
    protected $revisionCreationsEnabled = true;
    protected $dontKeepRevisionOf = ['updated_at'];
}

// Query revision history
$order = Order::find(123);
$history = $order->revisions()->get()->map(fn($r) => [
    'timestamp' => $r->created_at->toDateTimeString(),
    'user' => $r->executor?->email,
    'changes' => $r->getDiff()
]);

// Example output:
// [
//   'timestamp' => '2026-01-30 14:37:57',
//   'user' => '[email protected]',
//   'changes' => [
//     'status' => ['old' => 'pending', 'new' => 'completed']
//   ]
// ]

Pro Tip
Store the authenticated user’s ID automatically by implementing revisionCreationsEnabled() on your model. The package will track who made each change without additional code.

			
March 16, 2026
		
		
	

		
		

			
			
The Silent Loop Bug: Variable Assignment vs Array Append in PHP
			
A single character difference—one missing bracket—can cause a bug that survives months of code reviews and deployments. Here’s a PHP gotcha that’s easy to miss but painful to debug.
The Bug
Imagine you’re importing pricing data from an API. You loop through items and build a collection of Price objects:
foreach ($products->items as $item) {
    $price = $item->unitPrice;
    $prices = new Price($product->references, $price, null, null);
}

Spot the bug? It’s subtle but devastating.
That should be $prices[] = new Price(...), not $prices = new Price(...).
Without the brackets, you’re not appending to an array—you’re overwriting the variable on each iteration. After the loop completes, $prices contains only the last Price object instead of all of them.
Why It’s Dangerous
This bug pattern is particularly nasty because:

It compiles successfully – PHP sees nothing wrong
It’s visually subtle – Easy to miss in code review
It fails at runtime – Only when downstream code enforces type safety
The error manifests elsewhere – Not where the bug actually lives

Here’s what the downstream code might look like:
public function calculateTotals(array $prices): Collection
{
    return collect($prices)->map(function (Price $price) {
        return $price->calculateWithTax();
    });
}

When this runs, you’ll get:
TypeError: Argument #1 ($price) must be of type Price, array given

The error points to calculateTotals, but the actual bug is several calls upstream in the loop that builds $prices.
The Correct Pattern
Always use array append syntax when building collections in loops:
// ✅ CORRECT: Appends to array
foreach ($products->items as $item) {
    $price = $item->unitPrice;
    $prices[] = new Price($product->references, $price, null, null);
}
// Result: $prices contains ALL Price objects

If you initialize the array first, it’s even clearer:
$prices = [];
foreach ($products->items as $item) {
    $prices[] = new Price($item->references, $item->unitPrice, null, null);
}

How to Debug This
When you encounter a TypeError that points to downstream code but makes no sense (like “expected Price, got array”), trace it backward:

Check the stack trace in your error monitoring (Sentry, Bugsnag, etc.)
Use git blame on the lines in the stack to see recent changes
Reproduce locally with the exact command from logs
Add dd($prices) or var_dump($prices) right after the loop
Check if you’re getting a single object instead of an array

The actual bug location is often several commits before the reported error. In one real case, this bug existed for 13 days and generated 300 Sentry events before someone traced it back through the PR history.
Always reproduce errors locally before claiming a fix works. Type errors that seem impossible often point to bugs elsewhere in the call chain.

			
March 15, 2026
		
		
	

		
		

			
			
Pre-Flight API Validation: Stop Making Calls You Know Will Fail
			
Making unnecessary API calls wastes rate limits, adds latency, and pollutes your error logs. When you already have the data needed to avoid an invalid request, use it. Here’s how pre-flight validation saves time and money.
The Anti-Pattern
Consider a sync job that fetches pricing data for products:
public function syncProductPricing($productId, $startDate, $endDate)
{
    $pricing = $this->cache->remember(
        "pricing:{$productId}",
        3600,
        fn() => $this->apiClient->getProductPricing($productId, $startDate, $endDate)
    );
    
    $this->updatePricing($pricing);
}

This looks clean, but what if some products are “bundles” that don’t have individual pricing? The API will return a 422 error: “this is a bundle product, use the child product IDs instead”.
Every sync cycle, you make the invalid API call, catch the error, fail the job, and retry. Meanwhile, you’re burning rate limits on requests you know will fail.
The Fix: Validate Before You Call
Check your database first. You likely already have the information needed to avoid the invalid request:
public function syncProductPricing($productId, $startDate, $endDate)
{
    // Check if this is a bundle product (they don't have individual pricing)
    $product = Product::find($productId);
    
    if ($product->type === 'bundle') {
        Log::debug("Skipping bundle product {$productId}, syncing children instead");
        
        foreach ($product->childProducts as $child) {
            $this->syncProductPricing($child->id, $startDate, $endDate);
        }
        
        return;
    }
    
    // Safe to call API now
    $pricing = $this->cache->remember(
        "pricing:{$productId}",
        3600,
        fn() => $this->apiClient->getProductPricing($productId, $startDate, $endDate)
    );
    
    $this->updatePricing($pricing);
}

When to Validate Up Front
Apply this pattern when:

The API documents specific constraints or limitations
You have the validation data locally (database, config, etc.)
The check is cheaper than making the API call
The error is predictable and repeatable

The Benefits
This defensive approach delivers multiple wins:

Reduced API costs – Avoid calls you know will fail
Better performance – No network round-trip for validation errors
Preserved rate limits – Don’t waste quota on invalid requests
Cleaner logs – Only real errors appear in monitoring
Faster debugging – When errors DO occur, they’re genuine issues

Third-party API calls are expensive resources. Treat them like database queries: fetch only what you need, cache when possible, and validate constraints before making the request. Your error logs (and your rate limit quota) will thank you.

			
March 15, 2026
		
		
	

		
		

			
			
Graceful API Error Handling in Laravel Queue Jobs
			
Queue jobs that fail repeatedly on predictable API errors waste server resources and pollute your error tracking. Here’s how to handle known validation constraints gracefully instead of letting jobs retry forever.
The Problem
Imagine a background sync job that queries a third-party API. The job runs every hour, but some requests hit a validation constraint that the API rejects:
try {
    $data = $this->apiClient->getProductAvailability($productId, $startDate, $endDate);
} catch (ApiException $e) {
    throw new SupplierException(
        sprintf('Error connecting to API: %s', $e->getMessage())
    );
}

When the API returns a 422 error for a constraint like “this product is a bundle”, the job fails, logs to Sentry, and retries. If you have thousands of products and a fraction are bundles, you’ll generate hundreds of error events per day for a completely predictable scenario.
One real-world case generated 1,434 Sentry errors over 10 days before someone investigated.
The Solution: Graceful Error Handling
Instead of treating all API errors the same way, detect known validation constraints and handle them gracefully:
try {
    $data = $this->apiClient->getProductAvailability($productId, $startDate, $endDate);
} catch (ApiException $e) {
    // Check if this is a known validation constraint
    if ($e->getStatusCode() === 422 && str_contains($e->getMessage(), 'product is a bundle')) {
        Log::info("Skipping bundle product {$productId} - requires child product sync");
        
        // Optional: fetch child products and queue them instead
        $children = $this->apiClient->getBundleChildren($productId);
        foreach ($children as $childId) {
            SyncProductAvailability::dispatch($childId, $startDate, $endDate);
        }
        
        return; // Exit gracefully, don't retry
    }
    
    // For unexpected errors, fail loudly
    throw new SupplierException(
        sprintf('Error connecting to API: %s', $e->getMessage())
    );
}

Why This Matters
Queue jobs that fail on predictable errors have real costs:

Wasted compute – Retry logic consumes server resources for errors that will never resolve
Error noise – Real issues get buried in thousands of false-positive alerts
Rate limits – Repeated invalid requests can exhaust API quotas
Debugging friction – When real errors occur, they’re hidden in the noise

This is especially critical for high-volume background jobs where a single unhandled edge case can generate thousands of errors per day. By handling known constraints gracefully, you reduce noise, save retry costs, and can implement smart fallback logic like queuing child products.
When debugging queue job failures, check Sentry event counts. If you see the same error repeating hundreds of times, it’s likely hitting a predictable constraint that should be handled explicitly instead of retried.

			
March 15, 2026
		
		
	

		
		

			
			
Safely Updating Environment Variables Across Multiple Production Servers
			

When running a Laravel application across multiple production servers (load-balanced or distributed architecture), you need to update configuration values consistently across all servers without causing downtime or configuration drift.



The Problem



You have 8 servers running your application:




2 web servers (web1, web2)
2 API servers (api1, api2)
2 queue worker servers (worker1, worker2)
2 admin dashboard servers (admin1, admin2)




A third-party service changed their API endpoint from http://api.vendor.com/ to https://platform.vendor.com/, and you need to update the VENDOR_API_URL environment variable across all servers immediately.



The Solution



Use SSH commands combined with sed and grep to update .env files across all servers in one operation, with immediate verification.



Step 1: Check Current Values



for server in web1 web2 api1 api2 worker1 worker2 admin1 admin2; do
  echo "=== $server ==="
  ssh $server "grep '^VENDOR_API_URL=' /var/www/app/.env"
done



This gives you a baseline and confirms the current value is consistent across all servers.



Step 2: Update All Servers



for server in web1 web2 api1 api2 worker1 worker2 admin1 admin2; do
  ssh $server "sudo sed -i 's|^VENDOR_API_URL=\"http://api.vendor.com/\"|VENDOR_API_URL=\"https://platform.vendor.com/\"|' /var/www/app/.env && sudo grep '^VENDOR_API_URL=' /var/www/app/.env"
done



Key techniques:




Pipe delimiters in sed: s|old|new| instead of s/old/new/ avoids escaping forward slashes in URLs
Chain with grep: && immediately verifies each update
Use sudo: Handle file permission requirements
In-place edit: sed -i modifies the file directly




Step 3: Independent Verification



After all updates complete, run a fresh check to confirm consistency:



for server in web1 web2 api1 api2 worker1 worker2 admin1 admin2; do
  echo "=== $server ==="
  ssh $server "grep '^VENDOR_API_URL=' /var/www/app/.env"
done



All servers should now show the new value. Document the results in your deployment notes.



Important Considerations



Service Restarts Required



.env changes don’t take effect until services restart. Plan your restart strategy:




PHP-FPM: sudo systemctl reload php8.2-fpm
Queue Workers: sudo supervisorctl restart all or php artisan queue:restart
Laravel Octane: php artisan octane:reload




Consider rolling restarts to avoid downtime (restart workers first, then web servers one at a time).



Config Cache



If you’re using php artisan config:cache in production, updating .env alone won’t work. You need to rebuild the cache:



for server in web1 web2 api1 api2 worker1 worker2 admin1 admin2; do
  ssh $server "cd /var/www/app && php artisan config:clear && php artisan config:cache"
done



Why Not Ansible/Chef/Puppet?



Configuration management tools are great for infrastructure-as-code, but for urgent hotfixes or one-off changes, this SSH approach is:




Faster – No playbook to write/test/deploy
Transparent – You see exactly what changed in real-time
Auditable – Terminal history captures the exact commands
Simple – Works even if CM tools aren’t set up yet




For routine configuration updates, absolutely use your CM tool. But when you need to update an API endpoint across 8 servers right now, this approach gets the job done safely.



Pro Tips




Document before changing: Keep a record of old vs new values
Test on one server first: Verify the sed command works before running across all servers
Use SSH config: Simplify server names with ~/.ssh/config aliases
Consider tmux: Run parallel SSH sessions to see all updates simultaneously
Backup first: cp /var/www/app/.env /var/www/app/.env.backup before making changes




Need to update environment variables across your server fleet? This pattern ensures consistency, provides immediate verification, and gives you the confidence that all servers are aligned.

			
March 15, 2026