I learned this the hard way.

In one project, all my tests were green. My mocks returned exactly what I expected. A week later, the external API removed one field from the response. My mocks didn’t know about the change. Production did.

Mocks told me everything was fine. Reality disagreed.

This is exactly the kind of problem contract testing is meant to solve. In this article, I’ll show you how to use contract testing for external APIs in PHP with Pact, using a real-world Laravel example.

Why Mocking External APIs Is Not Enough

Mocking external APIs is useful. I still do it. It makes tests fast, deterministic, and cheap. But mocks have one fatal flaw:

They only test your assumptions about the API, not the API itself.

Typical problems I’ve seen in production:

• The API removes or renames a field.
• A nested structure changes shape.
• The API starts returning 404 instead of 200 in some edge cases.
• The API adds a required field to the request body.

Your mocks will never catch this unless you manually update them. That means mocks alone can silently drift away from reality.

What Is Contract Testing (In Plain English)

Contract testing sits between mocking and full integration tests.

Instead of saying:

“This is what I think the API returns,”

you say:

“This is the contract between my app (consumer) and the API (provider).”

With consumer-driven contract testing:

• The consumer defines what it expects from the API.
• The provider must verify that it actually fulfills this contract.

If the provider changes something that breaks the contract, tests fail before production breaks.

This turns breaking API changes from a runtime surprise into a build-time failure.

Diagram: How contract testing works between a Laravel consumer, Pact mock server, and the real API provider.

Real-World Scenario: Laravel as API Consumer

Let’s assume a Laravel application integrates with an external billing API:

GET /api/customers/{id}

Response:
{
  "id": 123,
  "email": "john@example.com",
  "is_active": true
}

GET /api/customers/{id}

Response:
{
  "id": 123,
  "email": "john@example.com",
  "is_active": true
}

Your Laravel service:

class BillingClient
{
    public function getCustomer(int $id): array
    {
        $response = Http::get("https://billing.example.com/api/customers/{$id}");

        return $response->json();
    }
}

class BillingClient
{
    public function getCustomer(int $id): array
    {
        $response = Http::get("https://billing.example.com/api/customers/{$id}");

        return $response->json();
    }
}

Your application relies on:

• email
• is_active

If the provider removes is_active, your app breaks. Mocks won’t catch it. Contract testing will.

Step-by-Step: Contract Testing with Pact in Laravel

Installing Pact for PHP

Install Pact dependencies for your test environment:

composer require --dev pact-foundation/pact-php

You’ll also need the Pact CLI running locally or in CI (usually via Docker).

Writing the Consumer Contract Test

The goal: define what your Laravel app expects from the API.

Example consumer test:

public function test_it_fetches_customer_from_billing_api()
{
    $builder = new InteractionBuilder();
    
    $builder
        ->given('Customer 123 exists')
        ->uponReceiving('A request for customer 123')
        ->with([
            'method' => 'GET',
            'path'   => '/api/customers/123',
        ])
        ->willRespondWith([
            'status' => 200,
            'headers' => ['Content-Type' => 'application/json'],
            'body' => [
                'id' => 123,
                'email' => 'john@example.com',
                'is_active' => true,
            ],
        ]);

    $builder->verify(function () {
        $client = new BillingClient();
        $customer = $client->getCustomer(123);

        $this->assertSame('john@example.com', $customer['email']);
        $this->assertTrue($customer['is_active']);
    });
}

public function test_it_fetches_customer_from_billing_api()
{
    $builder = new InteractionBuilder();
    
    $builder
        ->given('Customer 123 exists')
        ->uponReceiving('A request for customer 123')
        ->with([
            'method' => 'GET',
            'path'   => '/api/customers/123',
        ])
        ->willRespondWith([
            'status' => 200,
            'headers' => ['Content-Type' => 'application/json'],
            'body' => [
                'id' => 123,
                'email' => 'john@example.com',
                'is_active' => true,
            ],
        ]);

    $builder->verify(function () {
        $client = new BillingClient();
        $customer = $client->getCustomer(123);

        $this->assertSame('john@example.com', $customer['email']);
        $this->assertTrue($customer['is_active']);
    });
}

This test:

• defines the expected request
• defines the expected response
• generates a contract file (Pact file)

This contract is the single source of truth between consumer and provider.

Verifying the Contract on the Provider Side

On the provider side, the API team runs Pact verification:

pact-verifier --provider-base-url=http://localhost:8000 \
 --pact-url=./pacts/billing-consumer.json

pact-verifier --provider-base-url=http://localhost:8000 \
 --pact-url=./pacts/billing-consumer.json

If the API no longer returns is_active, verification fails.

This is the key difference from mocks:

• mocks only test the consumer
• contract testing tests the agreement

Running Contract Tests in CI

This is where contract testing becomes powerful.

Typical CI flow:

1. Consumer tests generate Pact contracts.
2. Provider pipeline verifies contracts.
3. Pipeline fails if contracts are broken.

This creates a safety net:

API changes cannot be deployed if they break existing consumers.

Common Mistakes with Contract Testing

Over-Specifying Responses

Don’t lock down every field if you don’t need it.
Only define what your app actually uses.

Only Testing Happy Paths

Include error contracts:

• 404 responses
• validation errors
• unauthorized responses

Not Versioning Contracts

Treat contracts like code. Version them.

Not Enforcing Contracts in CI

If no pipeline enforces them, contract testing is just documentation.

When Contract Testing Is Worth It (and When It’s Overkill)

Contract testing is worth it when:

• multiple teams own different services
• APIs evolve frequently
• breaking changes are expensive

It’s probably overkill when:

• the integration is trivial
• you don’t control the provider
• the API is stable and rarely changes

Contract testing is a scalpel, not a hammer. Use it where API stability matters.

How Contract Testing Fits into Your Laravel Testing Strategy

This is how I think about testing layers in real projects:

• Unit tests – business logic
• Feature tests – HTTP flows
• Mocks – isolate slow or unstable services
• Contract tests – protect integrations from breaking changes

Mocks keep your tests fast.
Contract tests keep your integrations honest.

They solve different problems and work best together.

Final Thoughts

Mocking external APIs is necessary — but it’s not sufficient.

If your application depends on external services and you’ve ever been surprised by a breaking API change in production, contract testing is the missing safety net.

You don’t need to contract-test everything. Start with one critical integration. Add one contract. Let your CI enforce it. The first time a breaking change is caught before deployment, contract testing pays for itself.

The post Contract Testing External APIs in PHP with Pact (Real Laravel Example) appeared first on CodeCraft Diary.

This article walks you through mocking external HTTP APIs in plain PHP, from basics to advanced techniques, with sandbox-style examples you can run immediately. We’ll cover:

• Why mocking is essential
• Creating a PHP API client
• Mocking responses with Guzzle
• Dynamic and conditional fake responses
• Simulating error conditions (timeouts, server errors)
• Asserting requests were made correctly
• Sequential responses for testing retries
• Using sandbox APIs for integration

Previous article in testing category: https://codecraftdiary.com/2026/01/03/testing-database-logic-what-to-test-what-to-skip-and-why-it-matters/

1. Why Mock External API Calls

Before diving into code, here’s why mocking is crucial:

a. Speed
Live HTTP calls dramatically slow down tests — often orders of magnitude slower than in-memory logic.

b. Stability
Third-party APIs can be unreliable, returning downtime or throttling, which makes tests flaky.

c. Isolation
Tests should verify your application logic, not the availability or correctness of external services.

d. Cost and Limits
Calling paid APIs every test run can incur costs or hit rate limits.

2. Creating a PHP HTTP Client

We’ll use Guzzle as our HTTP client. Here’s a simple WeatherClient:

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

class WeatherClient
{
    private Client $client;
    private string $baseUrl;
    private string $apiKey;

    public function __construct(string $baseUrl, string $apiKey)
    {
        $this->baseUrl = $baseUrl;
        $this->apiKey = $apiKey;
        $this->client = new Client(['base_uri' => $baseUrl]);
    }

    public function getCurrent(string $city): array
    {
        try {
            $response = $this->client->request('GET', '/current', [
                'query' => ['q' => $city, 'key' => $this->apiKey],
                'http_errors' => false
            ]);
            return json_decode($response->getBody()->getContents(), true);
        } catch (RequestException $e) {
            throw new \RuntimeException("API request failed: ".$e->getMessage());
        }
    }
}

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

class WeatherClient
{
    private Client $client;
    private string $baseUrl;
    private string $apiKey;

    public function __construct(string $baseUrl, string $apiKey)
    {
        $this->baseUrl = $baseUrl;
        $this->apiKey = $apiKey;
        $this->client = new Client(['base_uri' => $baseUrl]);
    }

    public function getCurrent(string $city): array
    {
        try {
            $response = $this->client->request('GET', '/current', [
                'query' => ['q' => $city, 'key' => $this->apiKey],
                'http_errors' => false
            ]);
            return json_decode($response->getBody()->getContents(), true);
        } catch (RequestException $e) {
            throw new \RuntimeException("API request failed: ".$e->getMessage());
        }
    }
}

• GuzzleHttp\Client handles HTTP requests
• Works in plain PHP without Laravel

3. Mocking API Responses with Guzzle

Guzzle provides MockHandler to simulate responses. Here’s a basic test:

<?php
use GuzzleHttp\Client;
use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Psr7\Response;

// Mock API response
$mock = new MockHandler([
    new Response(200, [], json_encode([
        'location' => ['name' => 'London'],
        'current' => ['temp_c' => 18]
    ]))
]);

$handlerStack = HandlerStack::create($mock);
$client = new Client(['handler' => $handlerStack, 'base_uri' => 'https://api.weather.com']);

// Inject mock client into WeatherClient
$weatherClient = new WeatherClient('https://api.weather.com', 'dummy-key');
$ref = new ReflectionClass($weatherClient);
$prop = $ref->getProperty('client');
$prop->setAccessible(true);
$prop->setValue($weatherClient, $client);

// Make request (uses mocked response)
$result = $weatherClient->getCurrent('London');

echo "City: ".$result['location']['name']."\n";   // London
echo "Temperature: ".$result['current']['temp_c']."°C\n"; // 18

<?php
use GuzzleHttp\Client;
use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Psr7\Response;

// Mock API response
$mock = new MockHandler([
    new Response(200, [], json_encode([
        'location' => ['name' => 'London'],
        'current' => ['temp_c' => 18]
    ]))
]);

$handlerStack = HandlerStack::create($mock);
$client = new Client(['handler' => $handlerStack, 'base_uri' => 'https://api.weather.com']);

// Inject mock client into WeatherClient
$weatherClient = new WeatherClient('https://api.weather.com', 'dummy-key');
$ref = new ReflectionClass($weatherClient);
$prop = $ref->getProperty('client');
$prop->setAccessible(true);
$prop->setValue($weatherClient, $client);

// Make request (uses mocked response)
$result = $weatherClient->getCurrent('London');

echo "City: ".$result['location']['name']."\n";   // London
echo "Temperature: ".$result['current']['temp_c']."°C\n"; // 18

• No real HTTP requests are made
• Ideal for unit testing

3a. Basic Example: Mocking a Simple API in Plain PHP Sandbox

This version shows how to simulate external API responses in plain PHP, without Guzzle or Laravel, making it suitable for online sandbox environments like onlinephp.io.

<?php
// Simple WeatherClient that returns fake responses
class WeatherClient
{
    private $baseUrl;
    private $apiKey;

    public function __construct(string $baseUrl, string $apiKey)
    {
        $this->baseUrl = $baseUrl;
        $this->apiKey = $apiKey;
    }

    // Fake API call returning predefined data
    public function getCurrent(string $city): array
    {
        $fakeApiResponses = [
            'London' => [
                'location' => ['name' => 'London'],
                'current' => ['temp_c' => 18, 'condition' => 'Partly cloudy']
            ],
            'New York' => [
                'location' => ['name' => 'New York'],
                'current' => ['temp_c' => 22, 'condition' => 'Sunny']
            ]
        ];

        return $fakeApiResponses[$city] ?? [
            'location' => ['name' => $city],
            'current' => ['temp_c' => null, 'condition' => 'Unknown']
        ];
    }
}

// --- Sandbox Test ---
$client = new WeatherClient('https://api.fakeweather.com', 'dummy-key');

$cities = ['London', 'New York', 'Paris'];

foreach ($cities as $city) {
    $result = $client->getCurrent($city);
    $temp = $result['current']['temp_c'] ?? 'unknown';
    $condition = $result['current']['condition'] ?? 'unknown';
    echo "City: {$result['location']['name']}, Temperature: {$temp}°C, Condition: {$condition}\n";
}

<?php
// Simple WeatherClient that returns fake responses
class WeatherClient
{
    private $baseUrl;
    private $apiKey;

    public function __construct(string $baseUrl, string $apiKey)
    {
        $this->baseUrl = $baseUrl;
        $this->apiKey = $apiKey;
    }

    // Fake API call returning predefined data
    public function getCurrent(string $city): array
    {
        $fakeApiResponses = [
            'London' => [
                'location' => ['name' => 'London'],
                'current' => ['temp_c' => 18, 'condition' => 'Partly cloudy']
            ],
            'New York' => [
                'location' => ['name' => 'New York'],
                'current' => ['temp_c' => 22, 'condition' => 'Sunny']
            ]
        ];

        return $fakeApiResponses[$city] ?? [
            'location' => ['name' => $city],
            'current' => ['temp_c' => null, 'condition' => 'Unknown']
        ];
    }
}

// --- Sandbox Test ---
$client = new WeatherClient('https://api.fakeweather.com', 'dummy-key');

$cities = ['London', 'New York', 'Paris'];

foreach ($cities as $city) {
    $result = $client->getCurrent($city);
    $temp = $result['current']['temp_c'] ?? 'unknown';
    $condition = $result['current']['condition'] ?? 'unknown';
    echo "City: {$result['location']['name']}, Temperature: {$temp}°C, Condition: {$condition}\n";
}

Why include this:

• Shows a fully runnable example in any PHP environment.
• Illustrates the concept of mocking/faking API responses without external dependencies.
• Complements the Guzzle-based example for readers who want a quick sandbox-ready approach.

4. Dynamic and Conditional Fake Responses

You can customize responses based on input:

$mock = new MockHandler([
    function ($request, $options) {
        parse_str($request->getUri()->getQuery(), $query);
        if ($query['q'] === 'US') {
            return new Response(200, [], json_encode(['data'=>'US result']));
        }
        return new Response(200, [], json_encode(['data'=>'Other result']));
    }
]);

$handlerStack = HandlerStack::create($mock);
$client = new Client(['handler' => $handlerStack]);

$mock = new MockHandler([
    function ($request, $options) {
        parse_str($request->getUri()->getQuery(), $query);
        if ($query['q'] === 'US') {
            return new Response(200, [], json_encode(['data'=>'US result']));
        }
        return new Response(200, [], json_encode(['data'=>'Other result']));
    }
]);

$handlerStack = HandlerStack::create($mock);
$client = new Client(['handler' => $handlerStack]);

• Use closures to decide response dynamically

5. Simulating Errors: Timeouts & Server Failures

a. Failed Connection / Timeout

$mock = new MockHandler([
    new \GuzzleHttp\Exception\ConnectException(
        "Connection failed",
        new \GuzzleHttp\Psr7\Request('GET', '/current')
    )
]);

$mock = new MockHandler([
    new \GuzzleHttp\Exception\ConnectException(
        "Connection failed",
        new \GuzzleHttp\Psr7\Request('GET', '/current')
    )
]);

b. Server Errors (HTTP 500)

$mock = new MockHandler([
    new Response(500, [], 'Internal Server Error')
]);

$mock = new MockHandler([
    new Response(500, [], 'Internal Server Error')
]);

c. Sequential Responses for Retry Logic

$mock = new MockHandler([
    new Response(500, [], 'Fail'),  // First request
    new Response(200, [], json_encode(['location'=>['name'=>'London'], 'current'=>['temp_c'=>20]])), // Second
]);

$mock = new MockHandler([
    new Response(500, [], 'Fail'),  // First request
    new Response(200, [], json_encode(['location'=>['name'=>'London'], 'current'=>['temp_c'=>20]])), // Second
]);

• Useful for testing retry behavior

6. Assertions

In PHPUnit, you can assert the results:

$this->assertEquals('London', $result['location']['name']);
$this->assertEquals(18, $result['current']['temp_c']);

$this->assertEquals('London', $result['location']['name']);
$this->assertEquals(18, $result['current']['temp_c']);

In a sandbox without PHPUnit, simple checks:

if ($result['location']['name'] === 'London') {
    echo "Test passed!\n";
} else {
    echo "Test failed!\n";
}

if ($result['location']['name'] === 'London') {
    echo "Test passed!\n";
} else {
    echo "Test failed!\n";
}

7. Using Fixtures for Realistic Responses

Instead of hardcoding JSON:

$body = file_get_contents('weather_fixture.json');
$mock = new MockHandler([ new Response(200, [], $body) ]);

$body = file_get_contents('weather_fixture.json');
$mock = new MockHandler([ new Response(200, [], $body) ]);

• Easier to maintain and mirrors real API structure

8. Integration Testing with Sandbox APIs

Some APIs provide sandbox environments (Stripe, PayPal, GitHub) where you can test real HTTP requests safely.

For full sandbox testing:

• Configure your client’s base URL to the sandbox
• Optionally, use Wiremock or similar mock servers for advanced stubbing
• Run integration tests against sandbox to ensure real API compatibility

9. Best Practices

• Mock external APIs only, don’t mock internal logic
• Use descriptive fixtures for clarity
• Include error scenarios in tests (timeouts, 500 errors)
• Combine unit tests (mocked) with occasional sandbox integration tests

The post Mocking External APIs in PHP (Sandbox Example) appeared first on CodeCraft Diary.