适用于 PHP 的 AWS 开发工具包
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

从AWS SDK for PHP版本 2 升级

本主题展示如何迁移代码,以使用 AWS SDK for PHP 的版本 3,并介绍新版本与开发工具包版本 2 的不同之处。

注意

开发工具包的基本使用模式 (即 $result = $client->operation($params);) 从版本 2 到版本 3 并未改变,这样可确保顺利迁移。

介绍

AWS SDK for PHP 版本 3 展示出我们为提升开发工具包的功能做出的巨大努力,其中涵盖了客户在两年多时间中提供的反馈,升级了我们的依赖项、提升了性能、并符合最新的 PHP 标准。

版本 3 中的新增功能?

AWS SDK for PHP版本 3 遵循 PSR-4 和 PSR-7 标准,今后将遵循 SemVer 标准。

其他新增功能包括

  • 用于自定义服务客户端行为的中间件系统

  • 灵活的分页工具,用于迭代分页结果

  • 能够利用 JMESPath结果分页工具对象查询数据

  • 通过 'debug' 配置选项轻松调试

分离的 HTTP 层

  • 默认使用 Guzzle 6 发送请求,但也支持 Guzzle 5。

  • 在 cURL 不可用的环境中开发工具包也可以工作。

  • 也支持自定义 HTTP 处理程序。

异步请求

  • Waiter分段上传工具等功能也可异步使用。

  • 使用 Promise 协同程序可创建异步工作流程。

  • 提升了并发或批处理请求的性能。

与版本 2 有何不同之处?

更新了项目依赖项

开发工具包在此版本中更改了依赖项。

  • 开发工具包现在需要使用 PHP 5.5+。可以自由地在开发工具包代码中使用生成器

  • 我们升级了开发工具包,以使用 Guzzle 6 (或 5),可提供底层 HTTP 客户端实施,开发工具包会用它向 AWS 服务发送请求。Guzzle 的最新版本引入了一系列改进,包括异步请求、可交换 HTTP 处理程序、PSR-7 合规性、更出色的性能等。

  • PHP-FIG 的 PSR-7 程序包 (psr/http-message) 定义代表 HTTP 请求、HTTP 响应、URL 和流的接口。这些接口是开发工具包和 Guzzle 通用的,可与兼容 PSR-7 的其他程序包互通。

  • Guzzle 的 PSR-7 实施 (guzzlehttp/psr7) 在 PSR-7 中提供接口实施,还提供若干有用的类和函数。开发工具包和 Guzzle 6 均在很大程度上依赖这个程序包。

  • Guzzle 的 Promises/A+ 实施 (guzzlehttp/promises) 是开发工具包和 Guzzle 通用的,可提供管理异步请求和协同程序的接口。Guzzle 的多 cURL HTTP 处理程序最终会实施支持异步请求的非阻塞 I/O 模型,此程序包能够在该范例中进行编程。有关更多详细信息,请参阅适用于 PHP 的 AWS 开发工具包版本 3 中的 Promise

  • 开发工具包中使用 JMESPath 的 PHP 实施 (mtdowling/jmespath.php),用于提供 Aws\Result::search()Aws\ResultPaginator::search() 方法的数据查询功能。有关更多详细信息,请参阅适用于 PHP 的 AWS 开发工具包版本 3 中的 JMESPath 表达式

现在要求提供区域和版本选项

如果要将任何服务的客户端实例化,请指定 'region''version' 选项。在AWS SDK for PHP版本 2 中,'version' 完全是可选选项,'region' 有时是可选选项。在版本 3 中,这两个选项都是必需的。显式提供这两个选项可以锁定您编写代码的 API 版本和 AWS 区域。如果创建了新的 API 版本,或提供了新的 AWS 区域,会将可能造成崩溃的更改与您隔离,直到您已做好显式更新配置的准备。

注意

如果您不关心所用的 API 版本,只需将 'version' 选项设为 'latest'。但是,我们建议您针对生产代码显式设置 API 版本号。

并非所有服务都会在所有 AWS 区域中提供。您可以参考区域和终端节点,找到可用区域的列表。

对于仅通过单个全局终端节点(例如 Amazon Route 53、AWS Identity and Access Management 和 Amazon CloudFront)提供的服务,请实例化客户端,并将其配置的区域设置为 us-east-1

重要

开发工具包中还包含多区域客户端,可根据作为命令参数提供的参数 (@region),将请求分派至不同的 AWS 区域。这些客户端默认使用的区域是由客户端构造函数提供的 region 选项指定的。

使用构造函数进行客户端实例化

在 AWS SDK for PHP 的版本 3 中,改变了客户端的实例化方式。您只需使用 factory 关键字即可将客户端实例化,而在版本 2 中需使用 new 方法。

use Aws\DynamoDb\DynamoDbClient; // Version 2 style $client = DynamoDbClient::factory([ 'region' => 'us-east-2' ]); // Version 3 style $client = new DynamoDbClient([ 'region' => 'us-east-2', 'version' => '2012-08-10' ]);

注意

仍可使用 factory() 方法将客户端实例化。但这种方法已被弃用。

客户端配置已更改

在 AWS SDK for PHP 版本 3 中的客户端配置选项与版本 2 稍有不同。请参阅适用于 PHP 的 AWS 开发工具包版本3 配置页面,查看所有支持的选项的描述。

重要

在版本 3 中,'key''secret' 不再是根级别的有效选项,但可以作为 'credentials' 选项的一部分进行传递。我们做出这种更改的原因是,反对开发人员将 AWS 凭证硬编码到项目中。

Sdk 对象

AWS SDK for PHP版本 3 引入了 Aws\Sdk 对象来替换 Aws\Common\AwsSdk 对象可作为客户端工厂,用于管理多个客户端的共享配置选项。

在开发工具包的版本 2 中,Aws 类就像一个服务定位器 (它总是会返回客户端的同一实例),而在版本 3 中,每次使用 Sdk 类均会返回客户端的一个新实例。

Sdk 对象也不支持与开发工具包版本 2 相同的配置文件格式。原来的配置格式是 Guzzle 3 的特定格式,现已过时。可利用基本数组更轻松地进行配置,配置方法在使用 Sdk 类中进行了记录。

更改了一些 API 结果

为了确保开发工具包解析 API 操作结果的方式具有一致性,Amazon ElastiCache、Amazon RDS 和 Amazon Redshift 现已针对一些 API 响应提供额外的包装元素。

例如,在版本 3 中调用 Amazon RDSDescribeEngineDefaultParameters 的结果会包含包装 "EngineDefaults" 元素。在版本 2 中没有此元素。

$client = new Aws\Rds\RdsClient([ 'region' => 'us-west-1', 'version' => '2014-09-01' ]); // Version 2 $result = $client->describeEngineDefaultParameters(); $family = $result['DBParameterGroupFamily']; $marker = $result['Marker']; // Version 3 $result = $client->describeEngineDefaultParameters(); $family = $result['EngineDefaults']['DBParameterGroupFamily']; $marker = $result['EngineDefaults']['Marker'];

以下操作会受到影响,在结果输出中会包含包装元素 (在下文的括号中提供):

  • Amazon ElastiCache

    • AuthorizeCacheSecurityGroupIngress (CacheSecurityGroup)

    • CopySnapshot (Snapshot)

    • CreateCacheCluster (CacheCluster)

    • CreateCacheParameterGroup (CacheParameterGroup)

    • CreateCacheSecurityGroup (CacheSecurityGroup)

    • CreateCacheSubnetGroup (CacheSubnetGroup)

    • CreateReplicationGroup (ReplicationGroup)

    • CreateSnapshot (Snapshot)

    • DeleteCacheCluster (CacheCluster)

    • DeleteReplicationGroup (ReplicationGroup)

    • DeleteSnapshot (Snapshot)

    • DescribeEngineDefaultParameters (EngineDefaults)

    • ModifyCacheCluster (CacheCluster)

    • ModifyCacheSubnetGroup (CacheSubnetGroup)

    • ModifyReplicationGroup (ReplicationGroup)

    • PurchaseReservedCacheNodesOffering (ReservedCacheNode)

    • RebootCacheCluster (CacheCluster)

    • RevokeCacheSecurityGroupIngress (CacheSecurityGroup)

  • Amazon RDS

    • AddSourceIdentifierToSubscription (EventSubscription)

    • AuthorizeDBSecurityGroupIngress (DBSecurityGroup)

    • CopyDBParameterGroup (DBParameterGroup)

    • CopyDBSnapshot (DBSnapshot)

    • CopyOptionGroup (OptionGroup)

    • CreateDBInstance (DBInstance)

    • CreateDBInstanceReadReplica (DBInstance)

    • CreateDBParameterGroup (DBParameterGroup)

    • CreateDBSecurityGroup (DBSecurityGroup)

    • CreateDBSnapshot (DBSnapshot)

    • CreateDBSubnetGroup (DBSubnetGroup)

    • CreateEventSubscription (EventSubscription)

    • CreateOptionGroup (OptionGroup)

    • DeleteDBInstance (DBInstance)

    • DeleteDBSnapshot (DBSnapshot)

    • DeleteEventSubscription (EventSubscription)

    • DescribeEngineDefaultParameters (EngineDefaults)

    • ModifyDBInstance (DBInstance)

    • ModifyDBSubnetGroup (DBSubnetGroup)

    • ModifyEventSubscription (EventSubscription)

    • ModifyOptionGroup (OptionGroup)

    • PromoteReadReplica (DBInstance)

    • PurchaseReservedDBInstancesOffering (ReservedDBInstance)

    • RebootDBInstance (DBInstance)

    • RemoveSourceIdentifierFromSubscription (EventSubscription)

    • RestoreDBInstanceFromDBSnapshot (DBInstance)

    • RestoreDBInstanceToPointInTime (DBInstance)

    • RevokeDBSecurityGroupIngress (DBSecurityGroup)

  • Amazon Redshift

    • AuthorizeClusterSecurityGroupIngress (ClusterSecurityGroup)

    • AuthorizeSnapshotAccess (Snapshot)

    • CopyClusterSnapshot (Snapshot)

    • CreateCluster (Cluster)

    • CreateClusterParameterGroup (ClusterParameterGroup)

    • CreateClusterSecurityGroup (ClusterSecurityGroup)

    • CreateClusterSnapshot (Snapshot)

    • CreateClusterSubnetGroup (ClusterSubnetGroup)

    • CreateEventSubscription (EventSubscription)

    • CreateHsmClientCertificate (HsmClientCertificate)

    • CreateHsmConfiguration (HsmConfiguration)

    • DeleteCluster (Cluster)

    • DeleteClusterSnapshot (Snapshot)

    • DescribeDefaultClusterParameters (DefaultClusterParameters)

    • DisableSnapshotCopy (Cluster)

    • EnableSnapshotCopy (Cluster)

    • ModifyCluster (Cluster)

    • ModifyClusterSubnetGroup (ClusterSubnetGroup)

    • ModifyEventSubscription (EventSubscription)

    • ModifySnapshotCopyRetentionPeriod (Cluster)

    • PurchaseReservedNodeOffering (ReservedNode)

    • RebootCluster (Cluster)

    • RestoreFromClusterSnapshot (Cluster)

    • RevokeClusterSecurityGroupIngress (ClusterSecurityGroup)

    • RevokeSnapshotAccess (Snapshot)

    • RotateEncryptionKey (Cluster)

已删除 Enum 类

我们已删除AWS SDK for PHP版本 2 中的 Enum 类(例如 Aws\S3\Enum\CannedAcl)。Enum 是开发工具包公共 API 中的具体类,其中包含的常量代表有效参数值的组合。由于这些枚举是特定于某一 API 版本的,是可变的,可能与 PHP 保留关键字冲突,因此并不是非常有用,所以我们在版本 3 中删除了它们,从而支持版本 3 的数据驱动特性,以及与 API 版本无关的特性。

请直接使用文本值,而不是使用 Enum 对象的值(例如,CannedAcl::PUBLIC_READ'public-read')。

已删除精细异常类

我们已删除每项服务的命名空间中存在的精细异常类 (例如 Aws\Rds\Exception\{SpecificError}Exception),其原因与删除 Enum 的原因非常类似。服务或操作引发的异常依赖于所用的 API 版本 (各版本可能有变化)。另外,也无法提供给定操作可引发异常的完整列表,使得版本 2 的精细异常类不完整。

通过捕获每个服务的根异常类来处理错误(例如 Aws\Rds\Exception\RdsException)。您可以使用异常的 getAwsErrorCode() 方法查看具体的错误代码。它的功能与抓住不同的异常类等效,但不会为开发工具包增加多余内容。

删除了静态 Facade 类

AWS SDK for PHP版本 2 中有一项少有人知的功能,我们受到 Laravel 的启发,允许您对 Aws 类调用 enableFacades() 以支持各种服务客户端的静态访问。此功能不符合 PHP 最佳实践,我们在一年多前停止为此功能提供文档。在版本 3 中完全删除了此功能。请从 Aws\Sdk 对象中检索客户端对象,并将其用作对象实例,而不是静态类。

分页工具取代迭代器

AWS SDK for PHP 版本 2 中有一项名为 * iterators* 的功能。这些对象用于迭代分页结果。我们收到反馈,表示它们不够灵活,因为迭代器只会发出每个结果的特定值。如果您需要结果的其他值,只能通过事件侦听器进行检索。

在版本 3 中,分页工具替代了迭代器。它们的用途类似,但分页工具更灵活。这是因为分页工具可生成结果对象,而不是响应值。

以下示例演示了在版本 2 和版本 3 中如何检索 S3 ListObjects 操作的分页结果,从而展示了分页工具与迭代器的不同之处。

// Version 2 $objects = $s3Client->getIterator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($objects as $object) { echo $object['Key'] . "\n"; }
// Version 3 $results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($results as $result) { // You can extract any data that you want from the result. foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } }

分页工具对象拥有 search() 方法,支持您使用 JMESPath 表达式更轻松地从结果集中提取数据。

$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'my-bucket']); foreach ($results->search('Contents[].Key') as $key) { echo $key . "\n"; }

注意

我们仍支持 getIterator() 方法,从而确保更顺畅地过渡到版本 3,但我们鼓励您迁移代码,以使用分页工具。

更改了许多高级抽象

总体而言,我们改进或更新了许多高级抽象 (除客户端之外,特定服务的帮助程序对象)。还删除了一些。

比较开发工具包这两个版本的代码示例

以下示例展示 AWS SDK for PHP 版本 3 与版本 2 的一些不同之处。

示例:Amazon S3 ListObjects 操作

开发工具包版本 2

<?php require '/path/to/vendor/autoload.php'; use Aws\S3\S3Client; use Aws\S3\Exception\S3Exception; $s3 = S3Client::factory([ 'profile' => 'my-credential-profile', 'region' => 'us-east-1' ]); try { $result = $s3->listObjects([ 'Bucket' => 'my-bucket-name', 'Key' => 'my-object-key' ]); foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } } catch (S3Exception $e) { echo $e->getMessage() . "\n"; }

开发工具包版本 3

主要区别:

  • 使用 new 将客户端实例化,而不是 factory()

  • 在实例化的过程中需要 'version''region' 选项。

<?php require '/path/to/vendor/autoload.php'; use Aws\S3\S3Client; use Aws\S3\Exception\S3Exception; $s3 = new S3Client([ 'profile' => 'my-credential-profile', 'region' => 'us-east-1', 'version' => '2006-03-01' ]); try { $result = $s3->listObjects([ 'Bucket' => 'my-bucket-name', 'Key' => 'my-object-key' ]); foreach ($result['Contents'] as $object) { echo $object['Key'] . "\n"; } } catch (S3Exception $e) { echo $e->getMessage() . "\n"; }

示例:实例化具有全局配置的客户端

开发工具包版本 2

<?php return array( 'includes' => array('_aws'), 'services' => array( 'default_settings' => array( 'params' => array( 'profile' => 'my_profile', 'region' => 'us-east-1' ) ), 'dynamodb' => array( 'extends' => 'dynamodb', 'params' => array( 'region' => 'us-west-2' ) ), ) );
<?php require '/path/to/vendor/autoload.php'; use Aws\Common\Aws; $aws = Aws::factory('path/to/my/config.php'); $sqs = $aws->get('sqs'); // Note: SQS client will be configured for us-east-1. $dynamodb = $aws->get('dynamodb'); // Note: DynamoDB client will be configured for us-west-2.

开发工具包版本 3

主要区别:

  • 使用 Aws\Sdk 类,而不是 Aws\Common\Aws

  • 没有配置文件。使用一组配置。

  • 在实例化期间需要 'version' 选项。

  • 使用 create<Service>() 方法,而不是 get('<service>')

<?php require '/path/to/vendor/autoload.php'; $sdk = new Aws\Sdk([ 'profile' => 'my_profile', 'region' => 'us-east-1', 'version' => 'latest', 'DynamoDb' => [ 'region' => 'us-west-2', ], ]); $sqs = $sdk->createSqs(); // Note: Amazon SQS client will be configured for us-east-1. $dynamodb = $sdk->createDynamoDb(); // Note: DynamoDB client will be configured for us-west-2.