',
'Time' => time()
],
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Using alarm actions with Amazon CloudWatch alarms with AWS SDK for PHP Version 3
Use alarm actions to create alarms that automatically stop, terminate, reboot, or recover your Amazon EC2 instances. You can use the stop or terminate actions when you no longer need an instance to be running. You can use the reboot and recover actions to automatically reboot those instances.
The following examples show how to:
+ Enable actions for specified alarms using [EnableAlarmActions](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-monitoring-2010-08-01.html#enablealarmactions).
+ Disable actions for specified alarms using [DisableAlarmActions](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-monitoring-2010-08-01.html#disablealarmactions).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Enable alarm actions
**Imports**
```
require 'vendor/autoload.php';
use Aws\CloudWatch\CloudWatchClient;
use Aws\Exception\AwsException;
```
**Sample Code**
```
function enableAlarmActions($cloudWatchClient, $alarmNames)
{
try {
$result = $cloudWatchClient->enableAlarmActions([
'AlarmNames' => $alarmNames
]);
if (isset($result['@metadata']['effectiveUri'])) {
return 'At the effective URI of ' .
$result['@metadata']['effectiveUri'] .
', actions for any matching alarms have been enabled.';
} else {
return'Actions for some matching alarms ' .
'might not have been enabled.';
}
} catch (AwsException $e) {
return 'Error: ' . $e->getAwsErrorMessage();
}
}
function enableTheAlarmActions()
{
$alarmNames = array('my-alarm');
$cloudWatchClient = new CloudWatchClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-08-01'
]);
echo enableAlarmActions($cloudWatchClient, $alarmNames);
}
// Uncomment the following line to run this code in an AWS account.
// enableTheAlarmActions();
```
## Disable alarm actions
**Imports**
```
require 'vendor/autoload.php';
use Aws\CloudWatch\CloudWatchClient;
use Aws\Exception\AwsException;
```
**Sample Code**
```
function disableAlarmActions($cloudWatchClient, $alarmNames)
{
try {
$result = $cloudWatchClient->disableAlarmActions([
'AlarmNames' => $alarmNames
]);
if (isset($result['@metadata']['effectiveUri'])) {
return 'At the effective URI of ' .
$result['@metadata']['effectiveUri'] .
', actions for any matching alarms have been disabled.';
} else {
return 'Actions for some matching alarms ' .
'might not have been disabled.';
}
} catch (AwsException $e) {
return 'Error: ' . $e->getAwsErrorMessage();
}
}
function disableTheAlarmActions()
{
$alarmNames = array('my-alarm');
$cloudWatchClient = new CloudWatchClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-08-01'
]);
echo disableAlarmActions($cloudWatchClient, $alarmNames);
}
// Uncomment the following line to run this code in an AWS account.
// disableTheAlarmActions();
```
# Amazon EC2 examples using the AWS SDK for PHP Version 3
Amazon Elastic Compute Cloud (Amazon EC2) is a web service that provides virtual server hosting in the cloud. It’s designed to make web-scale cloud computing easier for developers by providing resizeable compute capacity.
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
**Topics**
+ [Credentials](#examplecredentials)
+ [Managing Amazon EC2 instances](ec2-examples-managing-instances.md)
+ [Using Elastic IP addresses](ec2-examples-using-elastic-ip-addresses.md)
+ [Using regions and availability zones](ec2-examples-using-regions-and-zones.md)
+ [Working with key pairs](ec2-examples-working-with-key-pairs.md)
+ [Working with security groups](ec2-examples-using-security-groups.md)
# Managing Amazon EC2 instances using the AWS SDK for PHP Version 3
The following examples show how to:
+ Describe Amazon EC2 instances using [DescribeInstances](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#describeinstances).
+ Enable detailed monitoring for a running instance using [MonitorInstances](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#monitorinstances).
+ Disable monitoring for a running instance using [UnmonitorInstances](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#unmonitorinstances).
+ Start an Amazon EBS-backed AMI that you’ve previously stopped, using [StartInstances](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#startinstances).
+ Stop an Amazon EBS-backed instance using [StopInstances](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#stopinstances).
+ Request a reboot of one or more instances using [RebootInstances](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#rebootinstances).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Describe instances
**Imports**
```
require 'vendor/autoload.php';
use Aws\Ec2\Ec2Client;
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$result = $ec2Client->describeInstances();
echo "Instances: \n";
foreach ($result['Reservations'] as $reservation) {
foreach ($reservation['Instances'] as $instance) {
echo "InstanceId: {$instance['InstanceId']} - {$instance['State']['Name']} \n";
}
}
```
## Enable and disable monitoring
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$instanceIds = ['InstanceID1', 'InstanceID2'];
$monitorInstance = 'ON';
if ($monitorInstance == 'ON') {
$result = $ec2Client->monitorInstances([
'InstanceIds' => $instanceIds
]);
} else {
$result = $ec2Client->unmonitorInstances([
'InstanceIds' => $instanceIds
]);
}
var_dump($result);
```
## Start and stop an instance
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$action = 'START';
$instanceIds = ['InstanceID1', 'InstanceID2'];
if ($action == 'START') {
$result = $ec2Client->startInstances([
'InstanceIds' => $instanceIds,
]);
} else {
$result = $ec2Client->stopInstances([
'InstanceIds' => $instanceIds,
]);
}
var_dump($result);
```
## Reboot an instance
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$instanceIds = ['InstanceID1', 'InstanceID2'];
$result = $ec2Client->rebootInstances([
'InstanceIds' => $instanceIds
]);
var_dump($result);
```
# Using Elastic IP addresses with Amazon EC2 with AWS SDK for PHP Version 3
An Elastic IP address is a static IP address designed for dynamic cloud computing. An Elastic IP address is associated with your AWS account. It’s a public IP address, which is reachable from the internet. If your instance does not have a public IP address, you can associate an Elastic IP address with your instance to enable communication with the internet.
The following examples show how to:
+ Describe one or more of your instances using [DescribeInstances](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#describeinstances).
+ Acquire an Elastic IP address using [AllocateAddress](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#allocateaddress).
+ Associate an Elastic IP address with an instance using [AssociateAddress](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#associateaddress).
+ Release an Elastic IP address using [ReleaseAddress](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#releaseaddress).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Describe an instance
**Imports**
```
require 'vendor/autoload.php';
use Aws\Ec2\Ec2Client;
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$result = $ec2Client->describeInstances();
echo "Instances: \n";
foreach ($result['Reservations'] as $reservation) {
foreach ($reservation['Instances'] as $instance) {
echo "InstanceId: {$instance['InstanceId']} - {$instance['State']['Name']} \n";
}
}
```
## Allocate and associate an address
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$instanceId = 'InstanceID';
$allocation = $ec2Client->allocateAddress(array(
'DryRun' => false,
'Domain' => 'vpc',
));
$result = $ec2Client->associateAddress(array(
'DryRun' => false,
'InstanceId' => $instanceId,
'AllocationId' => $allocation->get('AllocationId')
));
var_dump($result);
```
## Release an address
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$associationID = 'AssociationID';
$allocationID = 'AllocationID';
$result = $ec2Client->disassociateAddress([
'AssociationId' => $associationID,
]);
$result = $ec2Client->releaseAddress([
'AllocationId' => $allocationID,
]);
var_dump($result);
```
# Using regions and availability zones for Amazon EC2 with AWS SDK for PHP Version 3
Amazon EC2 is hosted in multiple locations worldwide. These locations are composed of AWS Regions and Availability Zones. Each Region is a separate geographic area, with multiple isolated locations known as Availability Zones. Amazon EC2 provides the ability to place instances and data in multiple locations.
The following examples show how to:
+ Describe the Availability Zones that are available to you using [DescribeAvailabilityZones](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#describeavailabilityzones).
+ Describe AWS Regions that are currently available to you using [DescribeRegions](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#describeregions).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Describe availability zones
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$result = $ec2Client->describeAvailabilityZones();
var_dump($result);
```
## Describe regions
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$result = $ec2Client->describeRegions();
var_dump($result);
```
# Working with Amazon EC2 key pairs with AWS SDK for PHP Version 3
Amazon EC2 uses public–key cryptography to encrypt and decrypt login information. Public–key cryptography uses a public key to encrypt data. Then the recipient uses the private key to decrypt the data. The public and private keys are known as a key pair.
The following examples show how to:
+ Create a 2048-bit RSA key pair using [CreateKeyPair](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#createkeypair).
+ Delete a specified key pair using [DeleteKeyPair](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#deletekeypair).
+ Describe one or more of your key pairs using [DescribeKeyPairs](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#describekeypairs).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Create a key pair
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$keyPairName = 'my-keypair';
$result = $ec2Client->createKeyPair(array(
'KeyName' => $keyPairName
));
// Save the private key
$saveKeyLocation = getenv('HOME') . "/.ssh/{$keyPairName}.pem";
file_put_contents($saveKeyLocation, $result['keyMaterial']);
// Update the key's permissions so it can be used with SSH
chmod($saveKeyLocation, 0600);
```
## Delete a key pair
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$keyPairName = 'my-keypair';
$result = $ec2Client->deleteKeyPair(array(
'KeyName' => $keyPairName
));
var_dump($result);
```
## Describe key pairs
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$result = $ec2Client->describeKeyPairs();
var_dump($result);
```
# Working with security groups in Amazon EC2 with AWS SDK for PHP Version 3
An Amazon EC2 security group acts as a virtual firewall that controls the traffic for one or more instances. You add rules to each security group to allow traffic to or from its associated instances. You can modify the rules for a security group at any time. The new rules are automatically applied to all instances that are associated with the security group.
The following examples show how to:
+ Describe one or more of your security groups using [DescribeSecurityGroups](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#describesecuritygroups).
+ Add an ingress rule to a security group using [AuthorizeSecurityGroupIngress](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#authorizesecuritygroupingress).
+ Create a security group using [CreateSecurityGroup](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#createsecuritygroup).
+ Delete a security group using [DeleteSecurityGroup](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-ec2-2016-11-15.html#deletesecuritygroup).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Describe security groups
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$result = $ec2Client->describeSecurityGroups();
var_dump($result);
```
## Add an ingress rule
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$result = $ec2Client->authorizeSecurityGroupIngress(array(
'GroupName' => 'string',
'SourceSecurityGroupName' => 'string'
));
var_dump($result);
```
## Create a security group
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
// Create the security group
$securityGroupName = 'my-security-group';
$result = $ec2Client->createSecurityGroup(array(
'GroupId' => $securityGroupName,
));
// Get the security group ID (optional)
$securityGroupId = $result->get('GroupId');
echo "Security Group ID: " . $securityGroupId . '\n';
```
## Delete a security group
**Imports**
```
require 'vendor/autoload.php';
```
**Sample Code**
```
$ec2Client = new Aws\Ec2\Ec2Client([
'region' => 'us-west-2',
'version' => '2016-11-15',
'profile' => 'default'
]);
$securityGroupId = 'my-security-group-id';
$result = $ec2Client->deleteSecurityGroup([
'GroupId' => $securityGroupId
]);
var_dump($result);
```
# Signing an Amazon OpenSearch Service search request with AWS SDK for PHP Version 3
Amazon OpenSearch Service is a managed service that makes it easy to deploy, operate, and scale Amazon OpenSearch Service, a popular open-source search, and analytics engine. OpenSearch Service offers direct access to the Amazon OpenSearch Service API. This means that developers can use the tools with which they’re familiar, as well as robust security options. Many Amazon OpenSearch Service clients support request signing, but if you’re using a client that doesn’t, you can sign arbitrary PSR-7 requests with the built-in credential providers and signers of the AWS SDK for PHP.
The following examples show how to:
+ Sign a request with the AWS signing protocol using [SignatureV4](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.Signature.SignatureV4.html#_signRequest).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Signing an OpenSearch Service request
OpenSearch Service uses [Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). This means that you need to sign requests against the service’s signing name (`es`, in this case) and the AWS Region of your OpenSearch Service domain. A full list of Regions supported by OpenSearch Service can be found [ on the AWS Regions and Endpoints page](https://docs.aws.amazon.com/general/latest/gr/rande.html) in the Amazon Web Services General Reference. However, in this example, we sign requests against an OpenSearch Service domain in the `us-west-2` region.
You need to provide credentials, which you can do either with the SDK’s default provider chain or with any form of credentials described in [Credentials for the AWS SDK for PHP Version 3](guide_credentials.md). You’ll also need a [PSR-7 request](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Psr.Http.Message.RequestInterface.html) (assumed in the code below to be named `$psr7Request`).
```
// Pull credentials from the default provider chain
$provider = Aws\Credentials\CredentialProvider::defaultProvider();
$credentials = call_user_func($provider)->wait();
// Create a signer with the service's signing name and Region
$signer = new Aws\Signature\SignatureV4('es', 'us-west-2');
// Sign your request
$signedRequest = $signer->signRequest($psr7Request, $credentials);
```
# AWS Identity and Access Management examples using the AWS SDK for PHP Version 3
AWS Identity and Access Management (IAM) is a web service that enables Amazon Web Services customers to manage users and user permissions in AWS. The service is targeted at organizations with multiple users or systems in the cloud that use AWS products. With IAM, you can centrally manage users, security credentials such as access keys, and permissions that control which AWS resources users can access.
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
**Topics**
+ [Credentials](#examplecredentials)
+ [Managing IAM access keys](iam-examples-managing-access-keys.md)
+ [Managing IAM users](iam-examples-managing-users.md)
+ [Using IAM account aliases](iam-examples-using-account-aliases.md)
+ [Working with IAM policies](iam-examples-working-with-policies.md)
+ [Working with IAM server certificates](iam-examples-working-with-certs.md)
# Managing IAM access keys with AWS SDK for PHP Version 3
Users need their own access keys to make programmatic calls to AWS. To fill this need, you can create, modify, view, or rotate access keys (access key IDs and secret access keys) for IAM users. By default, when you create an access key, its status is Active. This means the user can use the access key for API calls.
The following examples show how to:
+ Create a secret access key and corresponding access key ID using [CreateAccessKey](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#createaccesskey).
+ Return information about the access key IDs associated with an IAM user using [ListAccessKeys](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#listaccesskeys).
+ Retrieve information about when an access key was last used using [GetAccessKeyLastUsed](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#getaccesskeylastused).
+ Change the status of an access key from Active to Inactive, or vice versa, using [UpdateAccessKey](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#updateaccesskey).
+ Delete an access key pair associated with an IAM user using [DeleteAccessKey](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#deleteaccesskey).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Create an access key
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->createAccessKey([
'UserName' => 'IAM_USER_NAME',
]);
$keyID = $result['AccessKey']['AccessKeyId'];
$createDate = $result['AccessKey']['CreateDate'];
$userName = $result['AccessKey']['UserName'];
$status = $result['AccessKey']['Status'];
// $secretKey = $result['AccessKey']['SecretAccessKey']
echo "AccessKey " . $keyID . " created on " . $createDate . "
";
echo "Username: " . $userName . "
";
echo "Status: " . $status . "
";
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## List access keys
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->listAccessKeys();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Get information about an access key’s last use
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->getAccessKeyLastUsed([
'AccessKeyId' => 'ACCESS_KEY_ID', // REQUIRED
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Update an access key
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->updateAccessKey([
'AccessKeyId' => 'ACCESS_KEY_ID', // REQUIRED
'Status' => 'Inactive', // REQUIRED
'UserName' => 'IAM_USER_NAME',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Delete an access key
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->deleteAccessKey([
'AccessKeyId' => 'ACCESS_KEY_ID', // REQUIRED
'UserName' => 'IAM_USER_NAME',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Managing IAM users with AWS SDK for PHP Version 3
An IAM user is an entity that you create in AWS to represent the person or service that uses it to interact with AWS. A user in AWS consists of a name and credentials.
The following examples show how to:
+ Create a new IAM user using [CreateUser](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#createuser).
+ List IAM users using [ListUsers](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#listusers).
+ Update an IAM user using [UpdateUser](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#updateuser).
+ Retrieve information about an IAM user using [GetUser](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#getuser).
+ Delete an IAM user using [DeleteUser](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#deleteuser).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Create an IAM user
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->createUser(array(
// UserName is required
'UserName' => 'string',
));
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## List IAM users
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->listUsers();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Update an IAM user
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->updateUser([
// UserName is required
'UserName' => 'string1',
'NewUserName' => 'string'
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Get information about an IAM user
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->getUser([
'UserName' => 'string',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Delete an IAM user
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->deleteUser([
// UserName is required
'UserName' => 'string'
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Using IAM account aliases with AWS SDK for PHP Version 3
If you want the URL for your sign-in page to contain your company name or other friendly identifier instead of your AWS account ID, you can create an alias for your AWS account ID. If you create an AWS account alias, your sign-in page URL changes to incorporate the alias.
The following examples show how to:
+ Create an alias using [CreateAccountAlias](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#createaccountalias).
+ List the alias associated with the AWS account using [ListAccountAliases](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#listaccountaliases).
+ Delete an alias using [DeleteAccountAlias](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#deleteaccountalias).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Create an alias
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->createAccountAlias(array(
// AccountAlias is required
'AccountAlias' => 'string',
));
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## List account aliases
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->listAccountAliases();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Delete an alias
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->deleteAccountAlias([
// AccountAlias is required
'AccountAlias' => 'string',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Working with IAM policies with AWS SDK for PHP Version 3
You grant permissions to a user by creating a policy. A policy is a document that lists the actions that a user can perform and the resources those actions can affect. By default, any actions or resources that are not explicitly allowed are denied. Policies can be created and attached to users, groups of users, roles assumed by users, and resources.
The following examples show how to:
+ Create a managed policy using [CreatePolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#createpolicy).
+ Attach a policy to a role using [AttachRolePolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#attachrolepolicy).
+ Attach a policy to a user using [AttachUserPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#attachuserpolicy).
+ Attach a policy to a group using [AttachGroupPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#attachgrouppolicy).
+ Remove a role policy using [DetachRolePolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#detachrolepolicy).
+ Remove a user policy using [DetachUserPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#detachuserpolicy).
+ Remove a group policy using [DetachGroupPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#detachgrouppolicy).
+ Delete a managed policy using [DeletePolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#deletepolicy).
+ Delete a role policy using [DeleteRolePolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#deleterolepolicy).
+ Delete a user policy using [DeleteUserPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#deleteuserpolicy).
+ Delete a group policy using [DeleteGroupPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#deletegrouppolicy).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Create a policy
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
$myManagedPolicy = '{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:CreateLogGroup",
"Resource": "RESOURCE_ARN"
},
{
"Effect": "Allow",
"Action": [
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:PutItem",
"dynamodb:Scan",
"dynamodb:UpdateItem"
],
"Resource": "RESOURCE_ARN"
}
]
}';
try {
$result = $client->createPolicy(array(
// PolicyName is required
'PolicyName' => 'myDynamoDBPolicy',
// PolicyDocument is required
'PolicyDocument' => $myManagedPolicy
));
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Attach a policy to a role
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
$roleName = 'ROLE_NAME';
$policyName = 'AmazonDynamoDBFullAccess';
$policyArn = 'arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess';
try {
$attachedRolePolicies = $client->getIterator('ListAttachedRolePolicies', ([
'RoleName' => $roleName,
]));
if (count($attachedRolePolicies) > 0) {
foreach ($attachedRolePolicies as $attachedRolePolicy) {
if ($attachedRolePolicy['PolicyName'] == $policyName) {
echo $policyName . " is already attached to this role. \n";
exit();
}
}
}
$result = $client->attachRolePolicy(array(
// RoleName is required
'RoleName' => $roleName,
// PolicyArn is required
'PolicyArn' => $policyArn
));
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Attach a policy to a user
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
$userName = 'USER_NAME';
$policyName = 'AmazonDynamoDBFullAccess';
$policyArn = 'arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess';
try {
$attachedUserPolicies = $client->getIterator('ListAttachedUserPolicies', ([
'UserName' => $userName,
]));
if (count($attachedUserPolicies) > 0) {
foreach ($attachedUserPolicies as $attachedUserPolicy) {
if ($attachedUserPolicy['PolicyName'] == $policyName) {
echo $policyName . " is already attached to this role. \n";
exit();
}
}
}
$result = $client->attachUserPolicy(array(
// UserName is required
'UserName' => $userName,
// PolicyArn is required
'PolicyArn' => $policyArn,
));
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Attach a policy to a group
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->attachGroupPolicy(array(
// GroupName is required
'GroupName' => 'string',
// PolicyArn is required
'PolicyArn' => 'string',
));
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Detach a user policy
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->detachUserPolicy([
// UserName is required
'UserName' => 'string',
// PolicyArn is required
'PolicyArn' => 'string',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Detach a group policy
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->detachGroupPolicy([
// GroupName is required
'GroupName' => 'string',
// PolicyArn is required
'PolicyArn' => 'string',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Delete a policy
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->deletePolicy(array(
// PolicyArn is required
'PolicyArn' => 'string'
));
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Delete a role policy
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->deleteRolePolicy([
// RoleName is required
'RoleName' => 'string',
// PolicyName is required
'PolicyName' => 'string'
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Delete a user policy
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->deleteUserPolicy([
// UserName is required
'UserName' => 'string',
// PolicyName is required
'PolicyName' => 'string',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Delete a group policy
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->deleteGroupPolicy(array(
// GroupName is required
'GroupName' => 'string',
// PolicyName is required
'PolicyName' => 'string',
));
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Working with IAM server certificates with AWS SDK for PHP Version 3
To enable HTTPS connections to your website or application on AWS, you need an SSL/TLS server certificate. To use a certificate that you obtained from an external provider with your website or application on AWS, you must upload the certificate to IAM or import it into AWS Certificate Manager.
The following examples show how to:
+ List the certificates stored in IAM using [ListServerCertificates](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#listservercertificates).
+ Retrieve information about a certificate using [GetServerCertificate](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#getservercertificate).
+ Update a certificate using [UpdateServerCertificate](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#updateservercertificate).
+ Delete a certificate using [DeleteServerCertificate](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-iam-2010-05-08.html#deleteservercertificate).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## List server certificates
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->listServerCertificates();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Retrieve a server certificate
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->getServerCertificate([
// ServerCertificateName is required
'ServerCertificateName' => 'string',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Update a server certificate
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->updateServerCertificate([
// ServerCertificateName is required
'ServerCertificateName' => 'string',
'NewServerCertificateName' => 'string',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Delete a server certificate
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Iam\IamClient;
```
**Sample Code**
```
$client = new IamClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2010-05-08'
]);
try {
$result = $client->deleteServerCertificate([
// ServerCertificateName is required
'ServerCertificateName' => 'string',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# AWS Key Management Service examples using the AWS SDK for PHP Version 3
AWS Key Management Service (AWS KMS) is a managed service that makes it easy for you to create and control the encryption keys used to encrypt your data. For more information about AWS KMS, see the [Amazon KMS documentation](https://aws.amazon.com/documentation/kms/). Whether you are writing secure PHP applications or sending data to other AWS services, AWS KMS helps you maintain control over who can use your keys and gain access to your encrypted data.
All the example code for the AWS SDK for PHP Version 3 is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
**Topics**
+ [Working with keys](kms-example-keys.md)
+ [Encrypting and decrypting data keys](kms-example-encrypt.md)
+ [Working with key policies](kms-example-key-policy.md)
+ [Working with grants](kms-example-grants.md)
+ [Working with aliases](kms-example-alias.md)
# Working with keys using the AWS KMS API and the AWS SDK for PHP Version 3
The primary resources in AWS Key Management Service (AWS KMS) are [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys). You can use a KMS key to encrypt your data.
The following examples show how to:
+ Create a customer KMS key using [CreateKey](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#createkey).
+ Generate a data key using [GenerateDataKey](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#generatedatakey).
+ View a KMS key using [DescribeKey](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#describekey).
+ Get key IDs and key ARNS of KMS keys using [ListKeys](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#listkeys).
+ Enable KMS keys using [EnableKey](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#enablekey).
+ Disable KMS keys using [DisableKey](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#disablekey).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using AWS Key Management Service (AWS KMS), see the [AWS KMS Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/).
## Create a KMS key
To create a [KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys), use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
//Creates a customer master key (CMK) in the caller's AWS account.
$desc = "Key for protecting critical data";
try {
$result = $KmsClient->createKey([
'Description' => $desc,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Generate a data key
To generate a data encryption key, use the [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) operation. This operation returns plaintext and encrypted copies of the data key that it creates. Specify the AWS KMS key under which to generate the data key.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$keySpec = 'AES_256';
try {
$result = $KmsClient->generateDataKey([
'KeyId' => $keyId,
'KeySpec' => $keySpec,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## View a KMS key
To get detailed information about a KMS key, including the KMS key’s Amazon Resource Name (ARN) and [key state](https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html), use the [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operation.
`DescribeKey` doesn’t get aliases. To get aliases, use the [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeys.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
try {
$result = $KmsClient->describeKey([
'KeyId' => $keyId,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Get the key ID and key ARNs of a KMS key
To get the ID and ARN of the KMS key, use the [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeys.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$limit = 10;
try {
$result = $KmsClient->listKeys([
'Limit' => $limit,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Enable a KMS key
To enable a disabled KMS key, use the [EnableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_EnableKey.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
try {
$result = $KmsClient->enableKey([
'KeyId' => $keyId,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Disable a KMS key
To disable a KMS key, use the [DisableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKey.html) operation. Disabling a KMS key prevents it from being used.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
try {
$result = $KmsClient->disableKey([
'KeyId' => $keyId,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Encrypting and decrypting AWS KMS data keys using the AWS SDK for PHP Version 3
Data keys are encryption keys that you can use to encrypt data, including large amounts of data and other data encryption keys.
You can use an AWS Key Management Service's (AWS KMS) [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys) to generate, encrypt, and decrypt data keys.
The following examples show how to:
+ Encrypt a data key using [Encrypt](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#encrypt).
+ Decrypt a data key using [Decrypt](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#decrypt).
+ Re-encrypt a data key with a new KMS key using [ReEncrypt](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#reencrypt).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using AWS Key Management Service (AWS KMS), see the [AWS KMS Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/).
## Encrypt
The [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) operation is designed to encrypt data keys, but it’s not frequently used. The [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) and [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) operations return encrypted data keys. You might use the `Encypt` method when you’re moving encrypted data to a new AWS Region and want to encrypt its data key by using a KMS key in the new Region.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$message = pack('c*', 1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
try {
$result = $KmsClient->encrypt([
'KeyId' => $keyId,
'Plaintext' => $message,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Decrypt
To decrypt a data key, use the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation.
The `ciphertextBlob` that you specify must be the value of the `CiphertextBlob` field from a [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html), or [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) response.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$ciphertext = 'Place your cipher text blob here';
try {
$result = $KmsClient->decrypt([
'CiphertextBlob' => $ciphertext,
]);
$plaintext = $result['Plaintext'];
var_dump($plaintext);
} catch (AwsException $e) {
// Output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Reencrypt
To decrypt an encrypted data key, and then immediately reencrypt the data key under a different KMS key, use the [ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) operation. The operations are performed entirely on the server side within AWS KMS, so they never expose your plaintext outside of AWS KMS.
The `ciphertextBlob` that you specify must be the value of the `CiphertextBlob` field from a [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html), or [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) response.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$ciphertextBlob = 'Place your cipher text blob here';
try {
$result = $KmsClient->reEncrypt([
'CiphertextBlob' => $ciphertextBlob,
'DestinationKeyId' => $keyId,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Working with AWS KMS key policies using the AWS SDK for PHP Version 3
When you create an [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys), you determine who can use and manage that KMS key. These permissions are contained in a document called the key policy. You can use the key policy to add, remove, or modify permissions at any time for a customer managed KMS key, but you cannot edit the key policy for an AWS managed KMS key. For more information, see [Authentication and access control for AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html).
The following examples show how to:
+ List the names of key policies using [ListKeyPolicies](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#listkeypolicies).
+ Get a key policy using [GetKeyPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#getkeypolicy).
+ Set a key policy using [PutKeyPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#putkeypolicy).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using AWS Key Management Service (AWS KMS), see the [AWS KMS Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/).
## List all key policies
To get the names of key policies for a KMS key, use the `ListKeyPolicies` operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$limit = 10;
try {
$result = $KmsClient->listKeyPolicies([
'KeyId' => $keyId,
'Limit' => $limit,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Retrieve a key policy
To get the key policy for a KMS key, use the `GetKeyPolicy` operation.
`GetKeyPolicy` requires a policy name. Unless you created a key policy when you created the KMS key, the only valid policy name is the default. Learn more about the [Default key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html) in the *AWS Key Management Service Developer Guide*.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$policyName = "default";
try {
$result = $KmsClient->getKeyPolicy([
'KeyId' => $keyId,
'PolicyName' => $policyName
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Set a key policy
To establish or change a key policy for a KMS key, use the `PutKeyPolicy` operation.
`PutKeyPolicy` requires a policy name. Unless you created a Key Policy when you created the KMS key, the only valid policy name is the default. Learn more about the [Default key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html) in the *AWS Key Management Service Developer Guide*.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$policyName = "default";
try {
$result = $KmsClient->putKeyPolicy([
'KeyId' => $keyId,
'PolicyName' => $policyName,
'Policy' => '{
"Version":"2012-10-17",
"Id": "custom-policy-2016-12-07",
"Statement": [
{ "Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal":
{ "AWS": "arn:aws:iam::111122223333:user/root" },
"Action": [ "kms:*" ],
"Resource": "*" },
{ "Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal":
{ "AWS": "arn:aws:iam::111122223333:user/ExampleUser" },
"Action": [
"kms:Encrypt*",
"kms:GenerateDataKey*",
"kms:Decrypt*",
"kms:DescribeKey*",
"kms:ReEncrypt*"
],
"Resource": "*" }
]
} '
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Working with grants using the AWS KMS API and the AWS SDK for PHP version 3
A grant is another mechanism for providing permissions. It is an alternative to the key policy. You can use grants to give long-term access that allows AWS principals to use your AWS Key Management Service (AWS KMS) customer-managed [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys). For more information, see [Grants in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in the *AWS Key Management Service Developer Guide*.
The following examples show how to:
+ Create a grant for a KMS key using [CreateGrant](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#creategrant).
+ View a grant for a KMS key using [ListGrants](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#listgrants).
+ Retire a grant for a KMS key using [RetireGrant](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#retiregrant).
+ Revoke a grant for a KMS key using [RevokeGrant](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#revokegrant).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using AWS Key Management Service (AWS KMS), see the [AWS KMS Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/).
## Create a grant
To create a grant for an AWS KMS key, use the [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$granteePrincipal = "arn:aws:iam::111122223333:user/Alice";
$operation = ['Encrypt', 'Decrypt']; // A list of operations that the grant allows.
try {
$result = $KmsClient->createGrant([
'GranteePrincipal' => $granteePrincipal,
'KeyId' => $keyId,
'Operations' => $operation
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## View a grant
To get detailed information about the grants on an AWS KMS key, use the [ListGrants](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$limit = 10;
try {
$result = $KmsClient->listGrants([
'KeyId' => $keyId,
'Limit' => $limit,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Retire a grant
To retire a grant for an AWS KMS key, use the [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) operation. Retire a grant to clean up after you finish using it.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$grantToken = 'Place your grant token here';
try {
$result = $KmsClient->retireGrant([
'GrantToken' => $grantToken,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
//Can also identify grant to retire by a combination of the grant ID
//and the Amazon Resource Name (ARN) of the customer master key (CMK)
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$grantId = 'Unique identifier of the grant returned during CreateGrant operation';
try {
$result = $KmsClient->retireGrant([
'GrantId' => $grantToken,
'KeyId' => $keyId,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Revoke a grant
To revoke a grant to an AWS KMS key, use the [RevokeGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RevokeGrant.html) operation. You can revoke a grant to explicitly deny operations that depend on it.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$grantId = "grant1";
try {
$result = $KmsClient->revokeGrant([
'KeyId' => $keyId,
'GrantId' => $grantId,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Working with aliases using the AWS KMS API and the AWS SDK for PHP Version 3
AWS Key Management Service (AWS KMS) provides an optional display name for an [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys) called an alias.
The following examples show how to:
+ Create an alias using [CreateAlias](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#createalias).
+ View an alias using [ListAliases](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#listaliases).
+ Update an alias using [UpdateAlias](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#updatealias).
+ Delete an alias using [DeleteAlias](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kms-2014-11-01.html#deletealias).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using AWS Key Management Service (AWS KMS), see the [AWS KMS Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/).
## Create an alias
To create an alias for a KMS key, use the [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) operation. The alias must be unique in the account and AWS Region. If you create an alias for a KMS key that already has an alias, `CreateAlias` creates another alias to the same KMS key. It doesn’t replace the existing alias.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$aliasName = "alias/projectKey1";
try {
$result = $KmsClient->createAlias([
'AliasName' => $aliasName,
'TargetKeyId' => $keyId,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## View an alias
To list all aliases in the caller's AWS account and AWS Region, use the [ListAliases](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$limit = 10;
try {
$result = $KmsClient->listAliases([
'Limit' => $limit,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Update an alias
To associate an existing alias with a different KMS key, use the [UpdateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateAlias.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$keyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab';
$aliasName = "alias/projectKey1";
try {
$result = $KmsClient->updateAlias([
'AliasName' => $aliasName,
'TargetKeyId' => $keyId,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Delete an alias
To delete an alias, use the [DeleteAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteAlias.html) operation. Deleting an alias has no effect on the underlying KMS key.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$KmsClient = new Aws\Kms\KmsClient([
'profile' => 'default',
'version' => '2014-11-01',
'region' => 'us-east-2'
]);
$aliasName = "alias/projectKey1";
try {
$result = $KmsClient->deleteAlias([
'AliasName' => $aliasName,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Amazon Kinesis examples using the AWS SDK for PHP Version 3
Amazon Kinesis is an AWS service that collects, processes, and analyzes data in real time. Configure your data streams with Amazon Kinesis Data Streams or use Amazon Data Firehose to send data to Amazon S3, OpenSearch Service, Amazon Redshift, or Splunk.
For more information about Kinesis, see the [Amazon Kinesis documentation](https://docs.aws.amazon.com/kinesis/index.html).
All the example code for the AWS SDK for PHP Version 3 is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
**Topics**
+ [Kinesis data streams](kinesis-example-data-stream.md)
+ [Kinesis shards](kinesis-example-shard.md)
+ [Kinesis Data Firehose delivery streams](kinesis-firehose-example-delivery-stream.md)
# Creating data streams using the Kinesis Data Streams API and the AWS SDK for PHP Version 3
Amazon Kinesis Data Streams allows you to send real-time data. Create a data producer with Kinesis Data Streams that delivers data to the configured destination every time you add data.
For more information, see [Creating and Managing Streams](https://docs.aws.amazon.com/kinesis/latest/dev/working-with-streams.html.html) in the Amazon Kinesis Developer Guide.
The following examples show how to:
+ Create a data stream using [CreateAlias](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kinesis-1913-12-02.html#createstream).
+ Get details about a single data stream using [DescribeStream](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kinesis-1913-12-02.html#describestream).
+ List existing data streams using [ListStreams](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kinesis-1913-12-02.html#liststreams).
+ Send data to an existing data stream using [PutRecord](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kinesis-1913-12-02.html#putrecord).
+ Delete a data stream using [DeleteStream](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kinesis-1913-12-02.html#deletestream).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using Amazon Kinesis Developer Guide, see the [Amazon Kinesis Data Streams Developer Guide](https://docs.aws.amazon.com/kinesis/latest/dev/).
## Create a data stream using a Kinesis data stream
Establish a Kinesis data stream where you can send information to be processed by Kinesis using the following code example. Learn more about [Creating and Updating Data Streams](https://docs.aws.amazon.com/kinesis/latest/dev/amazon-kinesis-streams.html) in the Amazon Kinesis Developer Guide.
To create a Kinesis data stream, use the [CreateStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_CreateStream.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$kinesisClient = new Aws\Kinesis\KinesisClient([
'profile' => 'default',
'version' => '2013-12-02',
'region' => 'us-east-2'
]);
$shardCount = 2;
$name = "my_stream_name";
try {
$result = $kinesisClient->createStream([
'ShardCount' => $shardCount,
'StreamName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Retrieve a data stream
Get details about an existing data stream using the following code example. By default, this returns information about the first 10 shards connected to the specified Kinesis data stream. Remember to check `StreamStatus` from the response before writing data to a Kinesis data stream.
To retrieve details about a specified Kinesis data stream, use the [DescribeStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DescribeStream.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$kinesisClient = new Aws\Kinesis\KinesisClient([
'profile' => 'default',
'version' => '2013-12-02',
'region' => 'us-east-2'
]);
$name = "my_stream_name";
try {
$result = $kinesisClient->describeStream([
'StreamName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## List existing data streams that are connected to Kinesis
List the first 10 data streams from your AWS account in the selected AWS Region. Use the returned ``HasMoreStreams` to determine if there are more streams associated with your account.
To list your Kinesis data streams, use the [ListStreams](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListStreams.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$kinesisClient = new Aws\Kinesis\KinesisClient([
'profile' => 'default',
'version' => '2013-12-02',
'region' => 'us-east-2'
]);
try {
$result = $kinesisClient->listStreams();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Send data to an existing data stream
Once you create a data stream, use the following example to send data. Before sending data to it, use `DescribeStream` to check whether the data `StreamStatus` is active.
To write a single data record to a Kinesis data stream, use the [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html) operation. To write up to 500 records into a Kinesis data stream, use the [PutRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$kinesisClient = new Aws\Kinesis\KinesisClient([
'profile' => 'default',
'version' => '2013-12-02',
'region' => 'us-east-1'
]);
$name = "my_stream_name";
$content = '{"ticker_symbol":"QXZ", "sector":"HEALTHCARE", "change":-0.05, "price":84.51}';
$groupID = "input to a hash function that maps the partition key (and associated data) to a specific shard";
try {
$result = $kinesisClient->PutRecord([
'Data' => $content,
'StreamName' => $name,
'PartitionKey' => $groupID
]);
print("ShardID = " . $result["ShardId"] . "
");
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Delete a data stream
This example demonstrates how to delete a data stream. Deleting a data stream also deletes any data you sent to the data stream. Active Kinesis data streams switch to the DELETING state until the stream deletion is complete. While in the DELETING state, the stream continues to process data.
To delete a Kinesis data stream, use the [DeleteStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DeleteStream.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$kinesisClient = new Aws\Kinesis\KinesisClient([
'profile' => 'default',
'version' => '2013-12-02',
'region' => 'us-east-2'
]);
$name = "my_stream_name";
try {
$result = $kinesisClient->deleteStream([
'StreamName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Manage data shards using the Kinesis Data Streams API and the AWS SDK for PHP Version 3
Amazon Kinesis Data Streams enables you to send real-time data to an endpoint. The rate of data flow depends on the number of shards in your stream.
You can write 1,000 records per second to a single shard. Each shard also has an upload limit of 1 MiB per second. Usage is calculated and charged on a per-shard basis, so use these examples to manage the data capacity and cost of your stream.
The following examples show how to:
+ List shards in a stream using [ListShards](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kinesis-1913-12-02.html#listshards).
+ Add or reduce the number of shards in a stream using [UpdateShardCount](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-kinesis-1913-12-02.html#updateshardcount).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using Amazon Kinesis Data Streams, see the [Amazon Kinesis Data Streams Developer Guide](https://docs.aws.amazon.com/streams/latest/dev/).
## List data stream shards
List the details of up to 100 shards in a specific stream.
To list the shards in a Kinesis data stream, use the [ListShards](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListShards.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$kinesisClient = new Aws\Kinesis\KinesisClient([
'profile' => 'default',
'version' => '2013-12-02',
'region' => 'us-east-2'
]);
$name = "my_stream_name";
try {
$result = $kinesisClient->ListShards([
'StreamName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Add more data stream shards
If you need more data stream shards, you can increase your current number of shards. We recommend that you double your shard count when increasing. This makes a copy of each shard currently available to increase your capacity. You can double the number of your shards only twice in one 24-hour period.
Remember that billing for Kinesis Data Streams usage is calculated per shard, so when demand decreases, we recommend that you reduce your shard count by half. When you remove shards, you can only scale down the amount of shards to half of your current shard count.
To update the shard count of a Kinesis data stream, use the [UpdateShardCount](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_UpdateShardCount.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$kinesisClient = new Aws\Kinesis\KinesisClient([
'profile' => 'default',
'version' => '2013-12-02',
'region' => 'us-east-2'
]);
$name = "my_stream_name";
$totalshards = 4;
try {
$result = $kinesisClient->UpdateShardCount([
'ScalingType' => 'UNIFORM_SCALING',
'StreamName' => $name,
'TargetShardCount' => $totalshards
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Creating delivery streams using the Firehose API and the AWS SDK for PHP Version 3
Amazon Data Firehose enables you to send real-time data to other AWS services including Amazon Kinesis Data Streams, Amazon S3, Amazon OpenSearch Service (OpenSearch Service), and Amazon Redshift, or to Splunk. Create a data producer with delivery streams to deliver data to the configured destination every time you add data.
The following examples show how to:
+ Create a delivery stream using [CreateDeliveryStream](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-firehose-2015-08-04.html#createdeliverystream).
+ Get details about a single delivery stream using [DescribeDeliveryStream](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-firehose-2015-08-04.html#describedeliverystream).
+ List your delivery streams using [ListDeliveryStreams](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-firehose-2015-08-04.html#listdeliverystreams).
+ Send data to a delivery stream using [PutRecord](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-firehose-2015-08-04.html#putrecord).
+ Delete a delivery stream using [DeleteDeliveryStream](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-firehose-2015-08-04.html#deletedeliverystream).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using Amazon Data Firehose, see the [Amazon Kinesis Data Firehose Developer Guide](https://docs.aws.amazon.com/streams/latest/dev/).
## Create a delivery stream using a Kinesis data stream
To establish a delivery stream that puts data into an existing Kinesis data stream, use the [CreateDeliveryStream](https://docs.aws.amazon.com/firehose/latest/APIReference/API_CreateDeliveryStream.html) operation.
This enables developers to migrate existing Kinesis services to Firehose.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$firehoseClient = new Aws\Firehose\FirehoseClient([
'profile' => 'default',
'version' => '2015-08-04',
'region' => 'us-east-2'
]);
$name = "my_stream_name";
$stream_type = "KinesisStreamAsSource";
$kinesis_stream = "arn:aws:kinesis:us-east-2:0123456789:stream/my_stream_name";
$role = "arn:aws:iam::0123456789:policy/Role";
try {
$result = $firehoseClient->createDeliveryStream([
'DeliveryStreamName' => $name,
'DeliveryStreamType' => $stream_type,
'KinesisStreamSourceConfiguration' => [
'KinesisStreamARN' => $kinesis_stream,
'RoleARN' => $role,
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Create a delivery stream using an Amazon S3 bucket
To establish a delivery stream that puts data into an existing Amazon S3 bucket, use the [CreateDeliveryStream](https://docs.aws.amazon.com/firehose/latest/APIReference/API_CreateDeliveryStream.html) operation.
Provide the destination parameters, as described in [Destination Parameters](https://docs.aws.amazon.com/firehose/latest/dev/create-destination.html). Then ensure that you grant Firehose access to your Amazon S3 bucket, as described in [Grant Kinesis Data Firehose Access to an Amazon S3 Destination](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-s3.html).
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$firehoseClient = new Aws\Firehose\FirehoseClient([
'profile' => 'default',
'version' => '2015-08-04',
'region' => 'us-east-2'
]);
$name = "my_S3_stream_name";
$stream_type = "DirectPut";
$s3bucket = 'arn:aws:s3:::bucket_name';
$s3Role = 'arn:aws:iam::0123456789:policy/Role';
try {
$result = $firehoseClient->createDeliveryStream([
'DeliveryStreamName' => $name,
'DeliveryStreamType' => $stream_type,
'S3DestinationConfiguration' => [
'BucketARN' => $s3bucket,
'CloudWatchLoggingOptions' => [
'Enabled' => false,
],
'RoleARN' => $s3Role
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Create a delivery stream using OpenSearch Service
To establish a Firehose delivery stream that puts data into an OpenSearch Service cluster, use the [CreateDeliveryStream](https://docs.aws.amazon.com/firehose/latest/APIReference/API_CreateDeliveryStream.html) operation.
Provide the destination parameters, as described in [Destination Parameters](https://docs.aws.amazon.com/firehose/latest/dev/create-destination.html). Ensure that you grant Firehose access to your OpenSearch Service cluster, as described in [Grant Kinesis Data Firehose Access to an Amazon ES Destination](https://docs.aws.amazon.com/firehose/latest/dev/controlling-access.html#using-iam-es.html).
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$firehoseClient = new Aws\Firehose\FirehoseClient([
'profile' => 'default',
'version' => '2015-08-04',
'region' => 'us-east-2'
]);
$name = "my_ES_stream_name";
$stream_type = "DirectPut";
$esDomainARN = 'arn:aws:es:us-east-2:0123456789:domain/Name';
$esRole = 'arn:aws:iam::0123456789:policy/Role';
$esIndex = 'root';
$esType = 'PHP_SDK';
$s3bucket = 'arn:aws:s3:::bucket_name';
$s3Role = 'arn:aws:iam::0123456789:policy/Role';
try {
$result = $firehoseClient->createDeliveryStream([
'DeliveryStreamName' => $name,
'DeliveryStreamType' => $stream_type,
'ElasticsearchDestinationConfiguration' => [
'DomainARN' => $esDomainARN,
'IndexName' => $esIndex,
'RoleARN' => $esRole,
'S3Configuration' => [
'BucketARN' => $s3bucket,
'CloudWatchLoggingOptions' => [
'Enabled' => false,
],
'RoleARN' => $s3Role,
],
'TypeName' => $esType,
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Retrieve a delivery stream
To get the details about an existing Firehose delivery stream, use the [DescribeDeliveryStream](https://docs.aws.amazon.com/firehose/latest/APIReference/API_DescribeDeliveryStream.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$firehoseClient = new Aws\Firehose\FirehoseClient([
'profile' => 'default',
'version' => '2015-08-04',
'region' => 'us-east-2'
]);
$name = "my_stream_name";
try {
$result = $firehoseClient->describeDeliveryStream([
'DeliveryStreamName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## List existing delivery streams connected to Kinesis Data Streams
To list all the existing Firehose delivery streams sending data to Kinesis Data Streams, use the [ListDeliveryStreams](https://docs.aws.amazon.com/firehose/latest/APIReference/API_ListDeliveryStreams.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$firehoseClient = new Aws\Firehose\FirehoseClient([
'profile' => 'default',
'version' => '2015-08-04',
'region' => 'us-east-2'
]);
try {
$result = $firehoseClient->listDeliveryStreams([
'DeliveryStreamType' => 'KinesisStreamAsSource',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## List existing delivery streams sending data to other AWS services
To list all the existing Firehose delivery streams sending data to Amazon S3, OpenSearch Service, or Amazon Redshift, or to Splunk, use the [ListDeliveryStreams](https://docs.aws.amazon.com/firehose/latest/APIReference/API_ListDeliveryStreams.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$firehoseClient = new Aws\Firehose\FirehoseClient([
'profile' => 'default',
'version' => '2015-08-04',
'region' => 'us-east-2'
]);
try {
$result = $firehoseClient->listDeliveryStreams([
'DeliveryStreamType' => 'DirectPut',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Send data to an existing Firehose delivery stream
To send data through a Firehose delivery stream to your specified destination, use the [PutRecord](https://docs.aws.amazon.com/firehose/latest/APIReference/API_API_PutRecord.html) operation after you create a Firehose delivery stream.
Before sending data to a Firehose delivery stream, use `DescribeDeliveryStream` to see if the delivery stream is active.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$firehoseClient = new Aws\Firehose\FirehoseClient([
'profile' => 'default',
'version' => '2015-08-04',
'region' => 'us-east-2'
]);
$name = "my_stream_name";
$content = '{"ticker_symbol":"QXZ", "sector":"HEALTHCARE", "change":-0.05, "price":84.51}';
try {
$result = $firehoseClient->putRecord([
'DeliveryStreamName' => $name,
'Record' => [
'Data' => $content,
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Delete a Firehose delivery stream
To delete a Firehose delivery stream, use the [DeleteDeliveryStreams](https://docs.aws.amazon.com/firehose/latest/APIReference/API_DeleteDeliveryStreams.html) operation. This also deletes any data you have sent to the delivery stream.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$firehoseClient = new Aws\Firehose\FirehoseClient([
'profile' => 'default',
'version' => '2015-08-04',
'region' => 'us-east-2'
]);
$name = "my_stream_name";
try {
$result = $firehoseClient->deleteDeliveryStream([
'DeliveryStreamName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# AWS Elemental MediaConvert examples using the AWS SDK for PHP Version 3
AWS Elemental MediaConvert is a file-based video transcoding service with broadcast-grade features. You can use it to create assets for broadcast and for video-on-demand (VOD) delivery across the internet. For more information, see the [AWS Elemental MediaConvert User Guide](https://docs.aws.amazon.com/mediaconvert/latest/ug/).
The PHP API for AWS Elemental MediaConvert is exposed through the *`AWS.MediaConvert`* client class. For more information, see [https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-mediaconvert-2017-08-29.html](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-mediaconvert-2017-08-29.html) in the API reference.
## Create and manage transcoding jobs in AWS Elemental MediaConvert
In this example, you use the AWS SDK for PHP Version 3 to call AWS Elemental MediaConvert and create a transcoding job. Before you begin, you need to upload the input video to the Amazon S3 bucket you provisioned for the input storage. For a list of supported input video codecs and containers, see [Supported Input Codecs and Containers](https://docs.aws.amazon.com/mediaconvert/latest/ug/reference-codecs-containers-input.html) in the [AWS Elemental MediaConvert User Guide](https://docs.aws.amazon.com/mediaconvert/latest/ug/).
The following examples show how to:
+ Create transcoding jobs in AWS Elemental MediaConvert. [CreateJob](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-mediaconvert-2017-08-29.html#createjob).
+ Cancel a transcoding job from the AWS Elemental MediaConvert queue. [CancelJob](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-mediaconvert-2017-08-29.html#canceljob)
+ Retrieve the JSON for a completed transcoding job. [GetJob](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-mediaconvert-2017-08-29.html#getjob)
+ Retrieve a JSON array for up to 20 of the most recently created jobs. [ListJobs](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-mediaconvert-2017-08-29.html#listjobs)
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
### Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
To access the MediaConvert client, create an IAM role that gives AWS Elemental MediaConvert access to your input files and the Amazon S3 buckets where your output files are stored. For details, see [Set Up IAM Permissions](https://docs.aws.amazon.com/mediaconvert/latest/ug/iam-role.html) in the [AWS Elemental MediaConvert User Guide](https://docs.aws.amazon.com/mediaconvert/latest/ug/).
### Create a client
Configure the AWS SDK for PHP by creating a MediaConvert client, with the region for your code. In this example, the region is set to us-west-2.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\MediaConvert\MediaConvertClient;
```
**Sample Code**
```
$mediaConvertClient = new MediaConvertClient([
'version' => '2017-08-29',
'region' => 'us-east-2',
'profile' => 'default'
]);
```
### Defining a simple transcoding job
Create the JSON that defines the transcode job parameters.
These parameters are detailed. You can use the [AWS Elemental MediaConvert console](https://console.aws.amazon.com/mediaconvert/home) to generate the JSON job parameters by choosing your job settings in the console, and then choosing **Show job JSON** at the bottom of the **Job** section. This example shows the JSON for a simple job.
**Sample Code**
```
$jobSetting = [
"OutputGroups" => [
[
"Name" => "File Group",
"OutputGroupSettings" => [
"Type" => "FILE_GROUP_SETTINGS",
"FileGroupSettings" => [
"Destination" => "s3://OUTPUT_BUCKET_NAME/"
]
],
"Outputs" => [
[
"VideoDescription" => [
"ScalingBehavior" => "DEFAULT",
"TimecodeInsertion" => "DISABLED",
"AntiAlias" => "ENABLED",
"Sharpness" => 50,
"CodecSettings" => [
"Codec" => "H_264",
"H264Settings" => [
"InterlaceMode" => "PROGRESSIVE",
"NumberReferenceFrames" => 3,
"Syntax" => "DEFAULT",
"Softness" => 0,
"GopClosedCadence" => 1,
"GopSize" => 90,
"Slices" => 1,
"GopBReference" => "DISABLED",
"SlowPal" => "DISABLED",
"SpatialAdaptiveQuantization" => "ENABLED",
"TemporalAdaptiveQuantization" => "ENABLED",
"FlickerAdaptiveQuantization" => "DISABLED",
"EntropyEncoding" => "CABAC",
"Bitrate" => 5000000,
"FramerateControl" => "SPECIFIED",
"RateControlMode" => "CBR",
"CodecProfile" => "MAIN",
"Telecine" => "NONE",
"MinIInterval" => 0,
"AdaptiveQuantization" => "HIGH",
"CodecLevel" => "AUTO",
"FieldEncoding" => "PAFF",
"SceneChangeDetect" => "ENABLED",
"QualityTuningLevel" => "SINGLE_PASS",
"FramerateConversionAlgorithm" => "DUPLICATE_DROP",
"UnregisteredSeiTimecode" => "DISABLED",
"GopSizeUnits" => "FRAMES",
"ParControl" => "SPECIFIED",
"NumberBFramesBetweenReferenceFrames" => 2,
"RepeatPps" => "DISABLED",
"FramerateNumerator" => 30,
"FramerateDenominator" => 1,
"ParNumerator" => 1,
"ParDenominator" => 1
]
],
"AfdSignaling" => "NONE",
"DropFrameTimecode" => "ENABLED",
"RespondToAfd" => "NONE",
"ColorMetadata" => "INSERT"
],
"AudioDescriptions" => [
[
"AudioTypeControl" => "FOLLOW_INPUT",
"CodecSettings" => [
"Codec" => "AAC",
"AacSettings" => [
"AudioDescriptionBroadcasterMix" => "NORMAL",
"RateControlMode" => "CBR",
"CodecProfile" => "LC",
"CodingMode" => "CODING_MODE_2_0",
"RawFormat" => "NONE",
"SampleRate" => 48000,
"Specification" => "MPEG4",
"Bitrate" => 64000
]
],
"LanguageCodeControl" => "FOLLOW_INPUT",
"AudioSourceName" => "Audio Selector 1"
]
],
"ContainerSettings" => [
"Container" => "MP4",
"Mp4Settings" => [
"CslgAtom" => "INCLUDE",
"FreeSpaceBox" => "EXCLUDE",
"MoovPlacement" => "PROGRESSIVE_DOWNLOAD"
]
],
"NameModifier" => "_1"
]
]
]
],
"AdAvailOffset" => 0,
"Inputs" => [
[
"AudioSelectors" => [
"Audio Selector 1" => [
"Offset" => 0,
"DefaultSelection" => "NOT_DEFAULT",
"ProgramSelection" => 1,
"SelectorType" => "TRACK",
"Tracks" => [
1
]
]
],
"VideoSelector" => [
"ColorSpace" => "FOLLOW"
],
"FilterEnable" => "AUTO",
"PsiControl" => "USE_PSI",
"FilterStrength" => 0,
"DeblockFilter" => "DISABLED",
"DenoiseFilter" => "DISABLED",
"TimecodeSource" => "EMBEDDED",
"FileInput" => "s3://INPUT_BUCKET_AND_FILE_NAME"
]
],
"TimecodeConfig" => [
"Source" => "EMBEDDED"
]
];
```
### Create a job
After creating the job parameters JSON, call the createJob method by invoking an `AWS.MediaConvert service object`, and passing the parameters. The ID of the job created is returned in the response data.
**Sample Code**
```
try {
$result = $mediaConvertClient->createJob([
"Role" => "IAM_ROLE_ARN",
"Settings" => $jobSetting, //JobSettings structure
"Queue" => "JOB_QUEUE_ARN",
"UserMetadata" => [
"Customer" => "Amazon"
],
]);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
### Retrieve a job
With the JobID returned when you called createjob, you can get detailed descriptions of recent jobs in JSON format.
**Sample Code**
```
$mediaConvertClient = new MediaConvertClient([
'version' => '2017-08-29',
'region' => 'us-east-2',
'profile' => 'default'
]);
try {
$result = $mediaConvertClient->getJob([
'Id' => 'JOB_ID',
]);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
### Cancel a job
With the JobID returned when you called createjob, you can cancel a job while it is still in the queue. You can’t cancel jobs that have already started transcoding.
**Sample Code**
```
$mediaConvertClient = new MediaConvertClient([
'version' => '2017-08-29',
'region' => 'us-east-2',
'profile' => 'default'
]);
try {
$result = $mediaConvertClient->cancelJob([
'Id' => 'JOB_ID', // REQUIRED The Job ID of the job to be cancelled.
]);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
### Listing recent transcoding jobs
Create the parameters JSON, including values to specify whether to sort the list in ASCENDING, or DESCENDING order, the ARN of the job queue to check, and the status of jobs to include. This returns up to 20 Jobs. To retrieve the 20 next most recent jobs use the nextToken string returned with result.
**Sample Code**
```
$mediaConvertClient = new MediaConvertClient([
'version' => '2017-08-29',
'region' => 'us-east-2',
'profile' => 'default'
]);
try {
$result = $mediaConvertClient->listJobs([
'MaxResults' => 20,
'Order' => 'ASCENDING',
'Queue' => 'QUEUE_ARN',
'Status' => 'SUBMITTED',
// 'NextToken' => '', //OPTIONAL To retrieve the twenty next most recent jobs
]);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Amazon S3 examples using the AWS SDK for PHP Version 3
Amazon Simple Storage Service (Amazon S3) is a web service that provides highly scalable cloud storage. Amazon S3 provides easy to use object storage, with a simple web service interface to store and retrieve any amount of data from anywhere on the web.
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
**Topics**
+ [Credentials](#examplecredentials)
+ [Creating and using Amazon S3 buckets](s3-examples-creating-buckets.md)
+ [Managing Amazon S3 bucket access permissions](s3-examples-access-permissions.md)
+ [Configuring Amazon S3 buckets](s3-examples-configuring-a-bucket.md)
+ [Amazon S3 multipart uploads](s3-multipart-upload.md)
+ [Amazon S3 pre-signed URL](s3-presigned-url.md)
+ [Creating S3 pre-signed POSTs](s3-presigned-post.md)
+ [Using an Amazon S3 bucket as a static web host](s3-examples-static-web-host.md)
+ [Working with Amazon S3 bucket policies](s3-examples-bucket-policies.md)
+ [Using S3 access point ARNs](s3-examples-access-point-arn.md)
+ [Use Multi-Region Access Points](s3-multi-region-access-points.md)
# Creating and using Amazon S3 buckets with the AWS SDK for PHP Version 3
The following examples show how to:
+ Return a list of buckets owned by the authenticated sender of the request using [ListBuckets](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#listbuckets).
+ Create a new bucket using [CreateBucket](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#createbucket).
+ Add an object to a bucket using [PutObject](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
**Imports**
```
require 'vendor/autoload.php';
use Aws\S3\S3Client;
```
## List buckets
Create a PHP file with the following code. First create an AWS.S3 client service that specifies the AWS Region and version. Then call the `listBuckets` method, which returns all Amazon S3 buckets owned by the sender of the request as an array of Bucket structures.
**Sample Code**
```
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
//Listing all S3 Bucket
$buckets = $s3Client->listBuckets();
foreach ($buckets['Buckets'] as $bucket) {
echo $bucket['Name'] . "\n";
}
```
## Create a bucket
Create a PHP file with the following code. First create an AWS.S3 client service that specifies the AWS Region and version. Then call the `createBucket` method with an array as the parameter. The only required field is the key ‘Bucket’, with a string value for the bucket name to create. However, you can specify the AWS Region with the ‘CreateBucketConfiguration’ field. If successful, this method returns the ‘Location’ of the bucket.
**Sample Code**
```
function createBucket($s3Client, $bucketName)
{
try {
$result = $s3Client->createBucket([
'Bucket' => $bucketName,
]);
return 'The bucket\'s location is: ' .
$result['Location'] . '. ' .
'The bucket\'s effective URI is: ' .
$result['@metadata']['effectiveUri'];
} catch (AwsException $e) {
return 'Error: ' . $e->getAwsErrorMessage();
}
}
function createTheBucket()
{
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2006-03-01'
]);
echo createBucket($s3Client, 'amzn-s3-demo-bucket');
}
// Uncomment the following line to run this code in an AWS account.
// createTheBucket();
```
## Put an object in a bucket
To add files to your new bucket, create a PHP file with the following code.
In your command line, execute this file and pass in the name of the bucket where you want to upload your file as a string, followed by the full file path to the file to upload.
**Sample Code**
```
$USAGE = "\n" .
"To run this example, supply the name of an S3 bucket and a file to\n" .
"upload to it.\n" .
"\n" .
"Ex: php PutObject.php \n";
if (count($argv) <= 2) {
echo $USAGE;
exit();
}
$bucket = $argv[1];
$file_Path = $argv[2];
$key = basename($argv[2]);
try {
//Create a S3Client
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
$result = $s3Client->putObject([
'Bucket' => $bucket,
'Key' => $key,
'SourceFile' => $file_Path,
]);
} catch (S3Exception $e) {
echo $e->getMessage() . "\n";
}
```
# Managing Amazon S3 bucket access permissions with the AWS SDK for PHP Version 3
Access control lists (ACLs) are one of the resource-based access policy options you can use to manage access to your buckets and objects. You can use ACLs to grant basic read/write permissions to other AWS accounts. To learn more, see [Managing Access with ACLs](https://docs.aws.amazon.com/AmazonS3/latest/dev/S3_ACLs_UsingACLs.html).
The following example shows how to:
+ Get the access control policy for a bucket using [GetBucketAcl](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getbucketacl).
+ Set the permissions on a bucket using ACLs, using [PutBucketAcl](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putbucketacl).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Get and set an access control list policy
**Imports**
```
require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;
```
**Sample Code**
```
// Create a S3Client
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
// Gets the access control policy for a bucket
$bucket = 'amzn-s3-demo-bucket';
try {
$resp = $s3Client->getBucketAcl([
'Bucket' => $bucket
]);
echo "Succeed in retrieving bucket ACL as follows: \n";
var_dump($resp);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
// Sets the permissions on a bucket using access control lists (ACL).
$params = [
'ACL' => 'public-read',
'AccessControlPolicy' => [
// Information can be retrieved from `getBucketAcl` response
'Grants' => [
[
'Grantee' => [
'DisplayName' => '',
'EmailAddress' => '',
'ID' => '',
'Type' => 'CanonicalUser',
'URI' => '',
],
'Permission' => 'FULL_CONTROL',
],
// ...
],
'Owner' => [
'DisplayName' => '',
'ID' => '',
],
],
'Bucket' => $bucket,
];
try {
$resp = $s3Client->putBucketAcl($params);
echo "Succeed in setting bucket ACL.\n";
} catch (AwsException $e) {
// Display error message
echo $e->getMessage();
echo "\n";
}
```
# Configuring Amazon S3 buckets with the AWS SDK for PHP Version 3
Cross-origin resource sharing (CORS) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. With CORS support in Amazon S3, you can build rich client-side web applications with Amazon S3 and selectively allow cross-origin access to your Amazon S3 resources.
For more information about using CORS configuration with an Amazon S3 bucket, see [Cross-Origin Resource Sharing (CORS)](https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html).
The following examples show how to:
+ Get the CORS configuration for a bucket using [GetBucketCors](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getbucketcors).
+ Set the CORS configuration for a bucket using [PutBucketCors](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putbucketcors).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Get the CORS configuration
Create a PHP file with the following code. First create an AWS.S3 client service, then call the `getBucketCors` method and specify the bucket whose CORS configuration you want.
The only parameter required is the name of the selected bucket. If the bucket currently has a CORS configuration, that configuration is returned by Amazon S3 as a [CORSRules object](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#shape-corsrule).
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\S3\S3Client;
```
**Sample Code**
```
$client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
try {
$result = $client->getBucketCors([
'Bucket' => $bucketName, // REQUIRED
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Set the CORS configuration
Create a PHP file with the following code. First create an AWS.S3 client service. Then call the `putBucketCors` method and specify the bucket whose CORS configuration to set, and the CORSConfiguration as a [CORSRules JSON object](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#shape-corsrule).
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\S3\S3Client;
```
**Sample Code**
```
$client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
try {
$result = $client->putBucketCors([
'Bucket' => $bucketName, // REQUIRED
'CORSConfiguration' => [ // REQUIRED
'CORSRules' => [ // REQUIRED
[
'AllowedHeaders' => ['Authorization'],
'AllowedMethods' => ['POST', 'GET', 'PUT'], // REQUIRED
'AllowedOrigins' => ['*'], // REQUIRED
'ExposeHeaders' => [],
'MaxAgeSeconds' => 3000
],
],
]
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Using Amazon S3 multipart uploads with AWS SDK for PHP Version 3
With a single `PutObject` operation, you can upload objects up to 5 GB in size. However, by using the multipart upload methods (for example, `CreateMultipartUpload`, `UploadPart`, `CompleteMultipartUpload`, `AbortMultipartUpload`), you can upload objects from 5 MB to 5 TB in size.
The following example shows how to:
+ Upload an object to Amazon S3, using [ObjectUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectUploader.html).
+ Create a multipart upload for an Amazon S3 object using [MultipartUploader](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.MultipartUploader.html).
+ Copy objects from one Amazon S3 location to another using [ObjectCopier](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.ObjectCopier.html).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Object uploader
If you’re not sure whether `PutObject` or `MultipartUploader` is best for the task, use `ObjectUploader`. `ObjectUploader` uploads a large file to Amazon S3 using either `PutObject` or `MultipartUploader`, based on the payload size.
```
require 'vendor/autoload.php';
use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\ObjectUploader;
use Aws\S3\S3Client;
```
**Sample Code**
```
// Create an S3Client.
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-east-2',
'version' => '2006-03-01'
]);
$bucket = 'your-bucket';
$key = 'my-file.zip';
// Use a stream instead of a file path.
$source = fopen('/path/to/large/file.zip', 'rb');
$uploader = new ObjectUploader(
$s3Client,
$bucket,
$key,
$source
);
do {
try {
$result = $uploader->upload();
if ($result["@metadata"]["statusCode"] == '200') {
print('File successfully uploaded to ' . $result["ObjectURL"] . '.
');
}
print($result);
// If the SDK chooses a multipart upload, try again if there is an exception.
// Unlike PutObject calls, multipart upload calls are not automatically retried.
} catch (MultipartUploadException $e) {
rewind($source);
$uploader = new MultipartUploader($s3Client, $source, [
'state' => $e->getState(),
]);
}
} while (!isset($result));
fclose($source);
```
### Configuration
The `ObjectUploader` object constructor accepts the following arguments:
**`$client`**
The `Aws\ClientInterface` object to use for performing the transfers. This should be an instance of `Aws\S3\S3Client`.
**`$bucket`**
(`string`, *required*) Name of the bucket to which the object is being uploaded.
**`$key`**
(`string`, *required*) Key to use for the object being uploaded.
**`$body`**
(`mixed`, *required*) Object data to upload. Can be a `StreamInterface`, a PHP stream resource, or a string of data to upload.
**`$acl`**
(`string`) Access control list (ACL) to set on the object being upload. Objects are private by default.
**`$options`**
An associative array of configuration options for the multipart upload. The following configuration options are valid:
**`add_content_md5`**
(`bool`) Set to true to automatically calculate the MD5 checksum for the upload.
**`mup_threshold`**
(`int`, *default*: `int(16777216)`) The number of bytes for the file size. If the file size exceeds this limit, a multipart upload is used.
**`before_complete`**
(`callable`) Callback to invoke before the `CompleteMultipartUpload` operation. The callback should have a function signature similar to: `function (Aws\Command $command) {...}`. See the [CompleteMultipartUpload API reference](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#completemultipartupload) for the parameters that you can add to the `CommandInterface` object.
**`before_initiate`**
(`callable`) Callback to invoke before the `CreateMultipartUpload` operation. The callback should have a function signature similar to: `function (Aws\Command $command) {...}`. The SDK invokes this callback if the file size exceeds the `mup_threshold` value. See the [CreateMultipartUpload API reference](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#createmultipartupload) for the parameters that you can add to the `CommandInterface` object.
**`before_upload`**
(`callable`) Callback to invoke before any `PutObject` or `UploadPart` operations. The callback should have a function signature similar to: `function (Aws\Command $command) {...}`. The SDK invokes this callback if the file size is less than or equal to the `mup_threshold` value. See the [PutObject API reference](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) for the parameters that you can apply to the `PutObject` request. For parameters that apply to an `UploadPart` request, see the [UploadPart API reference](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#uploadpart). The SDK ignores any parameter that is not applicable to the operation represented by the `CommandInterface` object.
**`concurrency`**
(`int`, *default*: `int(3)`) Maximum number of concurrent `UploadPart` operations allowed during the multipart upload.
**`part_size`**
(`int`, *default*: `int(5242880)`) Part size, in bytes, to use when doing a multipart upload. The value must between 5 MB and 5 GB, inclusive.
**`state`**
(`Aws\Multipart\UploadState`) An object that represents the state of the multipart upload and that is used to resume a previous upload. When this option is provided, the `$bucket` and `$key` arguments and the `part_size` option are ignored.
**`params`**
An associative array that provides configuration options for each subcommand. For example:
```
new ObjectUploader($bucket, $key, $body, $acl, ['params' => ['CacheControl' => ])
```
## MultipartUploader
Multipart uploads are designed to improve the upload experience for larger objects. They enable you to upload objects in parts independently, in any order, and in parallel.
Amazon S3 customers are encouraged to use multipart uploads for objects greater than 100 MB.
## MultipartUploader object
The SDK has a special `MultipartUploader` object that simplifies the multipart upload process.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```
**Sample Code**
```
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
// Use multipart upload
$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
'bucket' => 'your-bucket',
'key' => 'my-file.zip',
]);
try {
$result = $uploader->upload();
echo "Upload complete: {$result['ObjectURL']}\n";
} catch (MultipartUploadException $e) {
echo $e->getMessage() . "\n";
}
```
The uploader creates a generator of part data, based on the provided source and configuration, and attempts to upload all parts. If some part uploads fail, the uploader continues to upload later parts until the entire source data is read. Afterwards, the uploader retries to upload the failed parts or throws an exception containing information about the parts that failed to upload.
## Customizing a multipart upload
You can set custom options on the `CreateMultipartUpload`, `UploadPart`, and `CompleteMultipartUpload` operations executed by the multipart uploader via callbacks passed to its constructor.
**Imports**
```
require 'vendor/autoload.php';
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```
**Sample Code**
```
// Create an S3Client
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
// Customizing a multipart upload
$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
'bucket' => 'your-bucket',
'key' => 'my-file.zip',
'before_initiate' => function (Command $command) {
// $command is a CreateMultipartUpload operation
$command['CacheControl'] = 'max-age=3600';
},
'before_upload' => function (Command $command) {
// $command is an UploadPart operation
$command['RequestPayer'] = 'requester';
},
'before_complete' => function (Command $command) {
// $command is a CompleteMultipartUpload operation
$command['RequestPayer'] = 'requester';
},
]);
```
### Manual garbage collection between part uploads
If you are hitting the memory limit with large uploads, this may be due to cyclic references generated by the SDK not yet having been collected by the [PHP garbage collector](https://www.php.net/manual/en/features.gc.php) when your memory limit was hit. Manually invoking the collection algorithm between operations may allow the cycles to be collected before hitting that limit. The following example invokes the collection algorithm using a callback before each part upload. Note that invoking the garbage collector does come with a performance cost, and optimal usage will depend on your use case and environment.
```
$uploader = new MultipartUploader($client, $source, [
'bucket' => 'your-bucket',
'key' => 'your-key',
'before_upload' => function(\Aws\Command $command) {
gc_collect_cycles();
}
]);
```
## Recovering from errors
When an error occurs during the multipart upload process, a `MultipartUploadException` is thrown. This exception provides access to the `UploadState` object, which contains information about the multipart upload’s progress. The `UploadState` can be used to resume an upload that failed to complete.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```
**Sample Code**
```
// Create an S3Client
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
'bucket' => 'your-bucket',
'key' => 'my-file.zip',
]);
//Recover from errors
do {
try {
$result = $uploader->upload();
} catch (MultipartUploadException $e) {
$uploader = new MultipartUploader($s3Client, $source, [
'state' => $e->getState(),
]);
}
} while (!isset($result));
//Abort a multipart upload if failed
try {
$result = $uploader->upload();
} catch (MultipartUploadException $e) {
// State contains the "Bucket", "Key", and "UploadId"
$params = $e->getState()->getId();
$result = $s3Client->abortMultipartUpload($params);
}
```
Resuming an upload from an `UploadState` attempts to upload parts that are not already uploaded. The state object tracks the missing parts, even if they are not consecutive. The uploader reads or seeks through the provided source file to the byte ranges that belong to the parts that still need to be uploaded.
`UploadState` objects are serializable, so you can also resume an upload in a different process. You can also get the `UploadState` object, even when you’re not handling an exception, by calling `$uploader->getState()`.
**Important**
Streams passed in as a source to a `MultipartUploader` are not automatically rewound before uploading. If you’re using a stream instead of a file path in a loop similar to the previous example, reset the `$source` variable inside of the `catch` block.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```
**Sample Code**
```
// Create an S3Client
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
//Using stream instead of file path
$source = fopen('/path/to/large/file.zip', 'rb');
$uploader = new MultipartUploader($s3Client, $source, [
'bucket' => 'your-bucket',
'key' => 'my-file.zip',
]);
do {
try {
$result = $uploader->upload();
} catch (MultipartUploadException $e) {
rewind($source);
$uploader = new MultipartUploader($s3Client, $source, [
'state' => $e->getState(),
]);
}
} while (!isset($result));
fclose($source);
```
### Aborting a multipart upload
A multipart upload can be aborted by retrieving the `UploadId` contained in the `UploadState` object and passing it to `abortMultipartUpload`.
```
try {
$result = $uploader->upload();
} catch (MultipartUploadException $e) {
// State contains the "Bucket", "Key", and "UploadId"
$params = $e->getState()->getId();
$result = $s3Client->abortMultipartUpload($params);
}
```
## Asynchronous multipart uploads
Calling `upload()` on the `MultipartUploader` is a blocking request. If you are working in an asynchronous context, you can get a [promise](guide_promises.md) for the multipart upload.
```
require 'vendor/autoload.php';
use Aws\S3\MultipartUploader;
use Aws\S3\S3Client;
```
**Sample Code**
```
// Create an S3Client
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
$source = '/path/to/large/file.zip';
$uploader = new MultipartUploader($s3Client, $source, [
'bucket' => 'your-bucket',
'key' => 'my-file.zip',
]);
$promise = $uploader->promise();
```
### Configuration
The `MultipartUploader` object constructor accepts the following arguments:
** `$client` **
The `Aws\ClientInterface` object to use for performing the transfers. This should be an instance of `Aws\S3\S3Client`.
** `$source` **
The source data being uploaded. This can be a path or URL (for example, `/path/to/file.jpg`), a resource handle (for example, `fopen('/path/to/file.jpg', 'r)`), or an instance of a [PSR-7 stream](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Psr.Http.Message.StreamInterface.html).
** `$config` **
An associative array of configuration options for the multipart upload.
The following configuration options are valid:
** `acl` **
(`string`) Access control list (ACL) to set on the object being upload. Objects are private by default.
** `before_complete` **
(`callable`) Callback to invoke before the `CompleteMultipartUpload` operation. The callback should have a function signature like `function (Aws\Command $command) {...}`.
** `before_initiate` **
(`callable`) Callback to invoke before the `CreateMultipartUpload` operation. The callback should have a function signature like `function (Aws\Command $command) {...}`.
** `before_upload` **
(`callable`) Callback to invoke before any `UploadPart` operations. The callback should have a function signature like `function (Aws\Command $command) {...}`.
** `bucket` **
(`string`, *required*) Name of the bucket to which the object is being uploaded.
** `concurrency` **
(`int`, *default*: `int(5)`) Maximum number of concurrent `UploadPart` operations allowed during the multipart upload.
** `key` **
(`string`, *required*) Key to use for the object being uploaded.
** `part_size` **
(`int`, *default*: `int(5242880)`) Part size, in bytes, to use when doing a multipart upload. This must between 5 MB and 5 GB, inclusive.
** `state` **
(`Aws\Multipart\UploadState`) An object that represents the state of the multipart upload and that is used to resume a previous upload. When this option is provided, the `bucket`, `key`, and `part_size` options are ignored.
**`add_content_md5`**
(`boolean`) Set to true to automatically calculate the MD5 checksum for the upload.
**`params`**
An associative array that provides configuration options for each subcommand. For example:
```
new MultipartUploader($client, $source, ['params' => ['CacheControl' => ]])
```
## Multipart copies
The AWS SDK for PHP also includes a `MultipartCopy` object that is used in a similar way to the `MultipartUploader`, but is designed for copying objects between 5 GB and 5 TB in size within Amazon S3.
```
require 'vendor/autoload.php';
use Aws\Exception\MultipartUploadException;
use Aws\S3\MultipartCopy;
use Aws\S3\S3Client;
```
**Sample Code**
```
// Create an S3Client
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
//Copy objects within S3
$copier = new MultipartCopy($s3Client, '/bucket/key?versionId=foo', [
'bucket' => 'your-bucket',
'key' => 'my-file.zip',
]);
try {
$result = $copier->copy();
echo "Copy complete: {$result['ObjectURL']}\n";
} catch (MultipartUploadException $e) {
echo $e->getMessage() . "\n";
}
```
# Amazon S3 pre-signed URL with AWS SDK for PHP Version 3
You can authenticate certain types of requests by passing the required information as query-string parameters instead of using the Authorization HTTP header. This is useful for enabling direct third-party browser access to your private Amazon S3 data, without proxying the request. The idea is to construct a “pre-signed” request and encode it as a URL that another user can use. Additionally, you can limit a pre-signed request by specifying an expiration time.
## Create a pre-signed URL for an HTTP GET request
The following code example shows how to create a pre-signed URL for an HTTP GET request by using the SDK for PHP.
```
'us-west-2',
]);
// Supply a CommandInterface object and an expires parameter to the `createPresignedRequest` method.
$request = $s3Client->createPresignedRequest(
$s3Client->getCommand('GetObject', [
'Bucket' => 'amzn-s3-demo-bucket',
'Key' => 'demo-key',
]),
'+1 hour'
);
// From the resulting RequestInterface object, you can get the URL.
$presignedUrl = (string) $request->getUri();
echo $presignedUrl;
```
The [API reference for the `createPresignedRequest`](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.S3Client.html#method_createPresignedRequest)method provides more details.
Someone else can use the `$presignedUrl` value to retrieve the object within the next hour. When the HTTP GET request is made—using a browser, for example—it appears to the S3 service that the call is coming from the user who created the pres-signed URL.
## Create a pre-signed URL for an HTTP PUT request
The following code example shows how to create a pre-signed URL for an HTTP PUT request by using the SDK for PHP.
```
'us-west-2',
]);
$request = $s3Client->createPresignedRequest(
$s3Client->getCommand('PutObject', [
'Bucket' => 'amzn-s3-demo-bucket',
'Key' => 'demo-key',
]),
'+1 hour'
);
// From the resulting RequestInterface object, you can get the URL.
$presignedUrl = (string) $request->getUri();
```
Someone else can now use the pre-signed URL in an HTTP PUT request to upload a file:
```
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Response;
// ...
function uploadWithPresignedUrl($presignedUrl, $filePath, $s3Client): ?Response
{
// Get the HTTP handler from the S3 client.
$handler = $s3Client->getHandlerList()->resolve();
// Create a stream from the file.
$fileStream = new Stream(fopen($filePath, 'r'));
// Create the request.
$request = new Request(
'PUT',
$presignedUrl,
[
'Content-Type' => mime_content_type($filePath),
'Content-Length' => filesize($filePath)
],
$fileStream
);
// Send the request using the handler.
try {
$promise = $handler($request, []);
$response = $promise->wait();
return $response;
} catch (Exception $e) {
echo "Error uploading file: " . $e->getMessage() . "\n";
return null;
}
}
```
# Amazon S3 pre-signed POSTs with AWS SDK for PHP Version 3
Much like pre-signed URLs, pre-signed POSTs enable you to give write access to a user without giving them AWS credentials. Pre-signed POST forms can be created with the help of an instance of [AwsS3PostObjectV4](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.PostObjectV4.html).
The following examples show how to:
+ Get data for an S3 Object POST upload form using [PostObjectV4](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.S3.PostObjectV4.html).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
**Note**
`PostObjectV4` does not work with credentials sourced from AWS IAM Identity Center.
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Create PostObjectV4
To create an instance of `PostObjectV4`, you must provide the following:
+ instance of `Aws\S3\S3Client`
+ bucket
+ associative array of form input fields
+ array of policy conditions (see [Policy Construction](https://docs.aws.amazon.com/AmazonS3/latest/dev/HTTPPOSTForms.html) in the Amazon Simple Storage Service User Guide)
+ expiration time string for the policy (optional, one hour by default).
**Imports**
```
require '../vendor/autoload.php';
use Aws\S3\PostObjectV4;
use Aws\S3\S3Client;
```
**Sample Code**
```
require '../vendor/autoload.php';
use Aws\S3\PostObjectV4;
use Aws\S3\S3Client;
$client = new S3Client([
'profile' => 'default',
'region' => 'us-east-1',
]);
$bucket = 'amzn-s3-demo-bucket10';
$starts_with = 'user/eric/';
$client->listBuckets();
// Set defaults for form input fields.
$formInputs = ['acl' => 'public-read'];
// Construct an array of conditions for policy.
$options = [
['acl' => 'public-read'],
['bucket' => $bucket],
['starts-with', '$key', $starts_with],
];
// Set an expiration time (optional).
$expires = '+2 hours';
$postObject = new PostObjectV4(
$client,
$bucket,
$formInputs,
$options,
$expires
);
// Get attributes for the HTML form, for example, action, method, enctype.
$formAttributes = $postObject->getFormAttributes();
// Get attributes for the HTML form values.
$formInputs = $postObject->getFormInputs();
?>
PHP
```
# Using an Amazon S3 bucket as a static web host with AWS SDK for PHP Version 3
You can host a static website on Amazon S3. To learn more, see [Hosting a Static Website on Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html).
The following example shows how to:
+ Get the website configuration for a bucket using [GetBucketWebsite](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getbucketwebsite).
+ Set the website configuration for a bucket using [PutBucketWebsite](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putbucketwebsite).
+ Remove the website configuration from a bucket using [DeleteBucketWebsite](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#deletebucketwebsite).
All the example code for the AWS SDK for PHP Version 3 is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials. See [Credentials for the AWS SDK for PHP Version 3](guide_credentials.md).
## Get, set, and delete the website configuration for a bucket
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\S3\S3Client;
```
**Sample Code**
```
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
// Retrieving the Bucket Website Configuration
$bucket = 'amzn-s3-demo-bucket';
try {
$resp = $s3Client->getBucketWebsite([
'Bucket' => $bucket
]);
echo "Succeed in retrieving website configuration for bucket: " . $bucket . "\n";
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
// Setting a Bucket Website Configuration
$params = [
'Bucket' => $bucket,
'WebsiteConfiguration' => [
'ErrorDocument' => [
'Key' => 'foo',
],
'IndexDocument' => [
'Suffix' => 'bar',
],
]
];
try {
$resp = $s3Client->putBucketWebsite($params);
echo "Succeed in setting bucket website configuration.\n";
} catch (AwsException $e) {
// Display error message
echo $e->getMessage();
echo "\n";
}
// Deleting a Bucket Website Configuration
try {
$resp = $s3Client->deleteBucketWebsite([
'Bucket' => $bucket
]);
echo "Succeed in deleting policy for bucket: " . $bucket . "\n";
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Working with Amazon S3 bucket policies with the AWS SDK for PHP Version 3
You can use a bucket policy to grant permission to your Amazon S3 resources. To learn more, see [Using Bucket Policies and User Policies](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-iam-policies.html).
The following example shows how to:
+ Return the policy for a specified bucket using [GetBucketPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getbucketpolicy).
+ Replace a policy on a bucket using [PutBucketPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putbucketpolicy).
+ Delete a policy from a bucket using [DeleteBucketPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#deletebucketpolicy).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Get, delete, and replace a policy on a bucket
**Imports**
```
require "vendor/autoload.php";
use Aws\Exception\AwsException;
use Aws\S3\S3Client;
```
**Sample Code**
```
$s3Client = new S3Client([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2006-03-01'
]);
$bucket = 'amzn-s3-demo-bucket';
// Get the policy of a specific bucket
try {
$resp = $s3Client->getBucketPolicy([
'Bucket' => $bucket
]);
echo "Succeed in receiving bucket policy:\n";
echo $resp->get('Policy');
echo "\n";
} catch (AwsException $e) {
// Display error message
echo $e->getMessage();
echo "\n";
}
// Deletes the policy from the bucket
try {
$resp = $s3Client->deleteBucketPolicy([
'Bucket' => $bucket
]);
echo "Succeed in deleting policy of bucket: " . $bucket . "\n";
} catch (AwsException $e) {
// Display error message
echo $e->getMessage();
echo "\n";
}
// Replaces a policy on the bucket
try {
$resp = $s3Client->putBucketPolicy([
'Bucket' => $bucket,
'Policy' => 'foo policy',
]);
echo "Succeed in put a policy on bucket: " . $bucket . "\n";
} catch (AwsException $e) {
// Display error message
echo $e->getMessage();
echo "\n";
}
```
# Using S3 access point ARNs the AWS SDK for PHP Version 3
S3 introduced access points, a new way to interact with S3 buckets. Access Points can have unique policies and configuration applied to them instead of directly to the bucket. The AWS SDK for PHP allows you to use access point ARNs in the bucket field for API operations instead of specifying bucket name explicitly. More details on how S3 access points and ARNs work can be found [here](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-access-points.html). The following examples show how to:
+ Use [GetObject](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getobject) with an access point ARN to fetch an object from a bucket.
+ Use [PutObject](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject) with an access point ARN to add an object to a bucket.
+ Configure the S3 client to use the ARN region instead of the client region.
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
**Imports**
```
require 'vendor/autoload.php';
use Aws\S3\S3Client;
```
## Get object
First create an AWS.S3 client service that specifies the AWS region and version. Then call the `getObject` method with your key and an S3 access point ARN in the `Bucket` field, which will fetch the object from the bucket associated with that access point.
**Sample Code**
```
$s3 = new S3Client([
'version' => 'latest',
'region' => 'us-west-2',
]);
$result = $s3->getObject([
'Bucket' => 'arn:aws:s3:us-west-2:123456789012:accesspoint:endpoint-name',
'Key' => 'MyKey'
]);
```
## Put an object in a bucket
First create an AWS.S3 client service that specifies the AWS Region and version. Then call the `putObject` method with the desired key, the body or source file, and an S3 access point ARN in the `Bucket` field, which will put the object in the bucket associated with that access point.
**Sample Code**
```
$s3 = new S3Client([
'version' => 'latest',
'region' => 'us-west-2',
]);
$result = $s3->putObject([
'Bucket' => 'arn:aws:s3:us-west-2:123456789012:accesspoint:endpoint-name',
'Key' => 'MyKey',
'Body' => 'MyBody'
]);
```
## Configure the S3 client to use the ARN region instead of the client region
When using an S3 access point ARN in an S3 client operation, by default the client will make sure that the ARN region matches the client region, throwing an exception if it does not. This behavior can be changed to accept the ARN region over the client region by setting the `use_arn_region` configuration option to `true`. By default, the option is set to `false`.
**Sample Code**
```
$s3 = new S3Client([
'version' => 'latest',
'region' => 'us-west-2',
'use_arn_region' => true
]);
```
The client will also check an environment variable and a config file option, in the following order of priority:
1. The client option `use_arn_region`, as in the above example.
1. The environment variable `AWS_S3_USE_ARN_REGION`
```
export AWS_S3_USE_ARN_REGION=true
```
1. The config variable `s3_use_arn_region` in the AWS shared configuration file (by default in `~/.aws/config`).
```
[default]
s3_use_arn_region = true
```
# Use Amazon S3 Multi-Region Access Points with the AWS SDK for PHP Version 3
[Amazon Simple Storage Service (S3) Multi-Region Access Points](https://docs.aws.amazon.com//AmazonS3/latest/userguide/MultiRegionAccessPoints.html) provide a global endpoint for routing Amazon S3 request traffic between AWS Regions.
You can create Multi-Region Access Points [using the SDK for PHP](https://docs.aws.amazon.com//aws-sdk-php/v3/api/api-s3control-2018-08-20.html#createmultiregionaccesspoint), another AWS SDK, the [S3 console, or AWS CLI](https://docs.aws.amazon.com//AmazonS3/latest/userguide/multi-region-access-point-create-examples.html),
**Important**
To use Multi-Region Access Points with the SDK for PHP, your PHP environment must have the [AWS Common Runtime (AWS CRT) extension](guide_crt.md) installed.
When you create a Multi-Region Access Point, Amazon S3 generates an Amazon Resource Name (ARN) that has the following format:
`arn:aws:s3::account-id:accesspoint/MultiRegionAccessPoint_alias`
You can use the generated ARN in place of a bucket name for `[getObject()](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#getobject)` and `[putObject()](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putobject)` methods.
```
'us-east-1'
]);
$s3Client->putObject([
'Bucket' => $mrap,
'Key' => $key,
'Body' => 'Hello World!'
]);
$result = $s3Client->getObject([
'Bucket' => $mrap,
'Key' => $key
]);
echo $result['Body'] . "\n";
// Clean up.
$result = $s3Client->deleteObject([
'Bucket' => $mrap,
'Key' => $key
]);
$s3Client->waitUntil('ObjectNotExists', ['Bucket' => $mrap, 'Key' => $key]);
echo "Object deleted\n";
```
# Managing secrets using the Secrets Manager API and the AWS SDK for PHP Version 3
AWS Secrets Manager stores and manages shared secrets such as passwords, API keys, and database credentials. With the Secrets Manager service, developers can replace hard-coded credentials in deployed code with an embedded call to Secrets Manager.
Secrets Manager natively supports automatic scheduled credential rotation for Amazon Relational Database Service (Amazon RDS) databases, increasing application security. Secrets Manager can also seamlessly rotate secrets for other databases and third-party services using AWS Lambda to implement service-specific details.
The following examples show how to:
+ Create a secret using [CreateSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#createsecret).
+ Retrieve a secret using [GetSecretValue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#getsecretvalue).
+ List all of the secrets stored by Secrets Manager using [ListSecrets](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#listsecrets).
+ Get details about a specified secret using [DescribeSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#describesecret).
+ Update a specified secret using [PutSecretValue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#putsecretvalue).
+ Set up a secret rotation using [RotateSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#rotatesecret).
+ Mark a secret for deletion using [DeleteSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#deletesecret).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Create a secret in Secrets Manager
To create a secret in Secrets Manager, use the [CreateSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#createsecret) operation.
In this example, a user name and password are stored as a JSON string.
**Imports**
```
require 'vendor/autoload.php';
use Aws\SecretsManager\SecretsManagerClient;
use Aws\Exception\AwsException;
```
**Sample Code**
```
$client = new SecretsManagerClient([
'profile' => 'default',
'version' => '2017-10-17',
'region' => 'us-west-2'
]);
$secretName = 'MySecretName';
$secret = json_encode([
"username" => getenv("SMDEMO_USERNAME"),
"password" => getenv("SMDEMO_PASSWORD"),
]);
$description = '<>';
try {
$result = $client->createSecret([
'Description' => $description,
'Name' => $secretName,
'SecretString' => $secret,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Retrieve a secret from Secrets Manager
To retrieve the value of a secret stored in Secrets Manager, use the [GetSecretValue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#getsecretvalue) operation.
In the following example, `secret` is a string that contains the stored value. If the value for `username` is `<>` and the value for `password` is `<>`, the output of `secret` is:
```
{"username":"<>","password":"<>"}
```
Use `json_decode($secret, true)` to access the array values.
**Imports**
```
require 'vendor/autoload.php';
use Aws\SecretsManager\SecretsManagerClient;
use Aws\Exception\AwsException;
```
**Sample Code**
```
$client = new SecretsManagerClient([
'profile' => 'default',
'version' => '2017-10-17',
'region' => 'us-east-1',
]);
$secretName = 'MySecretName';
try {
$result = $client->getSecretValue([
'SecretId' => $secretName,
]);
} catch (AwsException $e) {
$error = $e->getAwsErrorCode();
if ($error == 'DecryptionFailureException') {
// Secrets Manager can't decrypt the protected secret text using the provided AWS KMS key.
// Handle the exception here, and/or rethrow as needed.
throw $e;
}
if ($error == 'InternalServiceErrorException') {
// An error occurred on the server side.
// Handle the exception here, and/or rethrow as needed.
throw $e;
}
if ($error == 'InvalidParameterException') {
// You provided an invalid value for a parameter.
// Handle the exception here, and/or rethrow as needed.
throw $e;
}
if ($error == 'InvalidRequestException') {
// You provided a parameter value that is not valid for the current state of the resource.
// Handle the exception here, and/or rethrow as needed.
throw $e;
}
if ($error == 'ResourceNotFoundException') {
// We can't find the resource that you asked for.
// Handle the exception here, and/or rethrow as needed.
throw $e;
}
}
// Decrypts secret using the associated KMS CMK.
// Depending on whether the secret is a string or binary, one of these fields will be populated.
if (isset($result['SecretString'])) {
$secret = $result['SecretString'];
} else {
$secret = base64_decode($result['SecretBinary']);
}
print $secret;
$secretArray = json_decode($secret, true);
$username = $secretArray['username'];
$password = $secretArray['password'];
// Your code goes here;
```
## List secrets stored in Secrets Manager
Get a list of all the secrets that are stored by Secrets Manager using the [ListSecrets](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#listsecrets) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\SecretsManager\SecretsManagerClient;
use Aws\Exception\AwsException;
```
**Sample Code**
```
$client = new SecretsManagerClient([
'profile' => 'default',
'version' => '2017-10-17',
'region' => 'us-west-2'
]);
try {
$result = $client->listSecrets([
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Retrieve details about a secret
Stored secrets contain metadata about rotation rules, when it was last accessed or changed, user-created tags, and the Amazon Resource Name (ARN). To get the details of a specified secret stored in Secrets Manager, use the [DescribeSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#describesecret) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\SecretsManager\SecretsManagerClient;
use Aws\Exception\AwsException;
```
**Sample Code**
```
$client = new SecretsManagerClient([
'profile' => 'default',
'version' => '2017-10-17',
'region' => 'us-west-2'
]);
$secretName = 'MySecretName';
try {
$result = $client->describeSecret([
'SecretId' => $secretName,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Update the secret value
To store a new encrypted secret value in Secrets Manager, use the [PutSecretValue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#putsecretvalue) operation.
This creates a new version of the secret. If a version of the secret already exists, add the `VersionStages` parameter with the value in `AWSCURRENT` to ensure that the new value is used when retrieving the value.
**Imports**
```
require 'vendor/autoload.php';
use Aws\SecretsManager\SecretsManagerClient;
use Aws\Exception\AwsException;
```
**Sample Code**
```
$client = new SecretsManagerClient([
'profile' => 'default',
'version' => '2017-10-17',
'region' => 'us-west-2'
]);
$secretName = 'MySecretName';
$secret = json_encode([
"username" => getenv("SMDEMO_USERNAME"),
"password" => getenv("SMDEMO_PASSWORD"),
]);
try {
$result = $client->putSecretValue([
'SecretId' => $secretName,
'SecretString' => $secret,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Rotate the value to an existing secret in Secrets Manager
To rotate the value of an existing secret stored in Secrets Manager, use a Lambda rotation function and the [RotateSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#rotatesecret) operation.
Before you begin, create a Lambda function to rotate your secret. The [AWS Code Sample Catalog](https://docs.aws.amazon.com/code-samples/latest/catalog/code-catalog-lambda_functions-secretsmanager.html) currently contains several Lambda code examples for rotating Amazon RDS database credentials.
**Note**
For more information about rotating secrets, see [Rotating Your AWS Secrets Manager Secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html) in the AWS Secrets Manager User Guide.
After you set up your Lambda function, configure a new secret rotation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\SecretsManager\SecretsManagerClient;
use Aws\Exception\AwsException;
```
**Sample Code**
```
$client = new SecretsManagerClient([
'profile' => 'default',
'version' => '2017-10-17',
'region' => 'us-west-2'
]);
$secretName = 'MySecretName';
$lambda_ARN = 'arn:aws:lambda:us-west-2:123456789012:function:MyTestDatabaseRotationLambda';
$rules = ['AutomaticallyAfterDays' => 30];
try {
$result = $client->rotateSecret([
'RotationLambdaARN' => $lambda_ARN,
'RotationRules' => $rules,
'SecretId' => $secretName,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
When a rotation is configured, you can implement a rotation using the [RotateSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#rotatesecret) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\SecretsManager\SecretsManagerClient;
use Aws\Exception\AwsException;
```
**Sample Code**
```
$client = new SecretsManagerClient([
'profile' => 'default',
'version' => '2017-10-17',
'region' => 'us-west-2'
]);
$secretName = 'MySecretName';
try {
$result = $client->rotateSecret([
'SecretId' => $secretName,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Delete a secret from Secrets Manager
To remove a specified secret from Secrets Manager, use the [DeleteSecret](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-secretsmanager-2017-10-17.html#deletesecret) operation. To prevent deleting a secret accidentally, a DeletionDate stamp is automatically added to the secret that specifies a window of recovery time in which you can reverse the deletion. If the time isn’t specified for the recovery window, the default amount of time is 30 days.
**Imports**
```
require 'vendor/autoload.php';
use Aws\SecretsManager\SecretsManagerClient;
use Aws\Exception\AwsException;
```
**Sample Code**
```
$client = new SecretsManagerClient([
'profile' => 'default',
'version' => '2017-10-17',
'region' => 'us-west-2'
]);
$secretName = 'MySecretName';
try {
$result = $client->deleteSecret([
'SecretId' => $secretName,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Related information
The AWS SDK for PHP examples use the following REST operations from the AWS Secrets Manager API Reference:
+ [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html)
+ [GetSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html)
+ [ListSecrets](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ListSecrets.html)
+ [DescribeSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_DescribeSecret.html)
+ [PutSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html)
+ [RotateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_RotateSecret.html)
+ [DeleteSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_DeleteSecret.html)
For more information about using AWS Secrets Manager, see the [AWS Secrets Manager User Guide](https://docs.aws.amazon.com/secretsmanager/latest/userguide/).
# Amazon SES examples using the AWS SDK for PHP Version 3
Amazon Simple Email Service (Amazon SES) is an email platform that provides an easy, money-saving way for you to send and receive email using your own email addresses and domains. For more information about Amazon SES, see the [Amazon SES Developer Guide](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/).
AWS offers two versions of Amazon SES service and, correspondingly, the SDK for PHP offers two versions of the client: [SesClient](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.Ses.SesClient.html) and [SesV2Client](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.SesV2.SesV2Client.html). The functionality of the clients overlap in many cases although the way the methods are called or the results may differ. The two APIs also offer exclusive features, so you can use both clients to access all the functionality.
The examples in this section all use the original, `SesClient`.
All the example code for the AWS SDK for PHP Version 3 is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
**Topics**
+ [Verifying email addresses](ses-verify.md)
+ [Working with email templates](ses-template.md)
+ [Managing email filters](ses-filters.md)
+ [Using email rules](ses-rules.md)
+ [Monitor your sending activity](ses-send-email.md)
+ [Authorizing senders](ses-sender-policy.md)
# Verifying email identities using the Amazon SES API and the AWS SDK for PHP Version 3
When you first start using your Amazon Simple Email Service (Amazon SES) account, all senders and recipients must be verified in the same AWS Region that you are sending emails to. For more information about sending emails, see [Sending Email with Amazon SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-email.html).
The following examples show how to:
+ Verify an email address using [VerifyEmailIdentity](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#verifyemailidentity).
+ Verify an email domain using [VerifyDomainIdentity](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#verifydomainidentity).
+ List all email addresses using [ListIdentities](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#listidentities).
+ List all email domains using [ListIdentities](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#listidentities).
+ Remove an email address using [DeleteIdentity](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#deleteidentity).
+ Remove an email domain using [DeleteIdentity](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#deleteidentity).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using Amazon SES, see the [Amazon SES Developer Guide](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/).
## Verify an email addresses
Amazon SES can send email only from verified email addresses or domains. By verifying an email address, you demonstrate that you’re the owner of that address and want to allow Amazon SES to send email from that address.
When you run the following code example, Amazon SES sends an email to the address you specified. When you (or the recipient of the email) click the link in the email, the address is verified.
To add an email address to your Amazon SES account, use the [VerifyEmailIdentity](https://docs.aws.amazon.com/ses/latest/APIReference/API_VerifyEmailIdentity.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$email = 'email_address';
try {
$result = $SesClient->verifyEmailIdentity([
'EmailAddress' => $email,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Verify an email domain
Amazon SES can send email only from verified email addresses or domains. By verifying a domain, you demonstrate that you’re the owner of that domain. When you verify a domain, you allow Amazon SES to send email from any address on that domain.
When you run the following code example, Amazon SES provides you with a verification token. You have to add the token to your domain’s DNS configuration. For more information, see [Verifying a Domain with Amazon SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domain-procedure.html) in the Amazon Simple Email Service Developer Guide.
To add a sending domain to your Amazon SES account, use the [VerifyDomainIdentity](https://docs.aws.amazon.com/ses/latest/APIReference/API_VerifyDomainIdentity.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$domain = 'domain.name';
try {
$result = $SesClient->verifyDomainIdentity([
'Domain' => $domain,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## List email addresses
To retrieve a list of email addresses submitted in the current AWS Region, regardless of verification status, use the [ListIdentities](https://docs.aws.amazon.com/ses/latest/APIReference/API_ListIdentities.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
try {
$result = $SesClient->listIdentities([
'IdentityType' => 'EmailAddress',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## List email domains
To retrieve a list of email domains submitted in the current AWS Region, regardless of verification status use the [ListIdentities](https://docs.aws.amazon.com/ses/latest/APIReference/API_ListIdentities.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
try {
$result = $SesClient->listIdentities([
'IdentityType' => 'Domain',
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Delete an email address
To delete a verified email address from the list of identities, use the [DeleteIdentity](https://docs.aws.amazon.com/ses/latest/APIReference/API_DeleteIdentity.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$email = 'email_address';
try {
$result = $SesClient->deleteIdentity([
'Identity' => $email,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Delete an email domain
To delete a verified email domain from the list of verified identities, use the [DeleteIdentity](https://docs.aws.amazon.com/ses/latest/APIReference/API_DeleteIdentity.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$domain = 'domain.name';
try {
$result = $SesClient->deleteIdentity([
'Identity' => $domain,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Creating custom email templates using the Amazon SES API and the AWS SDK for PHP Version 3
Amazon Simple Email Service (Amazon SES) enables you to send emails that are personalized for each recipient by using templates. Templates include a subject line and the text and HTML parts of the email body. The subject and body sections can also contain unique values that are personalized for each recipient.
For more information, see [Sending Personalized Email Using the Amazon SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-personalized-email-api.html) in the Amazon Simple Email Service Developer Guide.
The following examples show how to:
+ Create an email template using [CreateTemplate](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#createtemplate).
+ List all email templates using [ListTemplates](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#listtemplates).
+ Retrieve an email template using [GetTemplate](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#gettemplate).
+ Update an email template using [UpdateTemplate](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#updateTemplate).
+ Remove an email template using [DeleteTemplate](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#deletetemplate).
+ Send a templated email using [SendTemplatedEmail](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#sendtemplatedemail).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using Amazon SES, see the [Amazon SES Developer Guide](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/).
## Create an email template
To create a template to send personalized email messages, use the [CreateTemplate](https://docs.aws.amazon.com/ses/latest/APIReference/API_CreateTemplate.html) operation. The template can be used by any account authorized to send messages in the AWS Region to which the template is added.
**Note**
Amazon SES doesn’t validate your HTML, so be sure that *HtmlPart* is valid before sending an email.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$name = 'Template_Name';
$html_body = 'AWS Amazon Simple Email Service Test Email
' .
'This email was sent with ' .
'Amazon SES using the ' .
'AWS SDK for PHP.
';
$subject = 'Amazon SES test (AWS SDK for PHP)';
$plaintext_body = 'This email was send with Amazon SES using the AWS SDK for PHP.';
try {
$result = $SesClient->createTemplate([
'Template' => [
'HtmlPart' => $html_body,
'SubjectPart' => $subject,
'TemplateName' => $name,
'TextPart' => $plaintext_body,
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Get an email template
To view the content for an existing email template including the subject line, HTML body, and plain text, use the [GetTemplate](https://docs.aws.amazon.com/ses/latest/APIReference/API_GetTemplate.html) operation. Only TemplateName is required.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$name = 'Template_Name';
try {
$result = $SesClient->getTemplate([
'TemplateName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## List all email templates
To retrieve a list of all email templates that are associated with your AWS account in the current AWS Region, use the [ListTemplates](https://docs.aws.amazon.com/ses/latest/APIReference/API_ListTemplates.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
try {
$result = $SesClient->listTemplates([
'MaxItems' => 10,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Update an email template
To change the content for a specific email template including the subject line, HTML body, and plain text, use the [UpdateTemplate](https://docs.aws.amazon.com/ses/latest/APIReference/API_UpdadteTemplate.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$name = 'Template_Name';
$html_body = 'AWS Amazon Simple Email Service Test Email
' .
'This email was sent with ' .
'Amazon SES using the ' .
'AWS SDK for PHP.
';
$subject = 'Amazon SES test (AWS SDK for PHP)';
$plaintext_body = 'This email was send with Amazon SES using the AWS SDK for PHP.';
try {
$result = $SesClient->updateTemplate([
'Template' => [
'HtmlPart' => $html_body,
'SubjectPart' => $subject,
'TemplateName' => $name,
'TextPart' => $plaintext_body,
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Delete an email template
To remove a specific email template, use the [DeleteTemplate](https://docs.aws.amazon.com/ses/latest/APIReference/API_DeleteTemplate.html) operation. All you need is the TemplateName.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$name = 'Template_Name';
try {
$result = $SesClient->deleteTemplate([
'TemplateName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Send an email with a template
To use a template to send an email to recipients, use the [SendTemplatedEmail](https://docs.aws.amazon.com/ses/latest/APIReference/API_SendTemplatedEmail.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$template_name = 'Template_Name';
$sender_email = 'email_address';
$recipient_emails = ['email_address'];
try {
$result = $SesClient->sendTemplatedEmail([
'Destination' => [
'ToAddresses' => $recipient_emails,
],
'ReplyToAddresses' => [$sender_email],
'Source' => $sender_email,
'Template' => $template_name,
'TemplateData' => '{ }'
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Managing email filters using the Amazon SES API and the AWS SDK for PHP Version 3
In addition to sending emails, you can also receive email with Amazon Simple Email Service (Amazon SES). An IP address filter enables you to optionally specify whether to accept or reject mail that originates from an IP address or range of IP addresses. For more information, see [Managing IP Address Filters for Amazon SES Email Receiving](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-managing-ip-filters.html).
The following examples show how to:
+ Create an email filter using [CreateReceiptFilter](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#createreceiptfilter).
+ List all email filters using [ListReceiptFilters](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#listreceiptfilters).
+ Remove an email filter using [DeleteReceiptFilter](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#deletereceiptfilter).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using Amazon SES, see the [Amazon SES Developer Guide](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/).
## Create an email filter
To allow or block emails from a specific IP address, use the [CreateReceiptFilter](https://docs.aws.amazon.com/ses/latest/APIReference/API_CreateReceiptFilter.html) operation. Provide the IP address or range of addresses and a unique name to identify this filter.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$filter_name = 'FilterName';
$ip_address_range = '10.0.0.1/24';
try {
$result = $SesClient->createReceiptFilter([
'Filter' => [
'IpFilter' => [
'Cidr' => $ip_address_range,
'Policy' => 'Block|Allow',
],
'Name' => $filter_name,
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## List all email filters
To list the IP address filters associated with your AWS account in the current AWS Region, use the [ListReceiptFilters](https://docs.aws.amazon.com/ses/latest/APIReference/API_ListReceiptFilters.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
try {
$result = $SesClient->listReceiptFilters();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Delete an email filter
To remove an existing filter for a specific IP address use the [DeleteReceiptFilter](https://docs.aws.amazon.com/ses/latest/APIReference/API_DeleteReceiptFilter.html) operation. Provide the unique filter name to identify the receipt filter to delete.
If you need to change the range of addresses that are filtered, you can delete a receipt filter and create a new one.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$filter_name = 'FilterName';
try {
$result = $SesClient->deleteReceiptFilter([
'FilterName' => $filter_name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Creating and managing email rules using the Amazon SES API and the AWS SDK for PHP Version 3
In addition to sending emails, you can also receive email with Amazon Simple Email Service (Amazon SES). Receipt rules enable you to specify what Amazon SES does with email it receives for the email addresses or domains you own. A rule can send email to other AWS services including but not limited to Amazon S3, Amazon SNS, or AWS Lambda.
For more information, see [Managing receipt rule sets for Amazon SES Email Receiving](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-managing-receipt-rule-sets.html) and [Managing Receipt Rules for Amazon SES Email Receiving](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-managing-receipt-rules.html).
The following examples show how to:
+ Create a receipt rule set using [CreateReceiptRuleSet](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#createreceiptruleset).
+ Create a receipt rule using [CreateReceiptRule](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#createreceiptrule).
+ Describe a receipt rule set using [DescribeReceiptRuleSet](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#describereceiptruleset).
+ Describe a receipt rule using [DescribeReceiptRule](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#describereceiptrule).
+ List all receipt rule sets using [ListReceiptRuleSets](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#listreceiptrulesets).
+ Update a receipt rule using [UpdateReceiptRule](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#updatereceiptrule).
+ Remove a receipt rule using [DeleteReceiptRule](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#deletereceiptrule).
+ Remove a receipt rule set using [DeleteReceiptRuleSet](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#deletereceiptruleset).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using Amazon SES, see the [Amazon SES Developer Guide](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/).
## Create a receipt rule set
A receipt rule set contains a collection of receipt rules. You must have at least one receipt rule set associated with your account before you can create a receipt rule. To create a receipt rule set, provide a unique RuleSetName and use the [CreateReceiptRuleSet](https://docs.aws.amazon.com/ses/latest/APIReference/API_CreateReceiptRuleSet.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$name = 'Rule_Set_Name';
try {
$result = $SesClient->createReceiptRuleSet([
'RuleSetName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Create a receipt rule
Control your incoming email by adding a receipt rule to an existing receipt rule set. This example shows you how to create a receipt rule that sends incoming messages to an Amazon S3 bucket, but you can also send messages to Amazon SNS and AWS Lambda. To create a receipt rule, provide a rule and the RuleSetName to the [CreateReceiptRule](https://docs.aws.amazon.com/ses/latest/APIReference/API_CreateReceiptRule.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$rule_name = 'Rule_Name';
$rule_set_name = 'Rule_Set_Name';
$s3_bucket = 'Bucket_Name';
try {
$result = $SesClient->createReceiptRule([
'Rule' => [
'Actions' => [
[
'S3Action' => [
'BucketName' => $s3_bucket,
],
],
],
'Name' => $rule_name,
'ScanEnabled' => true,
'TlsPolicy' => 'Optional',
'Recipients' => ['']
],
'RuleSetName' => $rule_set_name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Describe a receipt rule set
Once per second, return the details of the specified receipt rule set. To use the [DescribeReceiptRuleSet](https://docs.aws.amazon.com/ses/latest/APIReference/API_DescribeReceiptRuleSet.html) operation, provide the RuleSetName.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$name = 'Rule_Set_Name';
try {
$result = $SesClient->describeReceiptRuleSet([
'RuleSetName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Describe a receipt rule
Return the details of a specified receipt rule. To use the [DescribeReceiptRule](https://docs.aws.amazon.com/ses/latest/APIReference/API_DescribeReceiptRule.html) operation, provide the RuleName and RuleSetName.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$rule_name = 'Rule_Name';
$rule_set_name = 'Rule_Set_Name';
try {
$result = $SesClient->describeReceiptRule([
'RuleName' => $rule_name,
'RuleSetName' => $rule_set_name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## List all receipt rule sets
To list the receipt rule sets that exist under your AWS account in the current AWS Region, use the [ListReceiptRuleSets](https://docs.aws.amazon.com/ses/latest/APIReference/API_ListReceiptRuleSets.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
try {
$result = $SesClient->listReceiptRuleSets();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Update a receipt rule
This example shows you how to update a receipt rule that sends incoming messages to an AWS Lambda function, but you can also send messages to Amazon SNS and Amazon S3. To use the [UpdateReceiptRule](https://docs.aws.amazon.com/ses/latest/APIReference/API_UpdateReceiptRule.html) operation, provide the new receipt rule and the RuleSetName.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$rule_name = 'Rule_Name';
$rule_set_name = 'Rule_Set_Name';
$lambda_arn = 'Amazon Resource Name (ARN) of the AWS Lambda function';
$sns_topic_arn = 'Amazon Resource Name (ARN) of the Amazon SNS topic';
try {
$result = $SesClient->updateReceiptRule([
'Rule' => [
'Actions' => [
'LambdaAction' => [
'FunctionArn' => $lambda_arn,
'TopicArn' => $sns_topic_arn,
],
],
'Enabled' => true,
'Name' => $rule_name,
'ScanEnabled' => false,
'TlsPolicy' => 'Require',
],
'RuleSetName' => $rule_set_name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Delete a receipt rule set
Remove a specified receipt rule set that isn’t currently disabled. This also deletes all of the receipt rules it contains. To delete a receipt rule set, provide the RuleSetName to the [DeleteReceiptRuleSet](https://docs.aws.amazon.com/ses/latest/APIReference/API_DeleteReceiptRuleSet.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$name = 'Rule_Set_Name';
try {
$result = $SesClient->deleteReceiptRuleSet([
'RuleSetName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Delete a receipt rule
To delete a specified receipt rule, provide the RuleName and RuleSetName to the [DeleteReceiptRule](https://docs.aws.amazon.com/ses/latest/APIReference/API_DeleteReceiptRule.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
```
**Sample Code**
```
$SesClient = new Aws\Ses\SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-2'
]);
$rule_name = 'Rule_Name';
$rule_set_name = 'Rule_Set_Name';
try {
$result = $SesClient->deleteReceiptRule([
'RuleName' => $rule_name,
'RuleSetName' => $rule_set_name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Monitoring your sending activity using the Amazon SES API and the AWS SDK for PHP Version 3
Amazon Simple Email Service (Amazon SES) provides methods for monitoring your sending activity. We recommend that you implement these methods so that you can keep track of important measures, such as your account’s bounce, complaint, and reject rates. Excessively high bounce and complaint rates can jeopardize your ability to send emails using Amazon SES.
The following examples show how to:
+ Check your sending quota using [GetSendQuota](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#getsendquota).
+ Monitor your sending activity using [GetSendStatistics](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#getsendstatistics).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using Amazon SES, see the [Amazon SES Developer Guide](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/).
## Check your sending quota
You are limited to sending only a certain amount of messages in a single 24-hour period. To check how many messages you are still allowed to send, use the [GetSendQuota](https://docs.aws.amazon.com/ses/latest/APIReference/API_GetSendQuota.html) operation. For more information, see [Managing Your Amazon SES Sending Limits](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/manage-sending-limits.html).
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Ses\SesClient;
```
**Sample Code**
```
$SesClient = new SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-1'
]);
try {
$result = $SesClient->getSendQuota();
$send_limit = $result["Max24HourSend"];
$sent = $result["SentLast24Hours"];
$available = $send_limit - $sent;
print("You can send " . $available . " more messages in the next 24 hours.
");
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Monitor your sending activity
To retrieve metrics for messages you’ve sent in the past two weeks, use the [GetSendStatistics](https://docs.aws.amazon.com/ses/latest/APIReference/API_GetSendStatistics.html) operation. This example returns the number of delivery attempts, bounces, complaints, and rejected messages in 15-minute increments.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Ses\SesClient;
```
**Sample Code**
```
$SesClient = new SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-1'
]);
try {
$result = $SesClient->getSendStatistics();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Authorizing senders using the Amazon SES API and the AWS SDK for PHP Version 3
To enable another AWS account, AWS Identity and Access Management user, or AWS service to send email through Amazon Simple Email Service (Amazon SES) on your behalf, you create a sending authorization policy. This is a JSON document that you attach to an identity that you own.
The policy expressly lists who you are allowing to send for that identity, and under which conditions. All senders, other than you and the entities you explicitly grant permissions to in the policy, are not allowed to send emails. An identity can have no policy, one policy, or multiple policies attached to it. You can also have one policy with multiple statements to achieve the effect of multiple policies.
For more information, see [Using Sending Authorization with Amazon SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-authorization.html).
The following examples show how to:
+ Create an authorized sender using [PutIdentityPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#createidentitypolicy).
+ Retrieve polices for an authorized sender using [GetIdentityPolicies](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#getidentitypolicies).
+ List authorized senders using [ListIdentityPolicies](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#listidentitypolicies).
+ Revoke permission for an authorized sender using [DeleteIdentityPolicy](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2010-12-01.html#deleteidentitypolicy).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
For more information about using Amazon SES, see the [Amazon SES Developer Guide](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/).
## Create an authorized sender
To authorize another AWS account to send emails on your behalf, use an identity policy to add or update authorization to send emails from your verified email addresses or domains. To create an identity policy, use the [PutIdentityPolicy](https://docs.aws.amazon.com/ses/latest/APIReference/API_PutIdentityPolicy.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Ses\SesClient;
```
**Sample Code**
```
$SesClient = new SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-1'
]);
$identity = "arn:aws:ses:us-east-1:123456789012:identity/example.com";
$other_aws_account = "0123456789";
$policy = <<putIdentityPolicy([
'Identity' => $identity,
'Policy' => $policy,
'PolicyName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Retrieve polices for an authorized sender
Return the sending authorization policies that are associated with a specific email identity or domain identity. To get the sending authorization for a given email address or domain, use the [GetIdentityPolicy](https://docs.aws.amazon.com/ses/latest/APIReference/API_GetIdentityPolicy.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Ses\SesClient;
```
**Sample Code**
```
$SesClient = new SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-1'
]);
$identity = "arn:aws:ses:us-east-1:123456789012:identity/example.com";
$policies = ["policyName"];
try {
$result = $SesClient->getIdentityPolicies([
'Identity' => $identity,
'PolicyNames' => $policies,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## List authorized senders
To list the sending authorization policies that are associated with a specific email identity or domain identity in the current AWS Region, use the [ListIdentityPolicies](https://docs.aws.amazon.com/ses/latest/APIReference/API_ListIdentityPolicies.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Ses\SesClient;
```
**Sample Code**
```
$SesClient = new SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-1'
]);
$identity = "arn:aws:ses:us-east-1:123456789012:identity/example.com";
try {
$result = $SesClient->listIdentityPolicies([
'Identity' => $identity,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
## Revoke permission for an authorized sender
Remove sending authorization for another AWS account to send emails with an email identity or domain identity by deleting the associated identity policy with the [DeleteIdentityPolicy](https://docs.aws.amazon.com/ses/latest/APIReference/API_DeleteIdentityPolicy.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Ses\SesClient;
```
**Sample Code**
```
$SesClient = new SesClient([
'profile' => 'default',
'version' => '2010-12-01',
'region' => 'us-east-1'
]);
$identity = "arn:aws:ses:us-east-1:123456789012:identity/example.com";
$name = "policyName";
try {
$result = $SesClient->deleteIdentityPolicy([
'Identity' => $identity,
'PolicyName' => $name,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
echo $e->getMessage();
echo "\n";
}
```
# Amazon SNS examples using the AWS SDK for PHP Version 3
Amazon Simple Notification Service (Amazon SNS) is a web service that coordinates and manages the delivery or sending of messages to subscribing endpoints or clients.
In Amazon SNS, there are two types of clients: publishers (also referred to as producers) and subscribers (also referred to as consumers). Publishers communicate asynchronously with subscribers by producing and sending a message to a topic, which is a logical access point and communication channel. Subscribers (web servers, email addresses, Amazon SQS queues, AWS Lambda functions) consume or receive the message or notification over one of the supported protocols (Amazon SQS, HTTP/HTTPS URLs, email, AWS SMS, Lambda) when they are subscribed to the topic.
All the example code for the AWS SDK for PHP Version 3 is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
**Topics**
+ [Managing topics](sns-examples-managing-topics.md)
+ [Managing subscriptions](sns-examples-subscribing-unsubscribing-topics.md)
+ [Sending amazon SMS messages](sns-examples-sending-sms.md)
# Managing topics in Amazon SNS with the AWS SDK for PHP Version 3
To send notifications to Amazon Simple Queue Service (Amazon SQS), HTTP/HTTPS URLs, email, AWS SMS, or AWS Lambda, you must first create a topic that manages the delivery of messages to any subscribers of that topic.
In terms of the observer design pattern, a topic is like the subject. After a topic is created, you add subscribers that are notified automatically when a message is published to the topic.
Learn more about subscribing to topics in [Managing Subscriptions in Amazon SNS with AWS SDK for PHP Version 3](sns-examples-subscribing-unsubscribing-topics.md).
The following examples show how to:
+ Create a topic to publish notifications to using [CreateTopic](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#createtopic).
+ Return a list of the requester’s topics using [ListTopics](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#listtopic).
+ Delete a topic and all of its subscriptions using [DeleteTopic](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#deletetopic).
+ Return all of the properties of a topic using [GetTopicAttributes](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#gettopicattributes).
+ Allow a topic owner to set an attribute of the topic to a new value using [SetTopicAttributes](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#settopicattributes).
For more information about using Amazon SNS, see [Amazon SNS Topic Attributes for Message Delivery Status](https://docs.aws.amazon.com/sns/latest/dg/sns-topic-attributes.html).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Create a topic
To create a topic, use the [CreateTopic](https://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html) operation.
Each topic name in your AWS account must be unique.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$topicname = 'myTopic';
try {
$result = $SnSclient->createTopic([
'Name' => $topicname,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## List your topics
To list up to 100 existing topics in the current AWS Region, use the [ListTopics](https://docs.aws.amazon.com/sns/latest/api/API_ListTopics.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
try {
$result = $SnSclient->listTopics();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Delete a topic
To remove an existing topic and all of its subscriptions, use the [DeleteTopic](https://docs.aws.amazon.com/sns/latest/api/API_DeleteTopic.html) operation.
Any messages that have not been delivered yet to subscribers will also be deleted.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->deleteTopic([
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Get topic attributes
To retrieve properties of a single existing topic, use the [GetTopicAttributes](https://docs.aws.amazon.com/sns/latest/api/API_GetTopicAttributes.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->getTopicAttributes([
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Set topic attributes
To update properties of a single existing topic, use the [SetTopicAttributes](https://docs.aws.amazon.com/sns/latest/api/API_SetTopicAttributes.html) operation.
You can set only the `Policy`, `DisplayName`, and `DeliveryPolicy` attributes.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$attribute = 'Policy | DisplayName | DeliveryPolicy';
$value = 'First Topic';
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->setTopicAttributes([
'AttributeName' => $attribute,
'AttributeValue' => $value,
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Managing subscriptions in Amazon SNS with AWS SDK for PHP Version 3
Use Amazon Simple Notification Service (Amazon SNS) topics to send notifications to Amazon Simple Queue Service (Amazon SQS), HTTP/HTTPS, email addresses, AWS Server Migration Service (AWS SMS), or AWS Lambda.
Subscriptions are attached to a topic that manages sending messages to subscribers. Learn more about creating topics in [Managing Topics in Amazon SNS with the AWS SDK for PHP Version 3](sns-examples-managing-topics.md).
The following examples show how to:
+ Subscribe to an existing topic using [Subscribe](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#subscribe).
+ Verify a subscription using [ConfirmSubscription](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#confirmsubscription).
+ List existing subscriptions using [ListSubscriptionsByTopic](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#listsubscriptionsbytopic).
+ Delete a subscription using [Unsubscribe](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#unsubscribe).
+ Send a message to all subscribers of a topic using [Publish](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#publish).
For more information about using Amazon SNS, see [Using Amazon SNS for System-to-System Messaging](https://docs.aws.amazon.com/sns/latest/dg/sns-system-to-system-messaging.html).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Subscribe an email address to a topic
To initiate a subscription to an email address, use the [Subscribe](https://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html) operation.
You can use the subscribe method to subscribe several different endpoints to an Amazon SNS topic, depending on the values used for parameters passed. This is shown in other examples in this topic.
In this example, the endpoint is an email address. A confirmation token is sent to this email. Verify the subscription with this confirmation token within three days of receipt.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$protocol = 'email';
$endpoint = 'sample@example.com';
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->subscribe([
'Protocol' => $protocol,
'Endpoint' => $endpoint,
'ReturnSubscriptionArn' => true,
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Subscribe an application endpoint to a topic
To initiate a subscription to a web app, use the [Subscribe](https://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html) operation.
You can use the subscribe method to subscribe several different endpoints to an Amazon SNS topic, depending on the values used for parameters passed. This is shown in other examples in this topic.
In this example, the endpoint is a URL. A confirmation token is sent to this web address. Verify the subscription with this confirmation token within three days of receipt.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$protocol = 'https';
$endpoint = 'https://';
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->subscribe([
'Protocol' => $protocol,
'Endpoint' => $endpoint,
'ReturnSubscriptionArn' => true,
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Subscribe a Lambda function to a topic
To initiate a subscription to a Lambda function, use the [Subscribe](https://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html) operation.
You can use the subscribe method to subscribe several different endpoints to an Amazon SNS topic, depending on the values used for parameters passed. This is shown in other examples in this topic.
In this example, the endpoint is a Lambda function. A confirmation token is sent to this Lambda function. Verify the subscription with this confirmation token within three days of receipt.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$protocol = 'lambda';
$endpoint = 'arn:aws:lambda:us-east-1:123456789023:function:messageStore';
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->subscribe([
'Protocol' => $protocol,
'Endpoint' => $endpoint,
'ReturnSubscriptionArn' => true,
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Subscribe a text SMS to a topic
To send SMS messages to multiple phone numbers at the same time, subscribe each number to a topic.
To initiate a subscription to a phone number, use the [Subscribe](https://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html) operation.
You can use the subscribe method to subscribe several different endpoints to an Amazon SNS topic, depending on the values used for parameters passed. This is shown in other examples in this topic.
In this example, the endpoint is a phone number in E.164 format, a standard for international telecommunications.
A confirmation token is sent to this phone number. Verify the subscription with this confirmation token within three days of receipt.
For an alternative way to send SMS messages with Amazon SNS, see [Sending SMS Messages in Amazon SNS with the AWS SDK for PHP Version 3](sns-examples-sending-sms.md).
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$protocol = 'sms';
$endpoint = '+1XXX5550100';
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->subscribe([
'Protocol' => $protocol,
'Endpoint' => $endpoint,
'ReturnSubscriptionArn' => true,
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Confirm subscription to a topic
To actually create a subscription, the endpoint owner must acknowledge intent to receive messages from the topic using a token sent when a subscription is established initially, as described earlier. Confirmation tokens are valid for three days. After three days, you can resend a token by creating a new subscription.
To confirm a subscription, use the [ConfirmSubscription](https://docs.aws.amazon.com/sns/latest/api/API_ConfirmSubscription.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$subscription_token = 'arn:aws:sns:us-east-1:111122223333:MyTopic:123456-abcd-12ab-1234-12ba3dc1234a';
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->confirmSubscription([
'Token' => $subscription_token,
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## List subscriptions to a topic
To list up to 100 existing subscriptions in a given AWS Region, use the [ListSubscriptions](https://docs.aws.amazon.com/sns/latest/api/API_ListSubscriptions.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
try {
$result = $SnSclient->listSubscriptions();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Unsubscribe from a topic
To remove an endpoint subscribed to a topic, use the [Unsubscribe](https://docs.aws.amazon.com/sns/latest/api/API_Unsubscribe.html) operation.
If the subscription requires authentication for deletion, only the owner of the subscription or the topic’s owner can unsubscribe, and an AWS signature is required. If the unsubscribe call doesn’t require authentication and the requester isn’t the subscription owner, a final cancellation message is delivered to the endpoint.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$subscription = 'arn:aws:sns:us-east-1:111122223333:MySubscription';
try {
$result = $SnSclient->unsubscribe([
'SubscriptionArn' => $subscription,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Publish a message to an Amazon SNS topic
To deliver a message to each endpoint that’s subscribed to an Amazon SNS topic, use the [Publish](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html) operation.
Create an object that contains the parameters for publishing a message, including the message text and the Amazon Resource Name (ARN) of the Amazon SNS topic.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$message = 'This message is sent from a Amazon SNS code sample.';
$topic = 'arn:aws:sns:us-east-1:111122223333:MyTopic';
try {
$result = $SnSclient->publish([
'Message' => $message,
'TopicArn' => $topic,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Sending SMS messages in Amazon SNS with the AWS SDK for PHP Version 3
You can use Amazon Simple Notification Service (Amazon SNS) to send text messages, or SMS messages, to SMS-enabled devices. You can send a message directly to a phone number, or you can send a message to multiple phone numbers at once by subscribing those phone numbers to a topic and sending your message to the topic.
Use Amazon SNS to specify preferences for SMS messaging, such as how your deliveries are optimized (for cost or for reliable delivery), your monthly spending limit, how message deliveries are logged, and whether to subscribe to daily SMS usage reports. These preferences are retrieved and set as SMS attributes for Amazon SNS.
When you send an SMS message, specify the phone number using the E.164 format. E.164 is a standard for the phone number structure used for international telecommunications. Phone numbers that follow this format can have a maximum of 15 digits, and are prefixed with the plus character (\$1) and the country code. For example, a US phone number in E.164 format would appear as \$11001XXX5550100.
The following examples show how to:
+ Retrieve the default settings for sending SMS messages from your account using [GetSMSAttributes](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#getsmsattributes).
+ Update the default settings for sending SMS messages from your account using [SetSMSAttributes](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#setsmsattributes).
+ Discover if a given phone number owner has opted out of receiving SMS messages from your account using [CheckIfPhoneNumberISOptedOut](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#checkifphonenumberisoptedout).
+ List phone numbers where the owner has opted out of receiving SMS messages from your account using [ListPhoneNumberOptedOut](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#listphonenumbersoptedout).
+ Send a text message (SMS message) directly to a phone number using [Publish](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sns-2010-03-31.html#publish).
For more information about using Amazon SNS, see [Using Amazon SNS for User Notifications with a Mobile Phone Number as a Subscriber (Send SMS)](https://docs.aws.amazon.com/sns/latest/dg/sns-mobile-phone-number-as-subscriber.html).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Get SMS attributes
To retrieve the default settings for SMS messages, use the [GetSMSAttributes](https://docs.aws.amazon.com/sns/latest/api/API_GetSMSAttributes.html) operation.
This example gets the `DefaultSMSType` attribute. This attribute controls whether SMS messages are sent as `Promotional`, which optimizes message delivery to incur the lowest cost, or as `Transactional`, which optimizes message delivery to achieve the highest reliability.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
try {
$result = $SnSclient->getSMSAttributes([
'attributes' => ['DefaultSMSType'],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Set SMS attributes
To update the default settings for SMS messages, use the [SetSMSAttributes](https://docs.aws.amazon.com/sns/latest/api/API_SetSMSAttributes.html) operation.
This example sets the `DefaultSMSType` attribute to `Transactional`, which optimizes message delivery to achieve the highest reliability.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
try {
$result = $SnSclient->SetSMSAttributes([
'attributes' => [
'DefaultSMSType' => 'Transactional',
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Check if a phone number has opted out
To determine if a given phone number owner has opted out of receiving SMS messages from your account, use the [CheckIfPhoneNumberIsOptedOut](https://docs.aws.amazon.com/sns/latest/api/API_CheckIfPhoneNumberIsOptedOut.html) operation.
In this example, the phone number is in E.164 format, a standard for international telecommunications.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$phone = '+1XXX5550100';
try {
$result = $SnSclient->checkIfPhoneNumberIsOptedOut([
'phoneNumber' => $phone,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## List opted-out phone numbers
To retrieve a list of phone numbers where the owner has opted out of receiving SMS messages from your account, use the [ListPhoneNumbersOptedOut](https://docs.aws.amazon.com/sns/latest/api/API_ListPhoneNumbersOptedOut.html) operation.
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
try {
$result = $SnSclient->listPhoneNumbersOptedOut();
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Publish to a text message (SMS message)
To deliver a text message (SMS message) directly to a phone number, use the [Publish](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html) operation.
In this example, the phone number is in E.164 format, a standard for international telecommunications.
SMS messages can contain up to 140 bytes. The size limit for a single SMS publish action is 1,600 bytes.
For more details on sending SMS messages, see [Sending an SMS Message](https://docs.aws.amazon.com/sns/latest/dg/sms_publish-to-phone.html).
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sns\SnsClient;
```
**Sample Code**
```
$SnSclient = new SnsClient([
'profile' => 'default',
'region' => 'us-east-1',
'version' => '2010-03-31'
]);
$message = 'This message is sent from a Amazon SNS code sample.';
$phone = '+1XXX5550100';
try {
$result = $SnSclient->publish([
'Message' => $message,
'PhoneNumber' => $phone,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Amazon SQS examples using the AWS SDK for PHP Version 3
Amazon Simple Queue Service (SQS) is a fast, reliable, scalable, fully managed message queuing service. Amazon SQS lets you decouple the components of a cloud application. Amazon SQS includes standard queues with high throughput and at-least-once processing, and FIFO queues that provide FIFO (first>-in, first>-out) delivery and exactly-once processing.
All the example code for the AWS SDK for PHP Version 3 is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
**Topics**
+ [Enabling long polling](sqs-examples-enable-long-polling.md)
+ [Managing visibility timeout](sqs-examples-managing-visibility-timeout.md)
+ [Sending and receiving messages](sqs-examples-send-receive-messages.md)
+ [Using dead-letter queues](sqs-examples-dead-letter-queues.md)
+ [Using queues](sqs-examples-using-queues.md)
# Enabling long polling in Amazon SQS with AWS SDK for PHP Version 3
Long polling reduces the number of empty responses by allowing Amazon SQS to wait a specified time for a message to become available in the queue before sending a response. Also, long polling eliminates false empty responses by querying all of the servers instead of a sampling of servers. To enable long polling, specify a non-zero wait time for received messages. To learn more, see [SQS Long Polling](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-long-polling.html).
The following examples show how to:
+ Set attributes on an Amazon SQS queue to enable long polling, using [SetQueueAttributes](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#setqueueattributes).
+ Retrieve one or more messages with long polling using [ReceiveMessage](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#receivemessage).
+ Create a long polling queue using [CreateQueue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#createqueue).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Set attributes on a queue to enable long polling
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$queueUrl = "QUEUE_URL";
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
try {
$result = $client->setQueueAttributes([
'Attributes' => [
'ReceiveMessageWaitTimeSeconds' => 20
],
'QueueUrl' => $queueUrl, // REQUIRED
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Retrieve messages with long polling
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$queueUrl = "QUEUE_URL";
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
try {
$result = $client->receiveMessage([
'AttributeNames' => ['SentTimestamp'],
'MaxNumberOfMessages' => 1,
'MessageAttributeNames' => ['All'],
'QueueUrl' => $queueUrl, // REQUIRED
'WaitTimeSeconds' => 20,
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Create a queue with long polling
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$queueName = "QUEUE_NAME";
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
try {
$result = $client->createQueue([
'QueueName' => $queueName,
'Attributes' => [
'ReceiveMessageWaitTimeSeconds' => 20
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Managing visibility timeout in Amazon SQS with AWS SDK for PHP Version 3
A visibility timeout is a period of time during which Amazon SQS prevents other consuming components from receiving and processing a message. To learn more, see [Visibility Timeout](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html).
The following example shows how to:
+ Change the visibility timeout of specified messages in a queue to new values, using [ChangeMessageVisibilityBatch](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#changemessagevisibilitybatch).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Change the visibility timeout of multiple messages
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$queueUrl = "QUEUE_URL";
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
try {
$result = $client->receiveMessage(array(
'AttributeNames' => ['SentTimestamp'],
'MaxNumberOfMessages' => 10,
'MessageAttributeNames' => ['All'],
'QueueUrl' => $queueUrl, // REQUIRED
));
$messages = $result->get('Messages');
if ($messages != null) {
$entries = array();
for ($i = 0; $i < count($messages); $i++) {
$entries[] = [
'Id' => 'unique_is_msg' . $i, // REQUIRED
'ReceiptHandle' => $messages[$i]['ReceiptHandle'], // REQUIRED
'VisibilityTimeout' => 3600
];
}
$result = $client->changeMessageVisibilityBatch([
'Entries' => $entries,
'QueueUrl' => $queueUrl
]);
var_dump($result);
} else {
echo "No messages in queue \n";
}
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Sending and receiving messages in Amazon SQS with AWS SDK for PHP Version 3
To learn about Amazon SQS messages, see [Sending a Message to an SQS Queue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-send-message.html) and [Receiving and Deleting a Message from an SQS Queue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-receive-delete-message.html.html) in the Service Quotas User Guide.
The following examples show how to:
+ Deliver a message to a specified queue using [SendMessage](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#sendmessage).
+ Retrieve one or more messages (up to 10) from a specified queue using [ReceiveMessage](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#receivemessage).
+ Delete a message from a queue using [DeleteMessage](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#deletemessage).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Send a message
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
$params = [
'DelaySeconds' => 10,
'MessageAttributes' => [
"Title" => [
'DataType' => "String",
'StringValue' => "The Hitchhiker's Guide to the Galaxy"
],
"Author" => [
'DataType' => "String",
'StringValue' => "Douglas Adams."
],
"WeeksOn" => [
'DataType' => "Number",
'StringValue' => "6"
]
],
'MessageBody' => "Information about current NY Times fiction bestseller for week of 12/11/2016.",
'QueueUrl' => 'QUEUE_URL'
];
try {
$result = $client->sendMessage($params);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Receive and delete messages
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$queueUrl = "QUEUE_URL";
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
try {
$result = $client->receiveMessage([
'AttributeNames' => ['SentTimestamp'],
'MaxNumberOfMessages' => 1,
'MessageAttributeNames' => ['All'],
'QueueUrl' => $queueUrl, // REQUIRED
'WaitTimeSeconds' => 0,
]);
if (!empty($result->get('Messages'))) {
var_dump($result->get('Messages')[0]);
$result = $client->deleteMessage([
'QueueUrl' => $queueUrl, // REQUIRED
'ReceiptHandle' => $result->get('Messages')[0]['ReceiptHandle'] // REQUIRED
]);
} else {
echo "No messages in queue. \n";
}
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Using dead-letter queues in Amazon SQS with AWS SDK for PHP Version 3
A dead-letter queue is one that other (source) queues can target for messages that can’t be processed successfully. You can set aside and isolate these messages in the dead-letter queue to determine why their processing did not succeed. You must individually configure each source queue that sends messages to a dead-letter queue. Multiple queues can target a single dead-letter queue.
To learn more, see [Using SQS Dead Letter Queues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html).
The following example shows how to:
+ Enable a dead-letter queue using [SetQueueAttributes](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#setqueueattributes).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Enable a dead-letter queue
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$queueUrl = "QUEUE_URL";
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
try {
$result = $client->setQueueAttributes([
'Attributes' => [
'RedrivePolicy' => "{\"deadLetterTargetArn\":\"DEAD_LETTER_QUEUE_ARN\",\"maxReceiveCount\":\"10\"}"
],
'QueueUrl' => $queueUrl // REQUIRED
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Using queues in Amazon SQS with AWS SDK for PHP Version 3
To learn about Amazon SQS queues, see [How SQS Queues Work](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-how-it-works.html).
The following examples show how to:
+ Return a list of your queues using [ListQueues](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#listqueues).
+ Create a new queue using [CreateQueue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#createqueue).
+ Return the URL of an existing queue using [GetQueueUrl](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#getqueueurl).
+ Delete a specified queue using [DeleteQueue](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sqs-2012-11-05.html#deletequeue).
All the example code for the AWS SDK for PHP is available [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code).
## Credentials
Before running the example code, configure your AWS credentials, as described in [Authenticating with AWS using AWS SDK for PHP Version 3](credentials.md). Then import the AWS SDK for PHP, as described in [Installing the AWS SDK for PHP Version 3](getting-started_installation.md).
## Return a list of queues
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
try {
$result = $client->listQueues();
foreach ($result->get('QueueUrls') as $queueUrl) {
echo "$queueUrl\n";
}
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Create a queue
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$queueName = "SQS_QUEUE_NAME";
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
try {
$result = $client->createQueue([
'QueueName' => $queueName,
'Attributes' => [
'DelaySeconds' => 5,
'MaximumMessageSize' => 4096, // 4 KB
],
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Return the URL of a queue
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$queueName = "SQS_QUEUE_NAME";
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
try {
$result = $client->getQueueUrl([
'QueueName' => $queueName // REQUIRED
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
## Delete a queue
**Imports**
```
require 'vendor/autoload.php';
use Aws\Exception\AwsException;
use Aws\Sqs\SqsClient;
```
**Sample Code**
```
$queueUrl = "SQS_QUEUE_URL";
$client = new SqsClient([
'profile' => 'default',
'region' => 'us-west-2',
'version' => '2012-11-05'
]);
try {
$result = $client->deleteQueue([
'QueueUrl' => $queueUrl // REQUIRED
]);
var_dump($result);
} catch (AwsException $e) {
// output error message if fails
error_log($e->getMessage());
}
```
# Send events to Amazon EventBridge global endpoints using the AWS SDK for PHP Version 3
You can use [Amazon EventBridge global endpoints](https://docs.aws.amazon.com//eventbridge/latest/userguide/eb-global-endpoints.html) to improve the availability and reliability of your event-driven applications.
After the EventBridge global endpoint is [set up](https://docs.aws.amazon.com//eventbridge/latest/userguide/eb-global-endpoints.html#eb-ge-create-endpoint), you can send events to it by using the SDK for PHP.
**Important**
To use EventBridge global endpoints with the SDK for PHP, your PHP environment must have the [AWS Common Runtime (AWS CRT) extension](guide_crt.md) installed.
The following example uses the [PutEvents](https://docs.aws.amazon.com//aws-sdk-php/v3/api/api-eventbridge-2015-10-07.html#putevents) method of the `EventBridgeClient` to send a single event to an EventBridge global endpoint.
```
'us-east-1'
]);
$endpointId = 'xxxx123456.xxx'; // Existing EventBridge global endpointId.
$eventBusName = 'default'; // Existing event bus in the us-east-1 Region.
$event = [
'Source' => 'my-php-app',
'DetailType' => 'test',
'Detail' => json_encode(['foo' => 'bar']),
'Time' => new DateTime(),
'Resources' => ['php-script'],
'EventBusName' => $eventBusName,
'TraceHeader' => 'test'
];
$result = $evClient->putEvents([
'EndpointId' => $endpointId,
'Entries' => [$event]
]);
```
[This blog post ](https://aws.amazon.com/blogs//compute/introducing-global-endpoints-for-amazon-eventbridge/) contains more information about EventBridge global endpoints.