Create PHP SDKs from Swagger / OpenAPI

PHP SDK Overview

The Speakeasy PHP SDK is designed to be easy to use and debug, uses object-oriented programming in PHP for a robust and typed experience, and is 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
A convenient factory pattern manages the SDK configuration

The SDK uses few dependencies, including:

guzzlehttp/guzzle - Used to provide an HTTP client
jms/serializer - Tooling for data serialization and deserialization
Brick\DateTime - Support for Date objects

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 Speakeasy PHP SDK provides a default HTTP client implementation using \GuzzleHttp\Client for making API calls, which can be overridden. The client must implement the \GuzzleHttp\ClientInterface.

To override the HTTP client, pass 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 and Classes

Where possible, the Speakeasy PHP SDK uses native types:

string
\DateTime
int
float
bool

Where PHP doesn't have a builtin type, external dependencies are used:

Date - Brick\DateTime::LocalDate

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

Type Safety

Modern PHP uses type hints to improve code readability and so do Speakeasy-generated PHP SDKs! Speakeasy-generated PHP SDKs expose type annotations for developers to perform type checks at runtime and increase type safety.

The generated models

The PHP Speakeasy client generates models where all properties are carefully typed. These types can dictate not only the type of data, but also whether data is optional, or nullable.

For example, a drink object definition might look like:


class Drink 
{
    /**
     * The name of the drink
     *
     * @var string $name
     */
    public string $name;
    /**
     * The price of one unit of the drink in US cents.
     *
     * @var float $price
     */
    public float $price;
    
    /**
     * The type of drink.
     *
     * @var ?DrinkType $type
     */
    public ?DrinkType $type;
    /**
     * The number of units of the drink in stock, only available when authenticated.
     *
     * @var ?int $stock
     */
    public ?int $stock
    /**
     * The product code of the drink, only available when authenticated.
     *
     * @var ?string $productCode
     */
    public ?string $productCode
    public function __construct(string $name, float $price, ?DrinkType $type, ?int $stock, ?string $productCode)
    {
      ..snip..
    }
}

Parameters

When configured, Speakeasy will attempt to prefer a certain number of parameters to be included in the function signatures directly rather than provided as an object to be passed to the operation methods. This number is configured using the maxMethodParams option in gen.yaml. Whatever value is in that option will be the maximum number of parameters placed 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 Speakeasy PHP SDK returns errors by throwing the appropriate error class as part of the sdk call. The caller should wrap requests, and catch the error on the response.

User Agent Strings

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


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

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

Upgrading from Alpha build

We are working hard to make PHP a fully supported generation target, and until we reach GA, the SDK interface must be expected to change.

One such change that significantly affects PHP target is the added support for typed object constructors. This change allows us to have stronger type checking, but requires that all non-optional values are provided at constructor time.