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

從版本 2 升級 AWS SDK for PHP

本主題說明如何遷移程式碼以使用AWS SDK for PHP第 3 版，並說明新版本與開發套件第 2 版的差異。

簡介

我們在提升開發套件的功能方面投入許多心力，不僅將過去兩年的客戶意見回饋納入設計考量，亦升級相依性、改善效能，並採用最新的 PHP 標準，最終推出了AWS SDK for PHP第 3 版。

第 3 版有哪些最新功能？

第三版AWS SDK for PHP遵循 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 版有些許差異。如需所有支援選項的說明，請參閱第 3 AWS SDK for PHP 版的組態頁面。

Sdk 物件

AWS SDK for PHP第 3 版引進了 Aws\Sdk 物件，以取代 Aws\Common\Aws。系統會將 Sdk 物件做為用戶端 factory 使用，並採用該物件來管理多個用戶端的共用組態選項。

雖然軟體開發套件第 2 版的 Aws 類別是以類似服務定位器的方式進行運作 (該類別會一律傳回相同的用戶端執行個體)，但第 3 版的 Sdk 類別每次都會傳回新的用戶端執行個體。

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

變更部分 API 結果

為了提供 SDK 如何剖析 API 操作結果的一致性，亞馬遜ElastiCache、亞馬遜 RDS 和亞馬遜 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 中的具體類別，而該類別所含的常數可用來表示有效參數值群組。由於這些 enum 是 API 版本特有的類別，可能會隨著時間改變，或是與 PHP 保留字衝突，致使降低效能且沒有任何助益；因此，我們決定在第 3 版中移除這些類別。如此一來，這項改變即可支援第 3 版的資料導向與 API 版本適用性。

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

移除微調例外類別

出於與移除 Enums 類別相似的考量，我們也一併移除了各服務命名空間中的精細例外狀況類別 (例如 Aws\Rds\Exception\{SpecificError}Exception)。由於服務或操作會依據使用的 API 版本來擲出例外狀況，因此例外狀況會隨版本而異。不僅如此，系統亦無法使用指定操作所拋出的例外狀況完整清單，導致第 2 版的精細例外狀況類別無法完整呈現。

為了處理錯誤，您應該取得各項服務的例外根類別 (例如：Aws\Rds\Exception\RdsException)。您可以使用例外狀況的 getAwsErrorCode() 方法，藉此檢查特定的錯誤碼。此功能相當於取得不同的例外類別，但本版本所提供的功能不會增加開發套件的膨脹速度。

移除靜態 Facade 類別

受到 Laravel 啟發，AWS SDK for PHP第 2 版搭載了一項隱藏功能，讓您可對 Aws 類別呼叫 enableFacades()，以啟用各種服務用戶端的靜態存取。然而，這項功能並不符合 PHP 最佳實務。因此，我們在一年前便已經停止記錄該功能，而我們更是在第 3 版中完全將之移除。從 Aws\Sdk 物件中擷取用戶端物件，並將這些物件做為物件執行個體來使用，而非靜態類別。

以分頁程式取代疊代運算

AWS SDK for PHP第 2 版有一項稱為 *疊代運算* 的功能。系統會使用疊代運算物件來逐一查看分頁結果。使用者對這些物件感到不滿的原因之一便是「缺乏彈性」，因為疊代運算僅會發送每個結果的特定值。您只能透過事件接聽程式，才能擷取其他所需的結果值。

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

變更許多高階抽象概念

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

比較開發套件兩個版本的程式碼範例

以下範例顯示AWS SDK for PHP第 3 版與第 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' => '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.