Generate PHP SDKs from Swagger / OpenAPI

PHP SDK Overview

Speakeasy's PHP SDK is designed to be easy to use and debug, using object-oriented programing in PHP to create a useful and typed experience. It is also light on external dependencies.

Some of the core features of the SDK include:

Class-based objects using reflection and property attributes to aid serialization
A Utils package for common operations, simplifying generated code and making it easier to debug
Configuration of the SDK is performed using a convenient factory pattern
Authentication support for OAuth flows and other standard security mechanisms

The SDK uses only a small number of dependencies, including:

guzzlehttp/guzzle - used to provide an HTTP client
jms/serializer - tooling to add with data serialization

PHP Package Structure

lib-structure.yaml


|-- src                # root directory for all PHP source files
|   |-- SDK.php        # The main SDK class
|   |-- ...            # Other SDK classes
|   |-- Models
|   |   |-- Operations # The directory containing SDK request/response models
|   |   |   └-- ...
|   |   └-- Shared     # The directory containing SDK models generated from components
|   |       └-- ...
|   └-- Utils          # The directory containing utility classes
|       └-- ...
|-- docs               # Markdown files for the SDK's documentation
|   └-- ...
|-- composer.json      # Configuration for PHP composer
└-- ...

HTTP Client

The PHP SDK provides a means of overriding the HTTP client used to make the API calls. The client provided by implement the \GuzzleHttp\ClientInterface. A default implementation using \GuzzleHttp\Client is provided by default.

Overriding the HTTP client requires just passing the client during construction:


use GuzzleHttp\Client;
$client = new Client([
  'timeout' => 2.0,
]);
$sdk = SDK::builder()->setClient(
  $client
)->build();

This allows for full customization of low-level features like proxies, custom headers, timeouts, cookies, and others.

PHP SDK Data Types & Classes

Where possible the PHP SDK uses native types:

string
\DateTime
int
float
bool
etc...

The generated classes are standard PHP classes with public properties and use attributes and reflection to help guide serialization.

Parameters

When configured, we will attempt to prefer a certain number of parameters to be partof the function signatures directly, rather than provided as a an object to be passed to the operation methods. This is configured using the maxMethodParams option in gen.yaml. Whatever value is in that option will be the maximum number of parameters will place into the method signature.

The default value is 0, so if the maxMethodParams is not set (or set to 0), no method parameters will be added to operations.

Errors

The PHP SDK returns errors via the error property on the returned responses. The caller should check the status code on the response. If the status code indicates an error, it can then check the error property for details.

User Agent Strings

The PHP SDK will include a user agent (opens in a new tab) string in all requests. This can be leveraged for tracking SDK usage amongst broader API usage. The format is as follows:


speakeasy-sdk/php {{SDKVersion}} {{GenVersion}} {{DocVersion}} {{PackageName}}

Where

SDKVersion is the version of the SDK, defined in gen.yaml and released
GenVersion is the version of the Speakeasy generator
DocVersion is the version of the OpenAPI document
PackageName is the name of the package defined in gen.yaml