AzureCommunicationTransport
extends ApiTransport
in package
Email transport for Azure Communication Services REST API.
Uses HMAC-SHA256 authentication derived from the connection string. The API is asynchronous (returns 202 Accepted); delivery polling is not needed since CakePHP's model is fire-and-forget.
Config keys:
- connectionString: Azure Communication Services connection string (format: endpoint=https://xxx.communication.azure.com/;accesskey=BASE64KEY)
- apiVersion: API version (default: 2023-03-31)
- timeout: HTTP timeout in seconds (default: 30)
Table of Contents
Properties
- $_defaultConfig : array<string, mixed>
- $httpClient : Client|null
- $accessKey : string|null
- Decoded access key bytes from connection string.
- $endpoint : string|null
- Parsed endpoint URL from connection string.
Methods
- send() : array<string|int, mixed>
- setHttpClient() : static
- Set a custom HTTP client (useful for testing).
- assertSuccessResponse() : void
- Assert a successful HTTP response or throw.
- buildResult() : array{headers: string, message: string}
- Build the standard return value for send().
- checkRecipient() : void
- Validate that the message has at least one recipient.
- formatAttachments() : array<int, array{name: string, contentType: string, content: string}>
- Convert Message attachments to a provider-neutral format.
- formatRecipients() : array<int, array{email: string, name: string}>
- Convert Message address array to a flat list of recipient objects.
- getHttpClient() : Client
- Get or create the HTTP client instance.
- getSender() : array{email: string, name: string}
- Get the sender address from a Message.
- buildPayload() : array<string|int, mixed>
- Build the Azure Email API request payload.
- formatAzureRecipients() : array<int, array{address: string, displayName: string}>
- Convert addresses to Azure's recipient format (address + displayName).
- parseConnectionString() : void
- Parse the Azure connection string into endpoint and access key.
- signRequest() : array<string, string>
- Generate HMAC-SHA256 authentication headers for the Azure REST API.
Properties
$_defaultConfig
protected
array<string, mixed>
$_defaultConfig
= ['connectionString' => null, 'apiVersion' => '2023-03-31', 'timeout' => 30]
$httpClient
protected
Client|null
$httpClient
= null
$accessKey
Decoded access key bytes from connection string.
private
string|null
$accessKey
= null
$endpoint
Parsed endpoint URL from connection string.
private
string|null
$endpoint
= null
Methods
send()
public
send(Message $message) : array<string|int, mixed>
Parameters
- $message : Message
Tags
Return values
array<string|int, mixed>setHttpClient()
Set a custom HTTP client (useful for testing).
public
setHttpClient(Client $client) : static
Parameters
- $client : Client
Return values
staticassertSuccessResponse()
Assert a successful HTTP response or throw.
protected
assertSuccessResponse(Response $response, string $provider, int ...$acceptedCodes) : void
Parameters
- $response : Response
-
The HTTP response.
- $provider : string
-
Provider name for error messages.
- $acceptedCodes : int
-
HTTP status codes considered successful.
Tags
buildResult()
Build the standard return value for send().
protected
buildResult(Message $message) : array{headers: string, message: string}
Parameters
- $message : Message
Return values
array{headers: string, message: string}checkRecipient()
Validate that the message has at least one recipient.
protected
checkRecipient(Message $message) : void
Parameters
- $message : Message
-
The email message.
Tags
formatAttachments()
Convert Message attachments to a provider-neutral format.
protected
formatAttachments(Message $message) : array<int, array{name: string, contentType: string, content: string}>
Parameters
- $message : Message
Return values
array<int, array{name: string, contentType: string, content: string}>formatRecipients()
Convert Message address array to a flat list of recipient objects.
protected
formatRecipients(array<string, string> $addresses) : array<int, array{email: string, name: string}>
CakePHP stores addresses as ['email@example.com' => 'Display Name'].
Parameters
- $addresses : array<string, string>
Return values
array<int, array{email: string, name: string}>getHttpClient()
Get or create the HTTP client instance.
protected
getHttpClient() : Client
Return values
ClientgetSender()
Get the sender address from a Message.
protected
getSender(Message $message) : array{email: string, name: string}
Parameters
- $message : Message
-
The email message.
Tags
Return values
array{email: string, name: string}buildPayload()
Build the Azure Email API request payload.
private
buildPayload(Message $message) : array<string|int, mixed>
Parameters
- $message : Message
Tags
Return values
array<string|int, mixed>formatAzureRecipients()
Convert addresses to Azure's recipient format (address + displayName).
private
formatAzureRecipients(array<string, string> $addresses) : array<int, array{address: string, displayName: string}>
Parameters
- $addresses : array<string, string>
-
CakePHP address map
Return values
array<int, array{address: string, displayName: string}>parseConnectionString()
Parse the Azure connection string into endpoint and access key.
private
parseConnectionString() : void
Tags
signRequest()
Generate HMAC-SHA256 authentication headers for the Azure REST API.
private
signRequest(string $method, string $pathAndQuery, string $body) : array<string, string>
Parameters
- $method : string
-
HTTP method (POST, GET, etc.)
- $pathAndQuery : string
-
URL path + query string
- $body : string
-
Request body
Tags
Return values
array<string, string> —Headers to include in the request