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

从版本 2 升级 AWS SDK for PHP

本主题说明如何将您的代码迁移到使用版本 3， AWS SDK for PHP 以及新版本与版本 2 的不同之处SDK。

简介

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

版本 3 中有哪些新功能？

的版本 3 AWS SDK for PHP 遵循 PSR-4 和 PSR -7 标准，未来将遵循该SemVer标准。

其他新增功能包括

解耦层 HTTP

异步请求

与版本 2 有何不同之处？

更新了项目依赖项

在此版本中，的依赖关系SDK已更改。

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

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

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

在的版本 3 中 AWS SDK for PHP，实例化客户端的方式发生了变化。您只需使用 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 相比略 AWS SDK for PHP 有变化。有关所有支持的选项的描述，请参阅 AWS SDK for PHP 版本 3 的配置页面。

Sdk 对象

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

尽管版本 2 中的Aws类SDK的工作原理与服务定位器类似（它总是返回相同的客户端实例），但版本 3 中的Sdk类每次使用都会返回一个新的客户端实例。

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

一些API结果已经改变

为了使SDK解析API操作结果的方式保持一致，亚马逊 ElastiCache、亚马逊和亚马逊 Redshift 现在在API某些响应中添加了额外的包装元素。RDS

例如，在版本 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）。枚举是公共API中的具体类SDK，其中包含表示有效参数值组的常量。由于这些枚举是特定于API版本的，可能会随着时间的推移而变化，可能与PHP保留字冲突，并且最终没有多大用处，因此我们在版本 3 中删除了它们。这支持版本 3 的数据驱动和API版本不可知性。

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

已删除精细异常类

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

通过捕获每个服务的根异常类来处理错误（例如 Aws\Rds\Exception\RdsException）。您可以使用异常的 getAwsErrorCode() 方法查看具体的错误代码。这在功能上等同于捕获不同的异常类，但是在不增加膨胀的情况下提供了该函数。SDK

删除了静态 Facade 类

在的版本2中 AWS SDK for PHP，有一个受Laravel启发的模糊功能，它允许你调用该Aws类来启用enableFacades()对各种服务客户端的静态访问。此功能与PHP最佳实践背道而驰，一年多以前，我们就停止对其进行记录了。在版本 3 中完全删除了此功能。请从 Aws\Sdk 对象中检索客户端对象，并将其用作对象实例，而不是静态类。

分页工具取代迭代器

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

在版本 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";
}

更改了许多高级抽象

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

比较两个版本的代码示例 SDK

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

示例：亚马逊 S3 ListObjects 操作

来自第 2 版 SDK

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

主要区别：

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

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

主要区别：

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