本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

從 第 2 版升級 AWS SDK for PHP

本主題說明如何遷移程式碼以使用 第 AWS SDK for PHP 3 版，以及新版本與 第 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物件作為替代項目 AWS SDK for PHP 引入 Aws\Common\Aws。系統會將 Sdk 物件做為用戶端 factory 使用，並採用該物件來管理多個用戶端的共用組態選項。

雖然 第 2 版中的Aws類別SDK的運作方式與服務定位工具相同 （一律傳回相同的用戶端執行個體），但第 3 版中的Sdk類別會在每次使用時傳回用戶端的新執行個體。

Sdk 物件也不支援來自 第 2 版的相同組態檔案格式SDK。該組態格式為 Guzzle 3 專屬格式，目前已淘汰。使用基本陣列將能更輕鬆地進行組態，其做法詳載於使用 Sdk 類別。

某些API結果已變更

為了提供SDK剖析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'];

下列操作在此版本中亦受到影響，因此這些操作目前在輸出結果中會納入包裝元素，如括號中所示：

移除 Enum 類別

我們已經移除 AWS SDK for PHP第 2 版現存的 Enum 類別 (如 Aws\S3\Enum\CannedAcl)。列舉是 公有中的具體類別APISDK，其中包含代表有效參數值群組的常數。由於這些列舉是API版本特有的，可能會隨著時間而變更、可能與PHP預留單字衝突，最終不太有用，因此我們已在第 3 版中移除它們。這支援第 3 API版的資料驅動型和版本無關性質。

您不該使用來自 Enum 物件的值，而是直接使用常值。例如：使用 CannedAcl::PUBLIC_READ 取代 'public-read'。

移除微調例外類別

出於與移除 Enums 類別相似的考量，我們也一併移除了各服務命名空間中的精細例外狀況類別 (例如 Aws\Rds\Exception\{SpecificError}Exception)。服務或操作所擲出的例外狀況取決於使用的API版本 （它們可以從版本變更為版本）。不僅如此，系統亦無法使用指定操作所拋出的例外狀況完整清單，導致第 2 版的精細例外狀況類別無法完整呈現。

為了處理錯誤，您應該取得各項服務的例外根類別 (例如：Aws\Rds\Exception\RdsException)。您可以使用例外狀況的 getAwsErrorCode() 方法，藉此檢查特定的錯誤碼。這在功能上等同於擷取不同的例外類別，但提供該函數而不將 bloat 新增至 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";
}

變更許多高階抽象概念

整體而言，此版本改良或更新了許多高階抽象概念 (除用戶端之外的服務特定 helper 物件)；甚至移除部分高階抽象概念。

比較兩個版本的程式碼範例 SDK

下列範例顯示使用 第 3 版可能與第 2 版 AWS SDK for PHP 不同的一些方式。

範例：Amazon S3 ListObjects Operation

從 第 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.