dmorenof / sdk-generator
Contract-driven PHP SDK generator, built around a small reusable runtime.
Requires
- php: ^8.4
- composer-runtime-api: ^2.2
- ext-intl: *
- dmorenof/sdk-runtime: ^1.9.0
- friendsofphp/php-cs-fixer: ^3.95
- symfony/yaml: ^7.2
Requires (Dev)
- guzzlehttp/guzzle: ^7.9
- phpstan/phpstan: ^2
- phpunit/phpunit: ^11.5
- psr/http-client: ^1.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v1.10.0
- v1.9.0
- v1.8.0
- v1.7.0
- v1.6.0
- v1.5.0
- v1.4.0
- v1.3.1
- v1.3.0
- v1.2.0
- v1.1.0
- v1.0.0
- v0.40.0
- v0.39.0
- v0.38.0
- v0.37.0
- v0.36.0
- v0.35.0
- v0.34.0
- v0.33.0
- v0.32.0
- v0.31.0
- v0.30.0
- v0.29.1
- v0.29.0
- v0.28.0
- v0.27.0
- v0.26.1
- v0.26.0
- v0.25.0
- v0.24.0
- v0.23.0
- v0.22.0
- v0.21.0
- v0.20.0
- v0.19.0
- v0.18.0
- v0.17.0
- v0.16.0
- v0.15.0
- v0.14.0
- v0.13.0
- v0.12.0
- v0.11.0
- v0.10.0
- v0.9.0
- v0.8.0
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.1
- v0.4.0
- v0.3.0
- v0.2.0
- v0.1.0
- dev-claude/busy-franklin-9x9zpa
- dev-release/0.2.0
- dev-feature/p0-contract-fidelity
- dev-feature/native-model-inheritance
- dev-docs/mark-v0.2.0-released
- dev-feature/unified-dto-psr12-public-api
- dev-benchmark/route-namespaces-final-0.2.0
- dev-benchmark/route-namespaces-0.2.0
- dev-benchmark/openapi-generator-7.27
- dev-feature/0.2.0-core-inheritance
- dev-benchmark/runtime-parity-guzzle
- dev-feature/zero-config-psr18-client
- dev-benchmark/openapi-generator-baseline
- dev-feature/ci-preview-and-second-api
- dev-feature/executable-generated-clients
- dev-feature/php-contract-emitter
- dev-feature/contract-normalization-prototype
- dev-design/contract-pipeline-first-vertical-slice
- dev-feature/ci-quality-release-automation
This package is auto-updated.
Last update: 2026-11-20 00:41:47 UTC
README
Turn an OpenAPI or Swagger file into a typed PHP SDK you can install with Composer.
php bin/generate-sdk.php api.json build/acme-sdk 'Acme\Sdk' acme/sdk
You get a Composer package with typed models, backed enums, typed collections and one method per operation. Your application then calls the API like this:
$user = Users::getById(88); $body = new NewUser(); $body->name = 'Grace'; $created = Users::post($body);
Who it is for
PHP developers who consume a REST API that publishes an OpenAPI/Swagger contract and want a client that is typed, validated and cheap to maintain: when the contract changes, you regenerate.
It is a deliberately limited subset of OpenAPI, not a replacement for the full OpenAPI Generator. What it does not support is rejected with a clear message instead of being silently ignored (see supported scope).
How it fits together
| Piece | Role |
|---|---|
| sdk-generator (this repository) | Build-time tool. Reads the contract and writes the SDK. Not needed when the SDK runs. |
| sdk-runtime | Shared engine every generated SDK requires: HTTP (Guzzle/PSR-18), authentication, hydration, validation, errors, retries. Written and tested once. |
| Your generated SDK | Only what is specific to the API: models, operations, names. |
Because the engine is shared, a generated SDK is small and a fix in the runtime reaches every SDK with a composer update.
A real example: casafari-sdk is generated from the Casafari CRM contract with this tool.
Requirements
PHP 8.4 or newer, Composer 2.2 or newer. Generated SDKs require PHP 8.4 and dmorenof/sdk-runtime ^1.9.0.
composer require --dev dmorenof/sdk-generator
Quick start
composer install
php bin/generate-sdk.php \
tests/fixtures/accounts-openapi31.json \
build/accounts-sdk \
'Example\AccountsSdk' \
example/accounts-sdk
cd build/accounts-sdk && composer install
Arguments: the specification (JSON, or YAML with .yaml/.yml), an output directory (empty or absent), the PHP root namespace and the Composer package name.
Using the generated SDK:
use Example\AccountsSdk\{Configuration, ExampleAccountsSDK, Users}; use Example\AccountsSdk\DTOs\NewUser; $config = new Configuration(); $config->baseUrl = 'https://api.example.com/v1'; ExampleAccountsSDK::configure($config); $user = Users::getById(88); $body = new NewUser(); $body->name = 'Grace'; $created = Users::post($body);
Static route classes (Users::...) mirror the URL structure and share one configuration. For several independent connections use Client::connect($config) and $client->resource(Users::class). Endpoints above exist in the example Accounts specification; yours come from your contract.
Options
| Option | Effect |
|---|---|
--strict |
Refuse anything the generator cannot execute. |
--validate-formats |
Assert declared formats (date-time, uuid, …). |
--inspect / --dry-run |
Report what would be generated without writing files. See contract inspection. |
--resolve-local-references, --reference-root=DIR |
Follow $ref to local files. See file references. |
Validation, in short
Every property that has rules gets a PHP 8.4 set hook in the generated model, so a value is checked where it enters the model, once: when you assign it or when the model is built from JSON. Nothing is validated again when a request is sent, and json_encode($model) only serializes. $model->validate() checks everything on demand. Two limits of PHP 8.4 hooks: a property with a hook cannot be unset, and native array properties get no hook (a hooked property cannot be edited in place), so lists with rules are checked when the model is built and by typed collections. PHP has no 32-bit integer, so the range of int32 is always asserted; other formats only with --validate-formats. Details: the runtime's validation guide.
What is supported
- Swagger 2.0, OpenAPI 3.0.x and 3.1.x, in JSON or YAML.
- Models, enums, typed collections, maps, discriminators,
allOf/oneOf/anyOfwithin limits. - Path, query, header and cookie parameters; JSON, forms, multipart, text and binary bodies; exact/range/default response selection.
- Security: API key, HTTP basic/bearer, OAuth2 and OpenID Connect (a token you supply, or a token provider such as
OAuth2ClientCredentials) an OpenID Connect scheme'sopenIdConnectUrl(the generated client offersClient::openIdDiscovery(), which fetches the provider's endpoints) and, in OpenAPI 3.1,mutualTLS(aClientCertificatethe default Guzzle transport presents in the TLS handshake of the operations that require it), selected per operation. OAuth2 endpoints and scopes are not generated into the SDK.
Not supported (rejected, not ignored): remote $ref, structured XML/CSV models and the more exotic schema compositions. The exact list is in SUPPORTED_SCOPE.md.
Speed and honesty
Against OpenAPI Generator 7 on the same specifications, a call through our SDK is about 1.5× slower (about 92 µs against 62 µs on a mocked request), because it also validates, selects security, decodes errors and applies retry and redirect policies. We claim no speed advantage. See the audit and benchmark/.
Documentation
Supported scope · Design and naming · Public API · Ready-to-use client · Try without local PHP · Changelog · Releasing · Roadmap
One document per feature area lives in docs/: forms, query arrays and objects, path styles, cookies, responses, error payloads, schema rules and more.
Development
composer install composer validate --strict --no-check-lock bash ci/run-tests.sh --coverage
CI runs PHPUnit on PHP 8.4 and 8.5, minimum compatible dependencies, an advisory audit, and installs and smoke-tests generated SDKs.
License
MIT — LICENSE.