Skip to content

Latest commit

 

History

History
324 lines (259 loc) · 14 KB

UPGRADING.md

File metadata and controls

324 lines (259 loc) · 14 KB
Raw

Upgrading Guide

Upgrade from 2.x to 3.x

Version 3 is a new major version of the SDK that represents a significant effort to improve the capabilities of the SDK, incorporate two years of customer feedback, upgrade our dependencies, improve performance, and adopt the latest PHP standards.

The basic usage pattern of the SDK (i.e., $result = $client->operation($params);) has not changed from Version 2 to Version 3, which should result in a fairly smooth migration.

For details on how to migrate your code from Version 2 to Version 3, read the Version 3 Migration Guide.

Upgrade from 2.7 to 2.8

AWS Lambda

Version 2.8 is backward-compatible with version 2.7, except in the case of the AWS Lambda service. The Lambda service has changed their API significantly based on customer feedback during their preview period. The invokeAsync() operation has not changed, but many aspects of the API has.

If you would like to continue using the old 2014-11-11 previewAPI, you can configure this when you instantiate the LambdaClient:

use Aws\Lambda\LambdaClient;

$client = LambdaClient::factory(array(
    'version' => '2014-11-11',
    // ...
));

Preparations for Version 3 of the SDK

In preparation for Version 3 of the AWS SDK for PHP:

  • We marked all of the "facade" classes and methods as deprecated, since they will be removed.
  • We added the getAwsErrorCode(), getAwsErrorType() and getAwsRequestId() methods to the ServiceResponseException to be forward-compatible with Version 3's AwsException interface.
  • We advise against the use of any Enum class, since these will be removed. Instead, use the literal value to which the enum corresponds.
  • We advise against the use of any granular service classes, since these will be removed. Instead, catch the top-level service exception (e.g., Aws\S3\Exception\S3Exception) and use the getAwsErrorCode() method if you need to know the granular error code.

Upgrade from 2.6 to 2.7

Version 2.7 is backward-compatible with version 2.6. The version bump was necessary in order to mark some things in the DynamoDb namespace as deprecated. See the CHANGELOG entry for 2.7.0 for more details.

Upgrade from 2.5 to 2.6

IMPORTANT: Version 2.6 is backward-compatible with version 2.5, unless you are using the Amazon CloudSearch client. If you are using CloudSearch, please read the next section carefully.

Amazon CloudSearch

Version 2.6 of the AWS SDK for PHP has been updated to use the 2013-01-01 API version of Amazon CloudSearch by default.

The 2013-01-01 API marks a significant upgrade of Amazon CloudSearch, but includes numerous breaking changes to the API. CloudSearch now supports 33 languages, highlighting, autocomplete suggestions, geospatial search, AWS IAM integration to control access to domain configuration actions, and user configurable scaling and availability options. These new features are reflected in the changes to the method and parameters of the CloudSearch client.

For details about the new API and how to update your usage of CloudSearch, please consult the Configuration API Reference for Amazon CloudSearch and the guide for Migrating to the Amazon CloudSearch 2013-01-01 API.

If you would like to continue using the older 2011-02-01 API, you can configure this when you instantiate the CloudSearchClient:

use Aws\CloudSearch\CloudSearchClient;

$client = CloudSearchClient::factory(array(
    'key'     => '<aws access key>',
    'secret'  => '<aws secret key>',
    'region'  => '<region name>',
    'version' => '2011-02-01',
));

Upgrade from 2.4 to 2.5

Amazon EC2

A small, backwards-incompatible change has been made to the Amazon EC2 API. The LaunchConfiguration.MonitoringEnabled parameter of the RequestSpotInstances operation has been change to LaunchConfiguration.Monitoring.Enabled See this commit for the exact change. You are only affected by this change if you are using this specific parameter. To fix your code to work with the updated parameter, you will need to change the structure of your request slightly.

// The OLD way
$result = $ec2->requestSpotInstances(array(
    // ...
    'LaunchSpecification' => array(
        // ...
        'MonitoringEnabled' => true,
        // ...
    ),
    // ...
));

// The NEW way
$result = $ec2->requestSpotInstances(array(
    // ...
    'LaunchSpecification' => array(
        // ...
        'Monitoring' => array(
            'Enabled' => true,
        ),
        // ...
    ),
    // ...
));

AWS CloudTrail

AWS CloudTrail has made changes to their API. If you are not using the CloudTrail service, then you will not be affected by this change.

Here is an excerpt (with minor modifications) directly from the CloudTrail team's announcement regarding this change:

[...] We have made some minor improvements/fixes to the service API, based on early feedback. The impact of these changes to you depends on how you are currently interacting with the CloudTrail service. [...] If you have code that calls the APIs below, you will need to make minor changes.

There are two changes:

  1. CreateTrail / UpdateTrail: These APIs originally took a single parameter, a Trail object. [...] We have changed this so that you can now simply pass individual parameters directly to these APIs. The same applies to the responses of these APIs, namely the APIs return individual fields directly [...]
  2. GetTrailStatus: The actual values of the fields returned and their data types were not all as intended. As such, we are deprecating a set of fields, and adding a new set of replacement fields. The following fields are now deprecated, and should no longer be used:
  • LatestDeliveryAttemptTime (String): Time CloudTrail most recently attempted to deliver a file to S3 configured bucket.
  • LatestNotificationAttemptTime (String): As above, but for publishing a notification to configured SNS topic.
  • LatestDeliveryAttemptSucceeded (String): This one had a mismatch between implementation and documentation. As documented: whether or not the latest file delivery was successful. As implemented: Time of most recent successful file delivery.
  • LatestNotificationAttemptSucceeded (String): As above, but for SNS notifications.
  • TimeLoggingStarted (String): Time StartLogging was most recently called. [...]
  • TimeLoggingStarted (String): Time StopLogging was most recently called.

The following fields are new, and replace the fields above:

  • LatestDeliveryTime (Date): Date/Time that CloudTrail most recently delivered a log file.
  • LatestNotificationTime (Date): As above, for SNS notifications.
  • StartLoggingTime (Date): Same as TimeLoggingStarted, but with more consistent naming, and correct data type.
  • StopLoggingTime (Date): Same as TimeLoggingStopped, but with more consistent naming, and correct data type.

Note that LatestDeliveryAttemptSucceeded and LatestNotificationAttemptSucceeded have no direct replacement. To query whether everything is configured correctly for log file delivery, it is sufficient to query LatestDeliveryError, and if non-empty that means that there is a configuration problem preventing CloudTrail from being able to deliver logs successfully. Basically either the bucket doesn’t exist, or CloudTrail doesn’t have sufficient permissions to write to the configured path in the bucket. Likewise for LatestNotificationAttemptSucceeded.

The deprecated fields will be removed in the future, no earlier than February 15. Both set of fields will coexist on the service during this period to give those who are using the deprecated fields time to switch over to the use the new fields. However new SDKs and CLIs will remove the deprecated fields sooner than that. Previous SDK and CLI versions will continue to work until the deprecated fields are removed from the service.

We apologize for any inconvenience, and appreciate your understanding as we make these adjustments to improve the long-term usability of the CloudTrail APIs.

We are marking this as a breaking change now, preemptive of the February 15th cutoff, and we encourage everyone to update their code now. The changes to how you use createTrail() and updateTrail() are easy changes:

// The OLD way
$cloudTrail->createTrail(array(
    'trail' => array(
        'Name'         => 'TRAIL_NAME',
        'S3BucketName' => 'BUCKET_NAME',
    )
));

// The NEW way
$cloudTrail->createTrail(array(
    'Name'         => 'TRAIL_NAME',
    'S3BucketName' => 'BUCKET_NAME',
));

China (Beijing) Region / Signatures

This release adds support for the new China (Beijing) Region. This region requires that Signature V4 be used for both Amazon S3 and Amazon EC2 requests. We've added support for Signature V4 in both of these services for clients configured for this region. While doing this work, we did some refactoring to the signature classes and also removed support for Signature V3, as it is no longer needed. Unless you are explicitly referencing Signature V3 or explicitly interacting with signature objects, these changes should not affect you.

Upgrade from 2.3 to 2.4

Amazon CloudFront Client

The new 2013-05-12 API version of Amazon CloudFront includes support for custom SSL certificates via the ViewerCertificate parameter, but also introduces breaking changes to the API. Version 2.4 of the SDK now ships with two versions of the Amazon CloudFront service description, one for the new 2013-05-12 API and one for the next most recent 2012-05-05 API. The SDK defaults to using the newest API version, so CloudFront users may experience a breaking change to their projects when upgrading. This can be easily circumvented by switching back to the 2012-05-05 API by using the version option when instantiating the CloudFront client.

Guzzle 3.7

Version 2.4 of the AWS SDK for PHP requires at least version 3.7 of Guzzle.

Upgrade from 2.2 to 2.3

Amazon DynamoDB Client

The newly released 2012-08-10 API version of the Amazon DynamoDB service includes the new Local Secondary Indexes feature, but also introduces breaking changes to the API. The most notable change is in the way that you specify keys when creating tables and retrieving items. Version 2.3 of the SDK now ships with 2 versions of the DynamoDB service description, one for the new 2012-08-10 API and one for the next most recent 2011-12-05 API. The SDK defaults to using the newest API version, so DynamoDB users may experience a breaking change to their projects when upgrading. This can be easily fixed by switching back to the 2011-12-05 API by using the new version configuration setting when instantiating the DynamoDB client.

use Aws\DynamoDb\DynamoDbClient;

$client = DynamoDbClient::factory(array(
    'key'     => '<aws access key>',
    'secret'  => '<aws secret key>',
    'region'  => '<region name>',
    'version' => '2011-12-05'
));

If you are using a config file with Aws\Common\Aws, then you can modify your file like the following.

{
    "includes": ["_aws"],
    "services": {
        "default_settings": {
            "params": {
                "key": "<aws access key>",
                "secret": "<aws secret key>",
                "region": "<region name>"
            }
        },
        "dynamodb": {
            "extends": "dynamodb",
            "params": {
                "version": "2011-12-05"
            }
        }
    }
}

The SDK user guide has a guide and examples for both versions of the API.

Guzzle 3.4.1

Version 2.3 of the AWS SDK for PHP requires at least version 3.4.1 of Guzzle.

Upgrade from 2.1 to 2.2

Full Service Coverage

The AWS SDK for PHP now supports the full set of AWS services.

Guzzle 3.3

Version 2.2 of the AWS SDK for PHP requires at least version 3.3 of Guzzle.

Upgrade from 2.0 to 2.1

General

Service descriptions are now versioned under the Resources/ directory of each client.

Waiters

Waiters now require an associative array as input for the underlying operation performed by a waiter. The configuration system for waiters under 2.0.x utilized strings to determine the parameters used to create an operation. For example, when waiting for an object to exist with Amazon S3, you would pass a string containing the bucket name concatenated with the object name using a '/' separator (e.g. 'foo/baz'). In the 2.1 release, these parameters are now more explicitly tied to the underlying operation utilized by a waiter. For example, to use the ObjectExists waiter of Amazon S3 pass an associative array of array('Bucket' => 'foo', 'Key' => 'baz'). These options match the option names and rules associated with the HeadObject operation performed by the waiter. The API documentation of each client describes the waiters associated with the client and what underlying operation is responsible for waiting on the resource. Waiter specific options like the maximum number of attempts (max_attempts) or interval to wait between retries (interval) can be specified in this same configuration array by prefixing the keys with waiter..

Waiters can also be invoked using magic methods on the client. These magic methods are listed in each client's docblock using @method tags.

$s3Client->waitUntilObjectExists(array(
    'Bucket' => 'foo',
    'Key' => 'bar',
    'waiter.max_attempts' => 3
));