Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

从版本 2 升级 适用于 PHP 的 Amazon SDK

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

简介

版本 3 适用于 PHP 的 Amazon SDK 代表了为改进 SDK 的功能、整合两年多的客户反馈、升级我们的依赖关系、提高性能和采用最新的 PHP 标准所做的巨大努力。

版本 3 中有哪些新功能？

的版本 3 适用于 PHP 的 Amazon SDK 遵循 PSR-4 和 PSR-7 标准，今后将遵循该SemVer标准。

其他新增功能包括

分离的 HTTP 层

异步请求

与版本 2 有何不同之处？

更新了项目依赖项

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

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

如果要将任何服务的客户端实例化，请指定 'region' 和 'version' 选项。在的版本 2 中 适用于 PHP 的 Amazon SDK，'version'是完全可选的，有时'region'是可选的。在版本 3 中，这两个选项都是必需的。明确说明这两个选项可以让你锁定你要编码的 API 版本和 Amazon 区域。当新的 API 版本创建或新的 Amazon 区域可用时，在您准备好显式更新配置之前，您将与可能发生的重大更改隔离开来。

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

在的版本 3 中 适用于 PHP 的 Amazon SDK，实例化客户端的方式发生了变化。您只需使用 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'
]);

客户端配置已更改

版本 3 中的客户端配置选项与版本 2 相比略 适用于 PHP 的 Amazon SDK 有变化。有关所有支持的选项的描述，请参阅 适用于 PHP 的 Amazon SDK 版本 3 的配置页面。

Sdk 对象

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

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

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

更改了一些 API 结果

为了保持软件开发工具包解析 API 操作结果的方式的一致性，亚马逊 ElastiCache、亚马逊 RDS 和 Amazon Redshift 现在在某些 API 响应上增加了包装元素。

例如，在版本 3 中调用 Amazon RDS DescribeEngineDefaultParameters结果现在包括一个封装 “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'];

以下操作会受到影响，在结果输出中会包含包装元素（在下文的括号中提供）：

已删除 Enum 类

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

请直接使用文本值，而不是使用 Enum 对象的值（例如，CannedAcl::PUBLIC_READ → 'public-read'）。

已删除精细异常类

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

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

删除了静态 Facade 类

在的版本2中 适用于 PHP 的 Amazon SDK，有一个受Laravel启发的模糊功能，它允许你调用该Aws类来启用enableFacades()对各种服务客户端的静态访问。此功能不符合 PHP 最佳实践，我们在一年多前停止为此功能提供文档。在版本 3 中完全删除了此功能。请从 Aws\Sdk 对象中检索客户端对象，并将其用作对象实例，而不是静态类。

分页工具取代迭代器

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

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

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

// Version 2
$objects = $s3Client->getIterator('ListObjects', ['Bucket' => 'amzn-s3-demo-bucket']);
foreach ($objects as $object) {
    echo $object['Key'] . "\n";
}

// Version 3
$results = $s3Client->getPaginator('ListObjects', ['Bucket' => 'amzn-s3-demo-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";
    }
}

Paginator 对象具有一种search()方法，可让您使用JMESPath表达式更轻松地从结果集中提取数据。

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

更改了许多高级抽象

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

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

以下示例显示了使用版本 3 适用于 PHP 的 Amazon SDK 可能与版本 2 有所不同的一些方式。

示例：亚马逊 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' => 'amzn-s3-demo-bucket',
        'Key'    => 'my-object-key'
    ]);

    foreach ($result['Contents'] as $object) {
        echo $object['Key'] . "\n";
    }
} catch (S3Exception $e) {
    echo $e->getMessage() . "\n";
}

开发工具包版本 3

主要区别：

<?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' => 'amzn-s3-demo-bucket',
        '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

主要区别：

<?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.