Value Objects
Relevant source files
The following files were used as context for generating this wiki page:
Value Objects in the Resend PHP SDK provide immutable representations of data required for API communication. These objects encapsulate validation and formatting logic for API keys, URIs, and HTTP request components.
The system uses these objects to ensure data integrity before the HttpTransporter processes a request. This architecture separates the definition of a request from its execution.
Sources: src/ValueObjects/ApiKey.php, src/ValueObjects/Transporter/Payload.php
Core Identification and Addressing
The SDK uses specialized objects to handle authentication tokens and endpoint addresses. This prevents common errors like incorrect protocol prefixes or malformed path strings.
ApiKey
The ApiKey object wraps the raw string used for authentication. It implements the Stringable contract to provide a consistent string representation for headers.
Sources: src/ValueObjects/ApiKey.php:7-32
ResourceUri and BaseUri
ResourceUri manages the construction of endpoint paths. It provides static methods for common REST actions like list, get, create, update, and delete.
BaseUri normalizes the API host URL. It ensures the URI uses the HTTPS protocol by default and maintains a consistent trailing slash.
Sources: src/ValueObjects/ResourceUri.php:7-84, tests/ValueObjects/Transporter/BaseUri.php:5-23
| Method | Output Format | Purpose |
|---|---|---|
create(resource) | resource | Target for POST requests |
list(resource) | resource | Target for GET collection requests |
get(resource, id) | resource/id | Target for specific GET requests |
withAction(res, id, action) | res/id/action | Custom actions like verify or publish |
Sources: src/ValueObjects/ResourceUri.php:21-75
Request Orchestration
The SDK orchestrates HTTP requests using Headers and Payload objects. These objects prepare the metadata and body content required by the underlying HTTP client.
Headers
The Headers object maintains an array of HTTP headers. It includes specialized methods for authorization, content-type management, and idempotency.
- Authorization: Adds the
Bearerprefix to the API key. - User-Agent: Appends the SDK version and identifier.
- Idempotency: Supports
Idempotency-Keyfor safe request retries.
Sources: src/ValueObjects/Transporter/Headers.php:12-81
Payload
Payload is the primary value object for request definition. It stores the HTTP method, the ResourceUri, parameters, and specific headers.
The diagram shows how the Payload object transforms internal data into a standard PSR-7 Request.
Sources: src/ValueObjects/Transporter/Payload.php:143-184
Data Relationships
Value objects interact to form a complete request definition. The Payload object acts as the container that requires BaseUri, ResourceUri, and Headers to produce a valid request.
The class diagram illustrates the dependency flow between different value objects.
Sources: src/ValueObjects/Transporter/Payload.php:17-30, src/ValueObjects/Transporter/Headers.php:23-28
Implementation Details
Multipart Support
When the Payload uses ContentType::MULTIPART, it iterates through parameters to build a MultipartStream.
- It treats file resources as file uploads with specific filenames.
- It serializes arrays within the multipart body as JSON strings.
- It converts scalar values into strings.
- It extracts the boundary from the stream and updates the
Content-Typeheader.
Sources: src/ValueObjects/Transporter/Payload.php:154-177
URI Parameter Filtering
The Payload::list method filters query parameters. It only allows keys defined in a whitelist, such as limit, after, before, status, and origin. This prevents invalid query strings from being sent to the API.
Sources: src/ValueObjects/Transporter/Payload.php:38-48
Conclusion
Value Objects in the Resend PHP SDK formalize the structure of API requests. By encapsulating logic within Payload, Headers, and ResourceUri, the SDK ensures that all HTTP calls follow Resend's API specifications while maintaining immutability and type safety.