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

从 AWS SDK for PHP 的版本 2 升级

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

简介

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

版本 3 中有哪些新功能？

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

其他新增功能包括

分离的 HTTP 层

异步请求

与版本 2 有何不同之处？

更新了项目依赖项

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

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

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

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

在 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'
]);

客户端配置已更改

在 AWS SDK for PHP 版本 3 中的客户端配置选项与版本 2 稍有不同。请参阅 AWS SDK for PHP 版本3 配置页面，查看所有支持的选项的描述。

Sdk 对象

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

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

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

更改了一些 API 结果

为了确保 SDK 解析 API 操作、Amazon ElastiCache、Amazon 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 类

我们已删除AWS SDK for PHP版本 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 类

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";
}

更改了许多高级抽象

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

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

以下示例展示 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

主要区别：

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

主要区别：

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