Download the PHP package olivermack/duzzle without Composer

Duzzle: An opinionated, DTO-centric Guzzle HTTP Wrapper

Duzzle (_DTOs + Guzzle_) is a lightweight extension on top of Guzzle designed to seamlessly integrate DTO serialization and validation workflows into your HTTP client calls. It leverages the Symfony Serializer and (optionally) the Symfony Validator to transform your domain objects (DTOs) into request payloads, validate them before dispatch, and then deserialize responses back into strongly typed objects—enabling a clean, high-level API around Guzzle's powerful HTTP capabilities.

If you’re seeking a straightforward, “DTO-first” approach to RESTful interactions without manually handling JSON or validation rules, Duzzle aims to provide an easy and extensible solution.

Installation

Install the package via composer

Background

Duzzle was created as a proof of concept to show how/if a single API client implementation can reduce complexity in a domain application which deals with multiple different remote APIs.

Because Guzzle is a pretty well known and widely used API client in the PHP world Duzzle was built as a "wrapper" for Guzzle right from the start - hence the weird name ;).

Duzzle works with output and input definitions for any particular API call.

In order to add an extra guard for the consumption of remote APIs, Duzzle allows the validation of the input before sending it to the remote API as well as validating the output of the API to ensure that the API-consumer can deal with unexpected changes or invalid data.

Usage

First, create an instance of Duzzle via the DuzzleBuilder:

With the instance you can perform your requests. To make the usage easier Duzzle only provides a single request() method, following the signature that Guzzle's request() provides.

To access the data which was handled by Duzzle's middlewares you need to call getDuzzleResult() on the response.

DTO (De)Serialization

To deserialize the response into your domain specific DTO, you need to define the class as POPO (plain old php object) and tell the client to use it as output type:

To send an instance of a DTO to the API, you need to provide the instance as input:

Custom Serializer

The default serializer setup shipped with Duzzle is configured for the most common JSON API examples. However, if you need to use your own serializer stack you can provide it in the builder:

Validation

To use the (optional) validation capabilities you need to install the required symfony/validator package.

Now, when you create your Duzzle instance, you can ask the builder to set up the default validation behavior for you.

Validation Strategies

Duzzle works with different "Strategies" to determine how the validation result should affect the behavior of the API client.

ℹ️ Without specifying a strategy, no validation will actually happen even if you told the builder to use the default validator!

The following strategies are shipped with Duzzle:

• DefaultStrategyKey::NOOP / `noop - does not do anything with the results but enables the validation
• DefaultStrategyKey::INFORMATIVE / informative - allows you to log validation results
• DefaultStrategyKey::BLOCKING / blocking - throws an exception when the input or output payload are considered invalid

The informative strategy expects a PSR-3 logger. You need to pass one in the builder to get any effective output using $builder->withLogger($myLogger).

Validation constraints

With the default validator defined you can use PHP attributes to define your rules on the DTO class:

To validate the input, make sure your Duzzle instance is equipped with a default input_validation or define it per request like so:

For a working example check out examples/02-validation-json-api.php

Todos

• [x] dev ecosystem
• [x] lib builder / factories
• [x] most crucial code quality tooling
• [ ] DTO (de)serialization
  • [x] dealing with JSON API output
  • [x] dealing with JSON API input
  • [ ] dealing with XML API output
  • [ ] dealing with XML API input
• [x] DTO validation
  • [x] validating output DTOs
  • [x] validating input DTOs