Migrating to PHP SDK generator v3

Version 3.0.0 of the PHP SDK generator validates API responses by default. Release the regenerated SDK as a new major version, and share this page with your SDK users so they can update their code.

Before you upgrade

Generator versions 3.0.0 and later read configuration from sdk-config.yml instead of generators.yml. Run fern sdk migrate to create sdk-config.yml from your existing configuration.

Responses are validated against the schema

The validateResponses option is enabled by default. If a response doesn’t match its OpenAPI schema, the SDK throws a ValidationException from the generated SDK’s Exceptions namespace instead of returning a model.

Before

$plant = $client->plants->get($request);

After

use Plantstore\Exceptions\ValidationException;
try {
    $plant = $client->plants->get($request);
} catch (ValidationException $error) {
    // The response didn't match the declared schema.
}

If your SDK’s root namespace is Validation, its base exception is already named ValidationException. In that case, the SDK throws RequestValidationException for validation failures. Catch that class instead.

To fix: Handle ValidationException (or RequestValidationException) where responses may not match the schema. If the API returns responses that differ from the schema, fix the schema. Set validateResponses: false only after confirming the responses are correct.

Test the regenerated SDK

Generate the SDK with the previous and new generator from the same inputs. Install the new package in a clean environment and run the tests that cover API calls.

composer update plantstore/plantstore-php
vendor/bin/phpunit

For representative operations, verify the request URL, query string, headers, cookies, body format (including XML and multipart), retries, timeout behavior, and decoded result.