DEV Community: wadakatu

Contract testing a Symfony API with OpenAPI

wadakatu — Mon, 27 Jul 2026 13:42:42 +0000

Contract testing a Symfony API with OpenAPI takes four moving parts: the OpenAPI spec, a WebTestCase (or a plain Request/Response pair), one trait, and its assertions. This guide covers all four, then shows the full runnable example.

What is OpenAPI contract testing?

OpenAPI contract testing verifies that your live HTTP requests and responses conform to the OpenAPI schema you publish. The spec is the source of truth; the tests confirm the implementation still matches it — nothing more, nothing less.

This is the provider-side, spec-driven flavour of contract testing. It is different from consumer-driven contract testing (Pact and friends), which starts from what each consumer expects. Both are valid. Provider-side spec testing shines when you already publish OpenAPI and want a fast, per-endpoint check that the implementation hasn't drifted.

What you'll need

PHP 8.3+ and Symfony 6.4, 7.x, or 8.x
A Symfony application with symfony/http-foundation, symfony/http-kernel, and — for the WebTestCase / KernelBrowser flow — symfony/framework-bundle installed
An OpenAPI 3.0, 3.1, or 3.2 document you want to enforce
Gesso (studio-design/gesso), the framework-independent core plus its Symfony adapter

Install:

composer require --dev "studio-design/gesso:^2.0" \
  symfony/http-foundation symfony/http-kernel symfony/framework-bundle

The Symfony packages are suggestions, not hard requirements of Gesso — the core stays framework-independent, so you pull them in yourself to use the Symfony adapter. Skip symfony/framework-bundle if you only want the plain Request/Response form (shown further down); include it for the WebTestCase flow.

The four moving parts

1. The spec

Gesso finds spec files through the PHPUnit extension, not a Symfony bundle or a config/packages/*.yaml file. Register the extension in phpunit.xml:

<extensions>
    <bootstrap class="Studio\Gesso\PHPUnit\OpenApiCoverageExtension">
        <parameter name="spec_base_path" value="openapi"/>
        <parameter name="specs" value="petstore"/>
    </bootstrap>
</extensions>

spec_base_path is the directory holding your documents; specs lists the ones to report coverage for. YAML or JSON, 3.0.x, 3.1.x, or 3.2.x — the same loader accepts all of them (YAML needs symfony/yaml). Which spec a given test uses is pinned by a #[OpenApiSpec] attribute or by overriding openApiSpec(); there is no Laravel-style default_spec lookup in the Symfony adapter.

2. A WebTestCase

Extend Symfony's WebTestCase (or a plain PHPUnit class if you're constructing requests by hand):

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class PetsApiTest extends WebTestCase
{
    // ...
}

3. The trait

Mix in the Gesso Symfony assertion trait and name the spec:

use Studio\Gesso\Attribute\OpenApiSpec;
use Studio\Gesso\Symfony\OpenApiAssertions;

#[OpenApiSpec('petstore')]
class PetsApiTest extends WebTestCase
{
    use OpenApiAssertions;
}

The trait adds three assertion methods: assertResponseMatchesOpenApiSchema($request, $response) for responses, assertRequestMatchesOpenApiSchema($request) for requests, and assertClientMatchesOpenApiSchema($client), which runs both against the last call made by a test client.

4. The assertion

Either shape works. When you already have a KernelBrowser from static::createClient():

public function test_get_pets_matches_spec(): void
{
    $client = static::createClient();
    $client->request('GET', '/pets');

    $this->assertResponseIsSuccessful();
    $this->assertClientMatchesOpenApiSchema($client);
}

When you're constructing Request and Response objects directly — useful for unit-style tests that don't boot the kernel:

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

$request = Request::create('/pets', 'GET');
$response = new Response(
    '[{"id":1,"name":"Fido"}]',
    200,
    ['Content-Type' => 'application/json'],
);

$this->assertRequestMatchesOpenApiSchema($request, 200);
$this->assertResponseMatchesOpenApiSchema($request, $response);

Both forms record spec coverage.

The full example

The examples/symfony fixture in the Gesso repository installs and runs in CI on every push. To reproduce locally:

git clone https://github.com/studio-design/gesso.git
cd gesso/examples/symfony
composer install
composer test

The PHPUnit output ends with an OpenAPI Contract Test Coverage report: per spec, the share of endpoints fully covered and of (method, path, status, content-type) response rows validated, then a per-endpoint breakdown marking each row validated, skipped, uncovered, or request-only. That report is the point of running the tests: passing tests prove these operations conform; the coverage report shows which ones you haven't covered yet.

What to check next

Contract enforcement is the entry point. Three follow-ups matter for a real Symfony service:

Coverage in CI. Set min_endpoint_coverage / min_response_coverage on the PHPUnit extension so a PR that quietly stops testing an operation fails the build.
Preflight your spec. Run vendor/bin/gesso doctor --spec=openapi/petstore.json --strip-prefix=/api in CI. It reports whether Gesso can load and enforce the document — version and dialect, references, warned-about keywords, structurally valid operations — and exits non-zero when it can't.
Schema-driven exploration. Once the happy paths are green, generate request cases from the spec's schemas with OpenApiSpecExplorer::explore() and assert each dispatched response with the same validators the trait uses.

FAQ

Does this replace consumer-driven contract testing?
No. Provider-side spec testing verifies that your implementation matches the spec you publish. Consumer-driven testing (Pact) verifies that specific consumers' expectations are still met. If you publish OpenAPI and every consumer generates from it, provider-side testing covers the contract. If you have consumers with expectations the spec doesn't capture, keep Pact for those.

Does it work with a generated spec, like API Platform's?
Yes. Gesso loads a spec file; it does not care how the file was produced. OpenAPI documents generated by other tools — including API Platform — are treated the same as hand-authored ones, so long as the output is a valid OpenAPI 3.0/3.1/3.2 document on disk.

What about performance in a large test suite?
The parsed spec is cached and reused across assertions in the same test run. Validation cost per assertion scales with response body size and schema depth, not the total number of tests.

Does it validate requests too, or only responses?
Both, but with separate calls. assertClientMatchesOpenApiSchema($client) validates the outbound request and then the response of the last client call. assertResponseMatchesOpenApiSchema($request, $response) checks only the response — the Request is there to supply the method and path. Use assertRequestMatchesOpenApiSchema($request) for the request side of hand-built pairs.

Which OpenAPI versions are supported?
3.0.x, 3.1.x, and 3.2.x. oneOf/anyOf/allOf/not are validated in every supported dialect, and discriminator mappings are enforced by default rather than treated as a hint. OpenAPI 3.1/3.2 keep native JSON Schema 2020-12 semantics — const, prefixItems, unevaluatedProperties/unevaluatedItems, dependentSchemas/dependentRequired, $dynamicRef/$dynamicAnchor. OpenAPI 3.0 runs through a Draft 07 compatibility pipeline, so those 2020-12-only keywords warn instead of being enforced there.

Next step

The Symfony adapter is one of four; the same core powers Laravel, Pest, and PSR-7 setups. Start from the Symfony quickstart, or jump to the Schema-driven fuzzing guide once your happy paths are green.

Source and issue tracker: github.com/studio-design/gesso. MIT licensed.

Lumen (Laravel) v10 to v11: Contextual Binding Changes and Solutions.

wadakatu — Mon, 14 Apr 2025 02:06:10 +0000

Introduction

When upgrading from Lumen v10 to v11, have you ever been confused by unexpected behavior?

I encountered this issue myself when the changes to Contextual Binding caused previously functional code to stop working.

In this article, I will explain the changes to Contextual Binding with detailed sample code. We’ll look at how it worked in v10, the issues that arise in v11, and how to fix them step by step.

Reference: If you’d like to learn more about the basics of Contextual Binding, please refer to the official Laravel documentation.

Background of the Changes

【Key Changes】

Lumen v10: `when` method-based Contextual Binding applied across the entire DI chain (including indirect dependencies).

Lumen v11: `when` method-based Contextual Binding applies only when directly injected into the specified class.

In Lumen v10, the when method allowed Contextual Binding to propagate across the entire dependency injection (DI) chain.

In other words, a concrete class specified for one class's dependency was also reflected in subsequent layers of the DI chain.

However, as of v11, this behavior has changed. The when method now applies only to cases where the specified class is directly injected.

As a result, code that previously worked might stop functioning as intended.

Dependency Diagram

Here’s a diagram showing the dependencies discussed in this article:

Behavior in v10:
CreditController ──depends→ MoneyService ──depends→ PaymentInterface
     │                                                 ↑
     └────────────when().needs()───────────────────────┘
     (The PaymentInterface binding is correctly applied from CreditController)

Behavior in v11:
CreditController ──depends→ MoneyService ──depends→ PaymentInterface
     │                       │                         ↑
     └─when().needs()─╳      └─when().needs()──────────┘
     (The binding only applies to direct dependencies)

Let’s explore specific cases where this issue arises, along with code examples.

Example Code in v10

First, let’s look at example code that worked correctly in Lumen v10.

Configuration in AppServiceProvider

$this->app->bind(PaymentInterface::class, function ($app) {
    return new class implements PaymentInterface {
        public function paymentMethod(): string
        {
            return 'default';
        }
    };
});

$this->app
    ->when(CreditController::class)
    ->needs(PaymentInterface::class)
    ->give(function () {
        return new class implements PaymentInterface {
            public function paymentMethod(): string
            {
                return 'credit card';
            }
        };
    });

Here, PaymentInterface is configured to switch its concrete class based on CreditController.

CreditController

class CreditController extends Controller
{
    public function __construct(private MoneyService $moneyService)
    {
    }

    public function index(): string
    {
        return $this->moneyService->paymentMethod();
    }
}

CreditController injects MoneyService, which internally calls the paymentMethod of PaymentInterface.

MoneyService

class MoneyService
{
    public function __construct(private PaymentInterface $paymentInterface)
    {
    }

    public function paymentMethod(): string
    {
        return $this->paymentInterface->paymentMethod();
    }
}

MoneyService is a class that depends on PaymentInterface.

Execution Result

When this code is executed in Lumen v10, calling the index method of CreditController correctly returns 'credit card'.

Issues in v11

What happens if we run the same code in Lumen v11?

Cause of the Issue

CreditController injects MoneyService, which in turn injects PaymentInterface.

However, in v11, the when method applies only when directly injecting into the specified class. Therefore, even though CreditController is the basis of the configuration, the PaymentInterface passed to MoneyService remains the default, and 'default' is returned.

Execution Result

Calling CreditController returns 'default' instead of the expected 'credit card'.

Example of a Failing Test

No explicit error message appears, but the return value differs from expectations. For example, the following test will fail:

// Test code
public function testCreditControllerReturnsCorrectPaymentMethod()
{
    $response = $this->get('/credit');
    $this->assertEquals('credit card', $response->getContent());
    // Fails in v11 - 'default' is returned
}

In real-world environments, this discrepancy can cause features to break, requiring time-consuming debugging.

Fixed Code Example (v11-Compatible)

How can we make this code work correctly in Lumen v11?

The fix is simple: change the basis of the when method to MoneyService.

Configuration in AppServiceProvider

$this->app->bind(PaymentInterface::class, function ($app) {
    return new class implements PaymentInterface {
        public function paymentMethod(): string
        {
            return 'default';
        }
    };
});

$this->app
    ->when(CreditController::class) 
    ->needs(MoneyService::class)
    ->give(function () {
        $creditCardInterface = new class implements PaymentInterface {
            public function paymentMethod(): string
            {
                return 'credit card';
            }
        };
        return new MoneyService($creditCardInterface);
    });

Key Fix

`needs(PaymentInterface::class)` → `needs(MoneyService::class)`

Consider the DI chain, and specify the class that directly requires the interface.

The key here is changing the basis of the needs method from PaymentInterface to MoneyService.

This ensures that the correctly configured PaymentInterface is injected into MoneyService.

CreditController

class CreditController extends Controller
{
    public function __construct(private MoneyService $moneyService)
    {
    }

    public function index(): string
    {
        return $this->moneyService->paymentMethod();
    }
}

MoneyService

class MoneyService
{
    public function __construct(private PaymentInterface $paymentInterface)
    {
    }

    public function paymentMethod(): string
    {
        return $this->paymentInterface->paymentMethod();
    }
}

Execution Result

With this fixed code, calling the index method of CreditController correctly returns 'credit card'.

Conclusion

In summary, Lumen v11 enforces stricter scoping for Contextual Binding.

As a result, when using the when method, you need to carefully specify the correct class within the DI chain.

If you’ve encountered this behavior during an upgrade, please share your experience in the comments! If you know of alternative solutions or related documentation, feel free to share those as well :)

References

How to Handle Excessive Warning Messages When Running `pecl install grpc`

wadakatu — Wed, 25 Dec 2024 17:42:14 +0000

Overwhelming Warning Messages Can Be a Nuisance

When running pecl install grpc, you might encounter an avalanche of warning messages like these:

#7 67.72 /tmp/pear/temp/grpc/src/core/lib/promise/detail/promise_factory.h:174:5: warning: 'always_inline' function might not be inlinable [-Wattributes]

#7 352.5 /tmp/pear/temp/grpc/src/core/lib/event_engine/forkable.h:61:34: warning: 'unused' attribute ignored [-Wattributes]

There can be hundreds of these warnings, flooding your logs. This has been especially problematic during deployment, where CI/CD pipelines would exceed log limits, causing errors and halting the process.

The Root Cause

Searching for the warning messages online points to GCC, the GNU Compiler Collection.

It turns out these warnings are generated by the compiler when building gRPC's source code. Since the warnings originate from gRPC’s source code, it’s not feasible for users to fix the source code directly to suppress the warnings.

The Solution

Fortunately, GCC provides several options to suppress warning messages, which you can pass to the compiler during the build process:

Warning Options in GCC Documentation

However, there’s no straightforward way to pass these options directly when running pecl install grpc. If you know of one, please let me know—I’ll celebrate with tears of joy! 🥹

So, what now?

The answer came to me from a StackOverflow thread: Instead of letting pecl install handle everything, you can break the process into smaller steps and pass the options during the compilation phase.

Reference: StackOverflow

Since gRPC is written in C++, we can use environment variables like CFLAGS and CXXFLAGS to specify options that suppress the warnings during compilation:

Gentoo Wiki on GCC Optimization

Implementation

Let’s assume gRPC is being installed in a Dockerfile.

Before

RUN pecl install grpc

After

RUN pecl download grpc \
  && tar xzf $(ls grpc-*.tgz | head -n 1) \
  && cd $(ls -d grpc-*/ | head -n 1) \
  && phpize \
  && ./configure --with-php-config=/usr/local/bin/php-config \
  && make -e CFLAGS="-Wno-attributes -Wno-unused-parameter -Wno-deprecated-declarations -Wno-return-type" CXXFLAGS="-Wno-attributes -Wno-unused-parameter -Wno-deprecated-declarations -Wno-return-type" \
  && make install

The after commands mimic what pecl install does internally, but with more control. Breaking down the process revealed just how much pecl install handles behind the scenes—impressive!

The warnings appeared during the make phase, so I passed the suppression options via the CFLAGS and CXXFLAGS environment variables:

make -e CFLAGS="-Wno-attributes -Wno-unused-parameter -Wno-deprecated-declarations -Wno-return-type" CXXFLAGS="-Wno-attributes -Wno-unused-parameter -Wno-deprecated-declarations -Wno-return-type"

How to Identify Suppression Options

To determine which suppression options to use, look at the end of the warning messages. You’ll often see hints like [-Wattributes] or [-Wunused-parameter]. Add no to the beginning of these, e.g., -Wno-attributes or -Wno-unused-parameter, to suppress them.

For more details, refer to the official documentation:

Warning Options in GCC Documentation

Conclusion

With this approach, I successfully escaped the swamp of gRPC warning messages. However, this didn’t fully resolve the CI/CD log limit issue, which I’ll address in a future post.

If this article helps even one person escape the gRPC warning message swamp, I’ll be delighted! 🙌

Laravel 9, NO LTS Support!?

wadakatu — Tue, 22 Feb 2022 15:36:00 +0000

Latest LTS finally!!

Laravel 9 was finally released on February 22nd, 2022.

At first, we are thrilled with LTS (Long Term Support) of Laravel 9.

However, Mr.Otwell (The author of Laravel) decided to postpone the LTS.

Why Postponed?

You can find out the reason why the LTS is postponed on Mr.Otwell Tweet.

In short, a pull request on Symfony Repository causes the postponement of the LTS.

LTS Again?

The answer is "Maybe or Maybe not".

In my opinion, if the PR were rejected, There would be high probability that the LTS comes back.

What do you think about it?
Feel free to leave your thought on discussion.

Update! PHP 8.1 needed from Symfony 6.1

The PR was merged yesterday on Symfony.

Therefore, PHP 8.1 will be the minimum requirement for Symfony 6.1.

Read this article for more information.
https://symfony.com/blog/symfony-6-1-will-require-php-8-1

In Laravel, they have already merged a PR which changes the minimum PHP Version From 8.0 to 8.1 for Laravel 10.

[Laravel 8.x] Refactor Factory Call with One Command

wadakatu — Thu, 03 Feb 2022 11:01:03 +0000

Factory call changed

In Laravel 8.x, the style of factory call was changed from helper to static method.

//Laravel 7.x or earlier
factory(User::class)->make()

//Laravel 8.x
User::factory()->make()

It takes plenty of times to fetch this change into your application if you do by yourself.

Don't worry. I made a package to refactor all of them with Just One Command.

Laravel-Factory-Refactor

https://packagist.org/packages/wadakatu/laravel-factory-refactor

This package will help you to refactor the style of factory call from helper to static method for Laravel 8.x.

How to Use

1. Installation

You can install the package via composer:

composer require wadakatu/laravel-factory-refactor --dev

2. Run Artisan Command

php artisan refactor:factory

3. Voila, Refactor Completed !

//Before
factory(User::class)->make();
factory(App\Models\User::class)->make();
factory(User::class, 10)->make();
factory(App\Models\User::class, 10)->make();

//After
User::factory()->make();
App\Models\User::factory()->make();
User::factory()->count(10)->make();
App\Models\User::factory()->count(10)->make();

In conclusion

'Laravel-Factory-Refactor' is my first package ever in my life.

From now on, I am going to do my best to update this package to make it better.
I hope you are going to like it.

Moreover, I am looking forward to getting stars in Github⭐️

https://github.com/wadakatu/laravel-factory-refactor

Thank you.