Skip to main content

Revamped PHP SDKs as Immutable Clients, Added Support for PHP 8.0

· 4 min read

APIMatic's PHP SDKs have been refactored to immutable clients and now support PHP 8.0 with updated dependencies. All static analysis and linting issues have been resolved, support for optional and nullable has been added along with a new restructured authorization flow, and much more.

Details​

Updated Language and Runtime Requirement​

We are now supporting PHP 7.2 and above.

Updated Dependencies​

Updated other dependencies to support PHP 8.0:

  • apimatic/jsonmapper: v2.0.2
  • squizlabs/PHP_codesniffer: v3.5
  • phan/phan: v3.0
  • PHPunit/PHPunit: v8.5

Applying Coding Standards​

All static analysis and linting issues have been resolved, which resulted in generating clean and human readable code.

Immutable Client​

To make the client thread safe and remove the need of explicit synchronization and defensive copying, we have made the client immutable. The following code explains how to work with an immutable client in PHP:

// Initialize the immutable client
$client = new MyClient([
    'environment' => 'production',
    'timeout' => 10,
    'port' => '80',
]);

// Get a copy of client's configurations
$configurations = $client->getConfiguration();

// Clone a client by overriding some of its configuration
$newClient = $client->withConfiguration([
    'timeout' => 20,
]);

Authorization​

Authorization structure has been greatly improved in APIMatic v3 SDKs. We now have separate authorization managers, which are not only responsible for encapsulation of authorization credentials, but are also used to apply authorization to each endpoint (where required). Besides updating flow for authorization handling, we have also added support for custom authorization and OAuth 2.0.

The following code sample shows how to set/get authorization in the client:

// Initialize the immutable client with basic authorization
$client = new MyClient([
    'environment' => 'production',
    'username' => 'api-key',
    'password' => 'Qaws2W233WedeRe4T56G6Vref2',
]);

// Get username and password from configuration
$username = $client->getBasicAuthCredentials()->getUserName();
$password = $client->getBasicAuthCredentials()->getPassword();

// Check if client’s username and password match with the new ones
$areEqual = $client->getBasicAuthCredentials()->equals($newUser, $newPass);

Required Model Constructor Arguments​

In PHP, only required fields are a part of a model’s constructor, so models can not be initialized without setting their required parameters.

Optional and Nullable​

PHP SDKs now provide support for optional and nullable. You can get/set and unset the optional and nullable fields. The following example shows how to set/unset any field in PHP:

// Create a sample model object with its required fields
$model = new SampleModel("requiredField1", "requiredField2", "requiredField3");

$model->setAnotherField("This property is both optional and nullable");

// EITHER: Unset property will not be sent in the JSON request
$model->unsetAnotherField();

// OR: Null property will be sent as a “null” in the JSON request
$model->setAnotherField(null);

File Uploads​

Added support for sending a file as a body with the specified content type for its headers. You can send the file by wrapping it in a FileWrapper as shown:

// Wrap image file in a file wrapper
$image = FileWrapper::createFromPath("path/to/image");

// Use the client to send it as body
$client->getBinaryApi()->sendFileAsBody($image);

HttpCallback as Configuration​

With the new PHP SDKs, you can also optionally pass the HttpCallback in configurations:

// Create HttpCallback object
$httpCallback = new HttpCallback(
    function ($request) {
        // To be called before executing every request
        // User can work with $request here
    },
    function ($httpContext) {
        // To be called after executing every request
        $request = $httpContext->getRequest();
        $response = $httpContext->getResponse();
        // User can work with $request & $response here
    },

);

// Initialize the immutable client with http callback
$client = new MyClient([
    'environment' => 'production',
    'httpCallback' => $httpCallback,
]);

Improved Readme and Docs​

Updated the Authorization section and code samples in the README as well as documentation, guiding users to work with the new authorization flow.