Create PHP SDKs from OpenAPI documents

PHP SDK overview

The Speakeasy PHP SDK is designed to be easy to use and debug, and uses object-oriented programming in PHP for a robust and strongly-typed experience.

Some core features of the SDK are:

• 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 builder pattern manages the SDK configuration, and request level options.
• Support for some OAuth flows and other standard security mechanisms.

New PHP features

Since the release of PHP 8 in 2020, the language has introduced additional type features, enabling better support for OpenAPI. Some of the features we take advantage of are:

• Union types

• Enums

External libraries

The Speakeasy PHP SDK seeks to support the majority of the OpenAPI Specification features, and as such, supports some features that aren’t contained in the PHP standard library.

Speakeasy fills the gaps using some external dependencies, which are detailed below.

Dates

PHP has only date-time objects, not date objects. Speakeasy uses Brick\DateTime  for date support. For example:

Complex numbers

PHP doesn’t have support for arbitrary precision numbers, so we use the Brick\Math  library for complex number support.

To learn more about Speakeasy’s complex number support, please read this page.

HTTP client

The SDK uses Guzzle  to provide a default HTTP client implementation, \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:

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

Exhaustive type system

Speakeasy uses a combination of the phpDocumentor TypeResolver  library and the built-in standard library type specifications to provide exhaustive type checking across all aspects of the generated SDK.

Serialization

Speakeasy uses JMS Serializer  for serialization due to its union support, which other serialization libraries lack.

JMS Serializer checks types received in responses at runtime, guaranteeing strong typing not only in comment annotations, but also while the application is in use and transferring data.

Files in the Speakeasy-created PHP SDK include the line declare(strict_types=1);, which causes PHP to throw a TypeError if a function accepts or returns an invalid type at runtime.

Type checking and linting

Speakeasy uses a combination of PHPStan  and Laravel Pint  for linting, performing quality control, and statically analyzing the SDK.

Quality and security

Speakeasy also uses Roave Security Advisories  to ensure that its dependencies do not have any known security advisories.

Tests

PHPUnit  is included with the SDK for running tests. However, no tests are created for the SDK automatically.

PHP SDK package structure

• src
• docs
• composer.json
• vendor

PHP SDK data types and classes

The Speakeasy PHP SDK uses native types wherever possible:

• string
• DateTime
• int
• float
• bool

Where no native data types are available, the Speakeasy PHP SDK uses libraries:

• Brick\DateTime\LocalDate
• Brick\Math\BigInteger
• Brick\Math\BigDecimal

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

Parameters

When configured, Speakeasy will include up to a specified number of parameters directly in the function signatures, rather than providing the list of parameters as an object to be passed to the operation methods.

The maximum number of parameters to be placed in the method signature is set in the maxMethodParams option in the gen.yaml file. If maxMethodParams is not set or is set to 0, no method parameters will be added.

Errors

The Speakeasy PHP SDK throws exceptions using the appropriate error class as defined in the sdk specification. Wrap requests in a try block to handle the error in the response.

User agent strings

The PHP SDK includes a user agent  string in all requests, which can be leveraged to track SDK usage amongst broader API usage. The format is as follows:

• 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.

Feature examples

Let’s take a look at how OpenAPI features are mapped to PHP code. We’ll use snippets from the Swagger PetStore 3.1  OpenAPI document, openapi.yaml. If you’re not familiar with the example, it provides operations for managing users, customers, pets, and orders for pets in a hypothetical pet store.

Tags

Each tag in the OpenAPI document becomes one file of top-level operations, such as Pet.php, Store.php, and User.php for:

Security

The Swagger Petstore OpenAPI document uses API key security and OAuth 2.0:

The PHP SDK creates a security class you can call with either scheme:

The implicit flow is the only OAuth flow currently supported.

Enums

Speakeasy uses native types in PHP 8 for enums.

Typed parameters

Consider the following example of an array of strings in openapi.yaml:

The PHP SDK types the parameter in a DocBlock.

You can use oneOf in an OpenAPI document like this:

The age property will be typed as a union in PHP: