Interfaces and Contracts
Relevant source files
The following files were used as context for generating this wiki page:
Interfaces and contracts in the Resend PHP library define the architectural boundaries between API service logic and technical implementation details. They enable the library to swap components, such as HTTP transporters, without modifying high-level service code.
These contracts ensure that every component follows a predictable structure for request handling, response parsing, and resource representation. This design facilitates testing by allowing developers to mock complex network interactions.
Transporter Interface
The Transporter contract manages the transmission of data to the Resend API. It abstracts the underlying HTTP client implementation, such as Guzzle or a custom PSR-18 client.
HttpTransporter Implementation
The HttpTransporter class implements the Transporter contract. It requires a PSR-18 ClientInterface, a BaseUri, and a Headers object to function.
- Request Execution: It takes a
Payloadobject and converts it into a PSR-7Request. - Error Handling: It parses API error responses and throws specialized exceptions like
ErrorExceptionorTransporterExceptionwhen requests fail. - Serialization: It validates the
Content-Typeheader and ensures the response body is valid JSON before returning data.
Sources: src/Contracts/Transporter.php, tests/Transporters/HttpTransporter.php:22-30, tests/Transporters/HttpTransporter.php:121-137
Transporter Component Relationship
The following diagram illustrates how the Transporter interacts with PSR standards and internal value objects.
The diagram shows the HttpTransporter implementation of the Transporter interface and its dependency on the PSR-18 client.
Request Payloads
The Payload value object acts as an intermediary between service calls and the Transporter. It encapsulates the intent of an API call, including the HTTP method, resource path, and parameters.
Payload Construction Methods
Service classes use static factory methods to create specific payload types.
| Method | HTTP Verb | Purpose |
|---|---|---|
create() | POST | Creates a new resource. |
list() | GET | Retrieves a collection of resources, supporting pagination. |
get() | GET | Retrieves a single resource by ID. |
delete() | DELETE | Removes a resource. |
upload() | POST | Sends multipart/form-data for file imports. |
replace() | PUT | Replaces existing resource data. |
Sources: tests/ValueObjects/Transporter/Payload.php:12-20, tests/ValueObjects/Transporter/Payload.php:33-41, tests/ValueObjects/Transporter/Payload.php:121-130
Client and Service Contracts
The Client contract defines the public API for the Resend library. It provides access to various service modules like Emails, Domains, and Contacts.
Service Orchestration
The main Client implementation coordinates the Transporter to fulfill service requests. For example, the Segments service uses the Transporter to send PATCH requests when updating a segment.
Sources: src/Contracts/Client.php, tests/Service/Segment.php:59-67
Request Sequence
The sequence below shows how a service call moves through the contracts to reach the network layer.
This diagram demonstrates the flow of data from a high-level service call through the payload and transporter abstractions to the low-level HTTP client.
Resource and Identity Contracts
- Resource Interface: Standardizes API entities. Every object returned by the API that represents a distinct entity (like an Email or Webhook) implements this contract.
- Stringable Interface: Allows objects to be represented as strings, typically used for IDs or names in URI construction.
Sources: src/Contracts/Resource.php, src/Contracts/Stringable.php
Summary of Error Contracts
The library maps HTTP status codes and API error bodies to specific PHP exceptions.
| Exception | Cause |
|---|---|
ErrorException | API returned a JSON error object (e.g., 422 Unprocessable Entity). |
TransporterException | Network-level failure or connection timeout. |
UnserializableResponse | API returned non-JSON data or an empty body when data was expected. |
Sources: tests/Transporters/HttpTransporter.php:84-90, tests/Transporters/HttpTransporter.php:143-156, tests/Transporters/HttpTransporter.php:198-208