AsyncAws SNS Client

https://github.com/async-aws/sns
Admin
An API client for Amazon Simple Notification Service (SNS) within the AsyncAws project.
Tokens:67,953
Snippets:389
Trust Score:7.4
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### SnsClient constructor examples

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client.md

Two examples of instantiating SnsClient: one minimal with region, and one with explicit credentials and a local endpoint.

```php
<?php

use AsyncAws\Sns\SnsClient;

// Minimal client: region + default credential chain (env vars, IAM role, ...)
$client = new SnsClient(['region' => 'eu-west-1']);

// Explicit credentials + local endpoint (e.g. LocalStack, as used by the
// repository's own integration tests)
$client = new SnsClient(
    ['endpoint' => 'http://localhost:4573', 'region' => 'us-east-1'],
    new AsyncAws\Core\Credentials\Credentials('aws_id', 'aws_secret')
);
```

--------------------------------

### Example: Creating and using PublishBatchInput

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/inputs-publish.md

Demonstrates constructing a PublishBatchInput with a topic ARN and a list of PublishBatchRequestEntry objects, then calling request() to get a Request. The request() method throws InvalidArgument if required parameters are missing.

```php
<?php

use AsyncAws\Sns\Input\PublishBatchInput;
use AsyncAws\Sns\ValueObject\PublishBatchRequestEntry;

$entries = [];
foreach ($messages as $i => $message) {
    $entries[] = new PublishBatchRequestEntry([
        'Id' => "entry-$i",
        'Message' => $message,
        'MessageAttributes' => [
            'kind' => ['DataType' => 'String', 'StringValue' => 'order'], // arrays allowed
        ],
    ]);
}

$input = new PublishBatchInput([
    'TopicArn' => 'arn:aws:sns:eu-west-1:123456789012:orders',
    'PublishBatchRequestEntries' => $entries,
]);

try {
    $request = $input->request(); // pre-flight check: throws InvalidArgument if TopicArn or entries are null
} catch (AsyncAws\Core\Exception\InvalidArgument $e) {
    // Missing parameter "PublishBatchRequestEntries" for "AsyncAws\Sns\Input\PublishBatchInput". ...
}
```

--------------------------------

### SnsClient constructor examples

Source: https://github.com/async-aws/sns/blob/master/_autodocs/configuration.md

Three constructor examples: region with default credential chain, explicit credentials, and a custom endpoint for LocalStack. The LocalStack example uses endpoint 'http://localhost:4573' and region 'us-east-1'.

```php
<?php

use AsyncAws\Core\Credentials\Credentials; // from async-aws/core
use AsyncAws\Sns\SnsClient;

// Region + default credential chain (env vars, instance roles, shared file)
$client = new SnsClient(['region' => 'eu-west-1']);

// Explicit credentials
$client = new SnsClient(
    ['region' => 'eu-west-1'],
    new Credentials('AKIDEXAMPLE', 'secret')
);

// LocalStack / custom endpoint (as used by the project's own test suite)
$client = new SnsClient(
    ['endpoint' => 'http://localhost:4573', 'region' => 'us-east-1'],
    new Credentials('aws_id', 'aws_secret')
);
```

--------------------------------

### CreateTopicInput Usage Example

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/inputs.md

Example showing how to use setters on an input class to configure values and pass the input to a client method.

```APIDOC
```php
<?php

use AsyncAws\Sns\Input\CreateTopicInput;

$input = (new CreateTopicInput())
    ->setName('orders')
    ->setDataProtectionPolicy('{"Version":"2008-10-17","Statement":[]}');

$client->createTopic($input); // equivalent to passing the array directly
```
```

--------------------------------

### Install AsyncAws SNS client

Source: https://github.com/async-aws/sns/blob/master/README.md

Installs the AsyncAws SNS client via Composer. Run this command in your project root to add the dependency.

```cli
composer require async-aws/sns
```

--------------------------------

### Example: subscribe and unsubscribe with NotFoundException handling

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client-subscription-operations.md

Shows how to subscribe to an SMS topic, retrieve the subscription ARN, and then unsubscribe. The example catches `NotFoundException` for a subscription that is already deleted (e.g., concurrent unsubscribe).

```php
<?php

use AsyncAws\Sns\SnsClient;
use AsyncAws\Sns\Exception\NotFoundException;

$client = new SnsClient(['region' => 'eu-west-1']);

$subArn = $client->subscribe([
    'TopicArn' => $topicArn,
    'Protocol' => 'sms',
    'Endpoint' => '+33612345678',
    'ReturnSubscriptionArn' => true,
])->getSubscriptionArn();

try {
    $client->unsubscribe(['SubscriptionArn' => $subArn])->resolve();
} catch (NotFoundException $e) {
    // Subscription already deleted (e.g. concurrent unsubscribe)
}
```

--------------------------------

### List subscriptions by topic example

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client-subscription-operations.md

Example usage of listSubscriptionsByTopic. Creates an SnsClient with region 'eu-west-1' and iterates over all subscriptions lazily, printing protocol, subscription ARN, and endpoint for each subscription.

```php
<?php

use AsyncAws\Sns\SnsClient;

$client = new SnsClient(['region' => 'eu-west-1']);

// Iterate all pages lazily; each Subscription exposes SubscriptionArn,
// Owner, Protocol, Endpoint, TopicArn
foreach ($client->listSubscriptionsByTopic(['TopicArn' => $topicArn]) as $subscription) {
    printf("%s (%s) -> %s\n", $subscription->getProtocol(), $subscription->getSubscriptionArn(), $subscription->getEndpoint());
}
```

--------------------------------

### PublishBatch usage example

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/results.md

Example of using publishBatch and iterating over successful and failed entries. Batch failures are reported per entry and do not throw; the HTTP status can still be 200.

```php
<?php
$response = $client->publishBatch([
    'TopicArn' => $topicArn,
    'PublishBatchRequestEntries' => [
        ['Id' => '1', 'Message' => 'first'],
        ['Id' => '2', 'Message' => 'second'],
    ],
]);

foreach ($response->getSuccessful() as $ok) {
    echo $ok->getId(), ' → ', $ok->getMessageId(), "\n";
}
foreach ($response->getFailed() as $err) {
    echo $err->getId(), ' ', $err->getCode(), ': ', $err->getMessage(),
         $err->getSenderFault() ? ' (sender fault)' : '', "\n";
}
```

--------------------------------

### DeleteTopicInput Missing Parameter Example

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/inputs.md

Example demonstrating that missing required parameters are only detected when the request is built, not at construction time.

```APIDOC
```php
<?php

use AsyncAws\Core\Exception\InvalidArgument;
use AsyncAws\Sns\Input\DeleteTopicInput;

$input = new DeleteTopicInput([]); // constructs fine

try {
    $input->request(); // internally throws
} catch (InvalidArgument $e) {
    echo $e->getMessage(); // Missing parameter "TopicArn" for "AsyncAws\Sns\Input\DeleteTopicInput". The value cannot be null.
}
```
```

--------------------------------

### ListTopics pagination example

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/results-pagination.md

Example usage of ListTopicsResponse. The first loop iterates all pages with prefetching via getTopics(). The second loop demonstrates manual pagination using getTopics(currentPageOnly: true) and getNextToken().

```php
<?php

use AsyncAws\Sns\SnsClient;

$client = new SnsClient(['region' => 'eu-west-1']);

// All pages, prefetched
$arns = [];
foreach ($client->listTopics()->getTopics() as $topic) {
    $arns[] = $topic->getTopicArn();
}

// Only the first page + manual pagination
$result = $client->listTopics();
$nextToken = null;
do {
    $page = $nextToken === null
        ? $result
        : $client->listTopics(['NextToken' => $nextToken]);

    foreach ($page->getTopics(currentPageOnly: true) as $topic) {
        // ...
    }
    $nextToken = $page->getNextToken();
} while (null !== $nextToken);
```

--------------------------------

### PublishBatchInput

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/inputs-publish.md

Documentation for the PublishBatchInput class, including constructor, methods, fields, and usage example.

```APIDOC
## `PublishBatchInput`

### Description
Input for the `PublishBatch` action (up to 10 entries).

### Constructor
`__construct(array $input = [])`

### Static Factory
`create($input): self`

### Methods
- `getPublishBatchRequestEntries(): array` - Returns `PublishBatchRequestEntry[]`
- `getTopicArn(): ?string` - Returns the topic ARN
- `setPublishBatchRequestEntries(array $value): self` - Sets the entries (`PublishBatchRequestEntry[]`)
- `setTopicArn(?string $value): self` - Sets the topic ARN
- `request(): Request` - Creates the request with `Action=PublishBatch`

### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `TopicArn` | `string` | yes (cond.) | Topic ARN |
| `PublishBatchRequestEntries` | `array<PublishBatchRequestEntry\|array>` | yes (cond.) | 1–10 entries; converted via `PublishBatchRequestEntry::create()`; serialized as `PublishBatchRequestEntries.member.N.<field>` |
| `'@region'` | `string` | no | Per-request region override |

### Example

```php
<?php

use AsyncAws\Sns\Input\PublishBatchInput;
use AsyncAws\Sns\ValueObject\PublishBatchRequestEntry;

$entries = [];
foreach ($messages as $i => $message) {
    $entries[] = new PublishBatchRequestEntry([
        'Id' => "entry-$i",
        'Message' => $message,
        'MessageAttributes' => [
            'kind' => ['DataType' => 'String', 'StringValue' => 'order'], // arrays allowed
        ],
    ]);
}

$input = new PublishBatchInput([
    'TopicArn' => 'arn:aws:sns:eu-west-1:123456789012:orders',
    'PublishBatchRequestEntries' => $entries,
]);

try {
    $request = $input->request(); // pre-flight check: throws InvalidArgument if TopicArn or entries are null
} catch (AsyncAws\Core\Exception\InvalidArgument $e) {
    // Missing parameter "PublishBatchRequestEntries" for "AsyncAws\Sns\Input\PublishBatchInput". ...
}
```
```

--------------------------------

### listTopics error handling example

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client-topic-operations.md

Example of catching AuthorizationErrorException when calling listTopics with an invalid token, indicating missing sns:ListTopics permission.

```php
<?php

use AsyncAws\Sns\Exception\AuthorizationErrorException;

try {
    $client->listTopics(['NextToken' => 'invalid-token'])->resolve();
} catch (AuthorizationErrorException $e) {
    // Credentials lack sns:ListTopics permission
}
```

--------------------------------

### Creating a PublishBatchRequestEntry

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/value-objects.md

Example of instantiating PublishBatchRequestEntry with required Id and Message fields, plus optional FIFO fields MessageGroupId and MessageDeduplicationId. Note that MessageGroupId is mandatory for FIFO topics.

```php
<?php

use AsyncAws\Sns\ValueObject\PublishBatchRequestEntry;

$entry = new PublishBatchRequestEntry([
    'Id' => 'e1',
    'Message' => 'hello',
    'MessageGroupId' => 'group-a',  // FIFO topic: mandatory
    'MessageDeduplicationId' => 'dedup-42',
]);
```

--------------------------------

### deleteTopic usage example

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client-topic-operations.md

Example of calling deleteTopic with a topic ARN. It demonstrates that deleting a nonexistent topic is not an error (idempotent), and shows how to catch client exceptions for real request failures.

```php
<?php

use AsyncAws\Sns\SnsClient;

$client = new SnsClient(['region' => 'eu-west-1']);
$result = $client->deleteTopic(['TopicArn' => 'arn:aws:sns:eu-west-1:123456789012:orders']);

// Deleting a nonexistent topic is NOT an error (idempotent)
try {
    $result->resolve();
} catch (AsyncAws\Core\Exception\Http\ClientException $e) {
    // Only real request failures land here, e.g. invalid ARN → InvalidParameterException
}
```

--------------------------------

### PublishBatchRequestEntry

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/value-objects.md

Documentation for the PublishBatchRequestEntry value object, including its constructor parameters, getter methods, and a usage example.

```APIDOC
## PublishBatchRequestEntry

### Description
Represents a single message inside a `PublishBatch` request. Use this value object to define the content and attributes of one message to be published in a batch.

### Constructor
`__construct(array $input)`

### Parameters
- **Id** (string) - Required - Batch identifier; unique within the request, ≤ 80 chars (`a-zA-Z0-9`, `-`, `_`). Throws `InvalidArgument` if missing.
- **Message** (string) - Required - Message body. Throws `InvalidArgument` if missing.
- **Subject** (string|null) - Optional - Email subject line.
- **MessageStructure** (string|null) - Optional - Set to `json` for per-protocol bodies.
- **MessageAttributes** (array<string, MessageAttributeValue|array>|null) - Optional - Same shape as `MessageAttributeValue`.
- **MessageDeduplicationId** (string|null) - Optional - FIFO dedup token, ≤ 128 chars.
- **MessageGroupId** (string|null) - Optional - FIFO group tag; required for FIFO topics.

### Methods
- `create($input): self` - Static factory to create an instance.
- `getId(): string` - Returns the batch identifier.
- `getMessage(): string` - Returns the message body.
- `getSubject(): ?string` - Returns the subject line.
- `getMessageStructure(): ?string` - Returns the message structure.
- `getMessageAttributes(): array` - Returns the message attributes as an array of `MessageAttributeValue`.
- `getMessageDeduplicationId(): ?string` - Returns the deduplication ID.
- `getMessageGroupId(): ?string` - Returns the group ID.

### Example
```php
<?php

use AsyncAws\Sns\ValueObject\PublishBatchRequestEntry;

$entry = new PublishBatchRequestEntry([
    'Id' => 'e1',
    'Message' => 'hello',
    'MessageGroupId' => 'group-a',  // FIFO topic: mandatory
    'MessageDeduplicationId' => 'dedup-42',
]);
```
```

--------------------------------

### PublishBatchResponse

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/results.md

Documentation for the PublishBatchResponse result class, including its getter methods and usage example.

```APIDOC
## PublishBatchResponse

### Description
Response object for the `PublishBatch` operation. Provides access to the successful and failed entries of a batch publish request.

### Method
N/A (SDK result object)

### Endpoint
N/A (SDK result object)

### Parameters
N/A (SDK result object)

### Request Example
N/A (SDK result object)

### Response
#### Success Response (200)
- **getSuccessful()** (array of `PublishBatchResultEntry`) - Successful entries, parsed from `PublishBatchResult/Successful/member` (Id, MessageId, SequenceNumber). Empty array when absent.
- **getFailed()** (array of `BatchResultErrorEntry`) - Failed entries, parsed from `PublishBatchResult/Failed/member` (Id, Code, Message, SenderFault). Empty array when absent.

#### Response Example
```php
<?php
$response = $client->publishBatch([
    'TopicArn' => $topicArn,
    'PublishBatchRequestEntries' => [
        ['Id' => '1', 'Message' => 'first'],
        ['Id' => '2', 'Message' => 'second'],
    ],
]);

foreach ($response->getSuccessful() as $ok) {
    echo $ok->getId(), ' → ', $ok->getMessageId(), "\n";
}
foreach ($response->getFailed() as $err) {
    echo $err->getId(), ' ', $err->getCode(), ': ', $err->getMessage(),
         $err->getSenderFault() ? ' (sender fault)' : '', "\n";
}
```

### Error Handling
- Batch failures are reported per entry and **do not throw**; the HTTP status can still be 200.
- All getters trigger the first HTTP read; subsequent calls use the cached parsed fields.
- Empty arrays are returned as `[]` (e.g. no `Successful`/`Failed` members).
- Reparsing never happens: `initialize()` guards double reads.
```

--------------------------------

### Create platform endpoint and get ARN

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/results.md

Calls createPlatformEndpoint with the platform application ARN and device token, then retrieves the endpoint ARN from the returned CreateEndpointResponse. The response is lazy, so the network call is only made when getEndpointArn() is invoked.

```php
<?php
$arn = $client->createPlatformEndpoint([
    'PlatformApplicationArn' => $appArn,
    'Token' => $token,
])->getEndpointArn();
```

--------------------------------

### ListSubscriptionsByTopicResponse

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/results-pagination.md

Documentation for the ListSubscriptionsByTopicResponse result class, including its public methods and usage example.

```APIDOC
## ListSubscriptionsByTopicResponse

### Description
Response object for the `ListSubscriptionsByTopic` operation. Provides paginated access to subscriptions for a given SNS topic.

### Public Methods

#### getNextToken
- **Signature**: `getNextToken(): ?string`
- **Return**: `?string` - Pagination token, `null` on the last page.

#### getSubscriptions
- **Signature**: `getSubscriptions(bool $currentPageOnly = false): iterable`
- **Return**: `iterable<Subscription>` - Yields `Subscription` objects. Follows pages automatically by calling `$client->listSubscriptionsByTopic($input)` for the next page unless `$currentPageOnly` is `true`.

#### getIterator
- **Signature**: `getIterator(): \Traversable`
- **Return**: `\Traversable<Subscription>` - Iterates over all pages via `getSubscriptions()`.

### Example
```php
<?php

use AsyncAws\Sns\SnsClient;

$client = new SnsClient(['region' => 'eu-west-1']);

$emails = 0;
foreach ($client->listSubscriptionsByTopic(['TopicArn' => $topicArn]) as $subscription) {
    if ('email' === $subscription->getProtocol()) {
        ++$emails;
    }
    // Subscription exposes: getSubscriptionArn(), getOwner(),
    // getProtocol(), getEndpoint(), getTopicArn() — all ?string
}

// Count only the first page
$page = $client->listSubscriptionsByTopic(['TopicArn' => $topicArn]);
$firstPageCount = iterator_count($page->getSubscriptions(currentPageOnly: true));
```
```

--------------------------------

### Create topic and get ARN

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/results.md

Calls createTopic with the topic name 'orders' and retrieves the topic ARN from the returned CreateTopicResponse. The response is lazy, so the network call is only made when getTopicArn() is invoked.

```php
<?php
$topicArn = $client->createTopic(['Name' => 'orders'])->getTopicArn();
```

--------------------------------

### Iterate subscriptions with listSubscriptionsByTopic

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/results-pagination.md

Example usage of listSubscriptionsByTopic to iterate over all subscriptions and count email subscriptions. Also shows how to count only the first page using getSubscriptions(currentPageOnly: true).

```php
<?php

use AsyncAws\Sns\SnsClient;

$client = new SnsClient(['region' => 'eu-west-1']);

$emails = 0;
foreach ($client->listSubscriptionsByTopic(['TopicArn' => $topicArn]) as $subscription) {
    if ('email' === $subscription->getProtocol()) {
        ++$emails;
    }
    // Subscription exposes: getSubscriptionArn(), getOwner(),
    // getProtocol(), getEndpoint(), getTopicArn() — all ?string
}

// Count only the first page
$page = $client->listSubscriptionsByTopic(['TopicArn' => $topicArn]);
$firstPageCount = iterator_count($page->getSubscriptions(currentPageOnly: true));
```

--------------------------------

### CreateTopicInput fluent setters for createTopic

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/inputs.md

Uses fluent setters on CreateTopicInput to configure the topic name and data protection policy before calling createTopic. The approach is equivalent to passing the array directly to the client method. This example demonstrates the chaining behavior of the input setters.

```php
<?php

use AsyncAws\Sns\Input\CreateTopicInput;

$input = (new CreateTopicInput())
    ->setName('orders')
    ->setDataProtectionPolicy('{"Version":"2008-10-17","Statement":[]}');

$client->createTopic($input); // equivalent to passing the array directly
```

--------------------------------

### Subscribe to a topic and get ARN

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/results.md

Subscribes an SQS queue to an SNS topic and retrieves the subscription ARN. Setting ReturnSubscriptionArn to true ensures the ARN is returned instead of "pending confirmation".

```php
<?php
$arn = $client->subscribe([
    'TopicArn' => $topicArn,
    'Protocol' => 'sqs',
    'Endpoint' => $queueArn,
    'ReturnSubscriptionArn' => true,
])->getSubscriptionArn();
if (str_starts_with($arn, 'arn:aws:sns:')) {
    // confirmed or requested ARN
}
```

--------------------------------

### Create platform endpoint and publish

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client-platform-operations.md

Creates a platform endpoint for a device and then publishes a push notification to it. Requires the PlatformApplicationArn from CreatePlatformApplication. The returned EndpointArn is used as TargetArn in publish().

```php
<?php

use AsyncAws\Sns\SnsClient;

$client = new SnsClient(['region' => 'us-east-1']);

$result = $client->createPlatformEndpoint([
    'PlatformApplicationArn' => 'arn:aws:sns:us-east-1:123456789012:app/GCM/MyApp',
    'Token' => 'APA91b...device-registration-id',
    'CustomUserData' => 'user-42',
    'Attributes' => ['Enabled' => 'true'],
]);

$endpointArn = $result->getEndpointArn();

// The endpoint can now receive push notifications
$client->publish([
    'TargetArn' => $endpointArn,
    'Message' => '{"GCM":"{\"notification\":{\"title\":\"Hi\"}}"}',
    'MessageStructure' => 'json',
]);
```

--------------------------------

### getTopics() pagination implementation

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/results-pagination.md

Implementation of getTopics() showing pagination logic. When $currentPageOnly is false, it follows NextToken and prefetches subsequent pages via registerPrefetch. Requires the injected SnsClient and ListTopicsInput; otherwise throws AsyncAws\Core\Exception\InvalidArgument.

```php
public function getTopics(bool $currentPageOnly = false): iterable
{
    if ($currentPageOnly) {
        $this->initialize();
        yield from $this->topics;
        return;
    }

    $client = $this->awsClient;
    if (!$client instanceof SnsClient) {
        throw new InvalidArgument('missing client injected in paginated result');
    }
    if (!$this->input instanceof ListTopicsInput) {
        throw new InvalidArgument('missing last request injected in paginated result');
    }
    $input = clone $this->input;
    $page = $this;
    while (true) {
        $page->initialize();
        if (null !== $page->nextToken) {
            $input->setNextToken($page->nextToken);
            $this->registerPrefetch($nextPage = $client->listTopics($input));
        } else {
            $nextPage = null;
        }
        yield from $page->topics;
        if (null === $nextPage) {
            break;
        }
        $this->unregisterPrefetch($nextPage);
        $page = $nextPage;
    }
}
```

--------------------------------

### Handle NotFoundException for createPlatformEndpoint

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client-platform-operations.md

Shows error handling for createPlatformEndpoint when the platform application does not exist. Catches NotFoundException and comments on the cause.

```php
<?php

use AsyncAws\Sns\Exception\NotFoundException;

try {
    $client->createPlatformEndpoint([
        'PlatformApplicationArn' => 'arn:aws:sns:us-east-1:123456789012:app/GCM/MyApp',
        'Token' => $deviceToken,
    ])->getEndpointArn();
} catch (NotFoundException $e) {
    // Platform application does not exist (wrong ARN or region)
}
```

--------------------------------

### listTopics($input = [])

Source: https://github.com/async-aws/sns/blob/master/_autodocs/README.md

Lists the topics in the account.

```APIDOC
## listTopics($input = [])

### Description
Lists the topics in the account. This operation is part of the SNS client's public API.

### Method
listTopics

### Parameters
- **$input** (array|ListTopicsInput) - Optional - The input for the operation, either as an associative array or a ListTopicsInput object. Defaults to an empty array.

### Returns
- **ListTopicsResponse** - The result of the operation.
```

--------------------------------

### MessageAttributeValue

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/value-objects.md

Documentation for the MessageAttributeValue value object, including constructor parameters, methods, and usage example.

```APIDOC
## MessageAttributeValue

### Description
Represents a user-specified message attribute value for `Publish`/`PublishBatch` operations. It is a final immutable value object (DTO) constructed from an array, with per-field getters and no setters. It exposes a `requestBody()` method (marked `@internal`) to serialize into the form-encoded payload.

### Constructor
`__construct(array $input)`

### Parameters
- **DataType** (string) - Required - Logical data type: `String`, `String.Array`, `Number`, `Binary`. Throws `InvalidArgument` with message `Missing required field "DataType".` if missing.
- **StringValue** (string|null) - Optional - Unicode UTF-8 value (used for String/Number types).
- **BinaryValue** (string|null) - Optional - Binary payload; base64-encoded in `requestBody()` (`$payload['BinaryValue'] = base64_encode($v)`).

### Methods
- `create($input): self` - Normalizer: returns `$input` if it is an instance of `self`, otherwise `new self($input)`.
- `getDataType(): string` - Returns the `DataType` field.
- `getStringValue(): ?string` - Returns the `StringValue` field.
- `getBinaryValue(): ?string` - Returns the `BinaryValue` field.
- `requestBody(): array` - (internal) Serializes the object into a form-encoded payload array.

### Usage Example
```php
<?php

use AsyncAws\Sns\ValueObject\MessageAttributeValue;

$attr = new MessageAttributeValue([
    'DataType' => 'String',
    'StringValue' => '123',
]);
echo $attr->getDataType(), ' ', $attr->getStringValue(), "\n";
```
```

--------------------------------

### createTopic

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client.md

Creates a new SNS topic.

```APIDOC
## createTopic($input): CreateTopicResponse

### Description
Creates a new SNS topic. This operation is part of the SNS client's topic operations.

### Method
createTopic

### Parameters
- **$input** (array|CreateTopicInput) - Required - Input for the operation.

### Return Type
CreateTopicResponse

```

--------------------------------

### PublishInput

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/inputs-publish.md

Input for the Publish action. Provides methods to set and get message attributes, topic ARN, target ARN, phone number, and other publish parameters.

```APIDOC
## PublishInput

### Description
Input for the `Publish` action. Allows setting message content, destination (topic ARN, target ARN, or phone number), and optional attributes.

### Constructor
`__construct(array $input = [])`

### Parameters
- **TopicArn** (string|null) - Optional - Topic ARN
- **TargetArn** (string|null) - Optional - Mobile platform EndpointArn
- **PhoneNumber** (string|null) - Optional - SMS destination, E.164
- **Message** (string) - Required (conditional) - Message body; throws `Missing parameter "Message"` when null
- **Subject** (string|null) - Optional - Email subject, < 100 chars
- **MessageStructure** (string|null) - Optional - `json` for per-protocol messages
- **MessageAttributes** (array<string, MessageAttributeValue|array>|null) - Optional - Converted via `MessageAttributeValue::create()`; serialized as `MessageAttributes.entry.N.Name` and `MessageAttributes.entry.N.Value.DataType`/`.StringValue`/`.BinaryValue`
- **MessageDeduplicationId** (string|null) - Optional - FIFO dedup token, ≤ 128 chars
- **MessageGroupId** (string|null) - Optional - FIFO message group / SQS fair-queue tag
- **'@region'** (string|null) - Optional - Per-request region override

### Methods
- `create($input): self` - Static factory
- `getMessage(): ?string`
- `getMessageAttributes(): array` - Returns array<string, MessageAttributeValue>
- `getMessageDeduplicationId(): ?string`
- `getMessageGroupId(): ?string`
- `getMessageStructure(): ?string`
- `getPhoneNumber(): ?string`
- `getSubject(): ?string`
- `getTargetArn(): ?string`
- `getTopicArn(): ?string`
- `setMessage(?string $value): self`
- `setMessageAttributes(array $value): self` - Accepts array<string, MessageAttributeValue>
- `setMessageDeduplicationId(?string $value): self`
- `setMessageGroupId(?string $value): self`
- `setMessageStructure(?string $value): self`
- `setPhoneNumber(?string $value): self`
- `setSubject(?string $value): self`
- `setTargetArn(?string $value): self`
- `setTopicArn(?string $value): self`
- `request(): Request` - Returns the HTTP request for the Publish action

### Example
```php
<?php

use AsyncAws\Sns\Input\PublishInput;
use AsyncAws\Sns\SnsClient;
use AsyncAws\Sns\ValueObject\MessageAttributeValue;

$input = (new PublishInput())
    ->setTopicArn('arn:aws:sns:eu-west-1:123456789012:orders')
    ->setMessage('Order #123 shipped')
    ->setSubject('Shipping update')
    ->setMessageAttributes([
        'orderId' => new MessageAttributeValue(['DataType' => 'String', 'StringValue' => '123']),
    ]);

$client = new SnsClient(['region' => 'eu-west-1']);
$result = $client->publish($input); // PublishInput accepted directly
```
```

--------------------------------

### Create a topic with attributes and tags

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client-topic-operations.md

Creates a topic named 'orders' with attributes and tags. The result's getTopicArn() returns the ARN of the created or pre-existing topic. Tags can be provided as Tag objects or plain arrays.

```php
<?php

use AsyncAws\Sns\SnsClient;
use AsyncAws\Sns\ValueObject\Tag;

$client = new SnsClient(['region' => 'eu-west-1']);

$result = $client->createTopic([
    'Name' => 'orders',
    'Attributes' => [
        'DisplayName' => 'Order notifications',
        'KmsMasterKeyId' => 'alias/aws/sns',
    ],
    'Tags' => [
        new Tag(['Key' => 'team', 'Value' => 'checkout']),
        ['Key' => 'env', 'Value' => 'prod'], // plain array also accepted
    ],
]);

echo $result->getTopicArn();
```

--------------------------------

### CreateTopic

Source: https://github.com/async-aws/sns/blob/master/_autodocs/endpoints.md

Creates a topic to which notifications can be published.

```APIDOC
## POST /

### Description
Creates a topic to which notifications can be published. Users can create at most 100,000 topics.

### Method
POST

### Endpoint
/

### Parameters
#### Request Body
- **Name** (string) - Required - The name of the topic you want to create.
- **Attributes.entry.N.key** (string) - Optional - The key of an attribute to set on the topic.
- **Attributes.entry.N.value** (string) - Optional - The value of the attribute.
- **Tags.member.N.Key** (string) - Optional - The key of a tag to add to the topic.
- **Tags.member.N.Value** (string) - Optional - The value of the tag.
- **DataProtectionPolicy** (string) - Optional - The body of the policy document you want to use for this topic.

### Request Example
```
Action=CreateTopic&Version=2010-03-31&Name=MyTopic
```

### Response
#### Success Response (200)
- **TopicArn** (string) - The ARN of the created topic.

#### Response Example
```
<CreateTopicResponse xmlns="http://sns.amazonaws.com/doc/2010-03-31/">
  <CreateTopicResult>
    <TopicArn>arn:aws:sns:us-east-1:123456789012:MyTopic</TopicArn>
  </CreateTopicResult>
</CreateTopicResponse>
```
```

--------------------------------

### CreatePlatformEndpointInput

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/inputs.md

Documentation for the CreatePlatformEndpointInput class, which is used to create a platform endpoint for push notifications.

```APIDOC
## CreatePlatformEndpointInput

### Description
Creates an endpoint for a device and mobile app on one of the supported push notification services, such as GCM and APNS. This input object is used to configure the request.

### Method
N/A (SDK Input Class)

### Endpoint
N/A (SDK Input Class)

### Parameters
#### Constructor Parameters
- **PlatformApplicationArn** (string) - Required (conditional) - ARN from `CreatePlatformApplication`
- **Token** (string) - Required (conditional) - Device token / registration ID
- **CustomUserData** (string) - Optional - Arbitrary UTF-8 data < 2 KB
- **Attributes** (array<string, string>) - Optional - Endpoint attributes; serialized as `Attributes.entry.N.key/.value`

### Request Example
```php
$input = CreatePlatformEndpointInput::create([
    'PlatformApplicationArn' => 'arn:aws:sns:us-east-1:123456789012:app/GCM/MyApplication',
    'Token' => 'example-device-token',
    'CustomUserData' => 'user-data',
    'Attributes' => ['Enabled' => 'true'],
]);
```

### Response
#### Success Response
Returns a `Request` object with the action `CreatePlatformEndpoint`.

#### Response Example
```php
$request = $input->request();
```
```

--------------------------------

### createPlatformEndpoint

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client.md

Creates a platform endpoint for a device.

```APIDOC
## createPlatformEndpoint($input): CreateEndpointResponse

### Description
Creates an endpoint for a device on a platform application. This operation is part of the SNS client's topic and platform operations.

### Method
createPlatformEndpoint

### Parameters
- **$input** (array|CreatePlatformEndpointInput) - Required - Input for the operation.

### Return Type
CreateEndpointResponse

```

--------------------------------

### subscribe() method signature with PHPDoc

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client-subscription-operations.md

Shows the PHP signature for the subscribe method, including the input array shape, return type, and thrown exceptions.

```php
/**
 * @param array{
 *   TopicArn: string,
 *   Protocol: string,
 *   Endpoint?: string|null,
 *   Attributes?: array<string, string>|null,
 *   ReturnSubscriptionArn?: bool|null,
 *   '@region'?: string|null,
 * }|SubscribeInput $input
 *
 * @throws AuthorizationErrorException
 * @throws FilterPolicyLimitExceededException
 * @throws InternalErrorException
 * @throws InvalidParameterException
 * @throws InvalidSecurityException
 * @throws NotFoundException
 * @throws ReplayLimitExceededException
 * @throws SubscriptionLimitExceededException
 */
public function subscribe($input): SubscribeResponse
```

--------------------------------

### Per-request '@region' override example

Source: https://github.com/async-aws/sns/blob/master/_autodocs/configuration.md

Demonstrates per-request '@region' override. A single client can call operations in different regions by passing '@region' in the input array; it is consumed by the Input base constructor and passed to RequestContext.

```php
<?php

use AsyncAws\Sns\SnsClient;

$client = new SnsClient(['region' => 'eu-west-1']);

$client->createTopic(['Name' => 'orders', '@region' => 'us-east-1']);
$client->publish([
    'TopicArn' => 'arn:aws:sns:eu-west-1:123456789012:orders',
    'Message' => 'hi',
    '@region' => 'eu-west-1',
]);
```

--------------------------------

### listTopics($input = []): ListTopicsResponse

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client-topic-operations.md

Returns up to 100 topics per page, with a `NextToken` when more results exist. Throttled at 30 TPS. This is the **only** operation with a default argument — it can be called with no input at all.

```APIDOC
## listTopics($input = []): ListTopicsResponse

### Description
Returns up to 100 topics per page, with a `NextToken` when more results exist. Throttled at 30 TPS. This is the **only** operation with a default argument — it can be called with no input at all.

### Signature
```php
/**
 * @param array{
 *   NextToken?: string|null,
 *   '@region'?: string|null,
 * }|ListTopicsInput $input
 *
 * @throws AuthorizationErrorException
 * @throws InternalErrorException
 * @throws InvalidParameterException
 */
public function listTopics($input = []): ListTopicsResponse
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `NextToken` | `string` | no | `null` | Token returned by a previous `listTopics` call |
| `'@region'` | `string` | no | `null` | Per-request region override |

### Return type

`AsyncAws\Sns\Result\ListTopicsResponse` — implements `\IteratorAggregate<Topic>`; see [results-pagination.md](results-pagination.md).

| Method | Description |
|--------|-------------|
| `getTopics(bool $currentPageOnly = false): iterable<Topic>` | Yields `Topic` value objects; follows `NextToken` across pages unless `$currentPageOnly` is `true`. Requires the client+input to be injected (true for results returned by `SnsClient`). |
| `getNextToken(): ?string` | Pagination token, `null` on the last page |
| `getIterator(): \Traversable<Topic>` | Iterates over all topics (all pages) |

### Throws

`AuthorizationErrorException`, `InternalErrorException`, `InvalidParameterException`.

### Examples

```php
<?php

use AsyncAws\Sns\SnsClient;

$client = new SnsClient(['region' => 'eu-west-1']);

// Basic call — the only SnsClient method callable with no argument
$result = $client->listTopics();

// Iterate ALL pages (auto-follows NextToken, prefetches next page)
foreach ($result->getTopics() as $topic) {
    echo $topic->getTopicArn(), "\n";
}

// Or iterate only the first page manually
$result = $client->listTopics();
foreach ($result->getTopics(currentPageOnly: true) as $topic) {
    // ...
}
$next = $result->getNextToken(); // null if this was the last page
```

```php
<?php

use AsyncAws\Sns\Exception\AuthorizationErrorException;

try {
    $client->listTopics(['NextToken' => 'invalid-token'])->resolve();
} catch (AuthorizationErrorException $e) {
    // Credentials lack sns:ListTopics permission
}
```
```

--------------------------------

### createTopic($input)

Source: https://github.com/async-aws/sns/blob/master/_autodocs/README.md

Creates a topic to which notifications can be published.

```APIDOC
## createTopic($input)

### Description
Creates a topic to which notifications can be published. This operation is part of the SNS client's public API.

### Method
createTopic

### Parameters
- **$input** (array|CreateTopicInput) - Required - The input for the operation, either as an associative array or a CreateTopicInput object.

### Returns
- **CreateTopicResponse** - The result of the operation.
```

--------------------------------

### createPlatformEndpoint($input)

Source: https://github.com/async-aws/sns/blob/master/_autodocs/README.md

Creates an endpoint for a device and mobile app.

```APIDOC
## createPlatformEndpoint($input)

### Description
Creates an endpoint for a device and mobile app. This operation is part of the SNS client's public API.

### Method
createPlatformEndpoint

### Parameters
- **$input** (array|CreatePlatformEndpointInput) - Required - The input for the operation, either as an associative array or a CreatePlatformEndpointInput object.

### Returns
- **CreateEndpointResponse** - The result of the operation.
```

--------------------------------

### Lazy Result behavior with SnsClient

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client.md

Shows the lazy behavior of the Result object: the HTTP request is only sent on first access to a getter or when calling resolve(). The example creates an SnsClient, calls listTopics(), iterates over the topics, and then forces resolution and checks the 'resolved' info flag.

```php
<?php

use AsyncAws\Sns\SnsClient;

$client = new SnsClient(['region' => 'eu-west-1']);

// Nothing is sent yet: the operation returns a lazy Result
$result = $client->listTopics();

// First access performs the request
foreach ($result->getTopics() as $topicsPage) {
    // ...
}

// Or force resolution explicitly
$result->resolve();
var_dump($result->info()['resolved']); // bool(true)
```

--------------------------------

### CreateTopicInput

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/inputs.md

Documentation for the CreateTopicInput class, which is used to create an SNS topic.

```APIDOC
## CreateTopicInput

### Description
Creates a topic to which notifications can be published. This input object is used to configure the request.

### Method
N/A (SDK Input Class)

### Endpoint
N/A (SDK Input Class)

### Parameters
#### Constructor Parameters
- **Name** (string) - Required (conditional) - Topic name; `.fifo` suffix for FIFO topics
- **Attributes** (array<string, string>) - Optional - Topic attributes (see topic operations page)
- **Tags** (array<Tag|array>) - Optional - Converted via `Tag::create()`; serialized as `Tags.member.N.Key/.Value`
- **DataProtectionPolicy** (string) - Optional - JSON policy, max 30,720 chars

### Request Example
```php
$input = CreateTopicInput::create([
    'Name' => 'my-topic',
    'Attributes' => ['DisplayName' => 'My Topic'],
    'Tags' => [['Key' => 'env', 'Value' => 'prod']],
    'DataProtectionPolicy' => '{"Version":"2008-10-17"}',
]);
```

### Response
#### Success Response
Returns a `Request` object with the action `CreateTopic`.

#### Response Example
```php
$request = $input->request();
```
```

--------------------------------

### Publish to SNS topic, SMS, and FIFO with AsyncAws\Sns\SnsClient

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/sns-client-publish-operations.md

Shows three publish scenarios: to a topic with a message attribute, direct SMS via PhoneNumber, and FIFO topic requiring MessageGroupId and MessageDeduplicationId unless content-based deduplication is enabled. Uses SnsClient with region 'eu-west-1' and prints the returned message ID or sequence number.

```php
<?php

use AsyncAws\Sns\SnsClient;
use AsyncAws\Sns\ValueObject\MessageAttributeValue;

$client = new SnsClient(['region' => 'eu-west-1']);

// Publish to a topic with an attribute
$result = $client->publish([
    'TopicArn' => 'arn:aws:sns:eu-west-1:123456789012:orders',
    'Message' => 'Order #123 shipped',
    'Subject' => 'Shipping update',
    'MessageAttributes' => [
        'orderId' => new MessageAttributeValue([
            'DataType' => 'String',
            'StringValue' => '123',
        ]),
    ],
]);
echo $result->getMessageId();

// Direct SMS
$client->publish([
    'PhoneNumber' => '+33612345678',
    'Message' => 'Hello from AsyncAws',
]);

// FIFO publish must carry MessageGroupId (+ MessageDeduplicationId unless
// the topic uses content-based deduplication)
$result = $client->publish([
    'TopicArn' => 'arn:aws:sns:eu-west-1:123456789012:orders.fifo',
    'Message' => 'Order #123 shipped',
    'MessageGroupId' => 'order-123',
    'MessageDeduplicationId' => 'ship-2024-001',
]);
echo $result->getSequenceNumber();
```

--------------------------------

### PublishBatchInput class definition

Source: https://github.com/async-aws/sns/blob/master/_autodocs/api-reference/inputs-publish.md

Shows the class signature and public methods for PublishBatchInput, including constructor, create, getters, setters, and request method. The request method returns a Request object for the PublishBatch action.

```php
final class PublishBatchInput extends Input
{
    public function __construct(array $input = []);
    // @param array{
    //   TopicArn?: string,
    //   PublishBatchRequestEntries?: array<PublishBatchRequestEntry|array>,
    //   '@region'?: string|null,
    // } $input

    public static function create($input): self;

    public function getPublishBatchRequestEntries(): array;    // PublishBatchRequestEntry[]
    public function getTopicArn(): ?string;

    public function setPublishBatchRequestEntries(array $value): self; // PublishBatchRequestEntry[]
    public function setTopicArn(?string $value): self;

    public function request(): Request;                        // Action=PublishBatch
}
```

--------------------------------

### SnsClient constructor signature

Source: https://github.com/async-aws/sns/blob/master/_autodocs/configuration.md

Shows the constructor signature for SnsClient, which accepts a required configuration array and optional credential provider, HTTP client, and logger. The configuration array is interpreted by the core package.

```php
<?php

use AsyncAws\Sns\SnsClient;

$client = new SnsClient(
    array $configuration,              // required
    ?CredentialProvider $credentialProvider = null,
    ?HttpClient $httpClient = null,
    ?LoggerInterface $logger = null
);
```
Tokens:
Raw