Download the PHP package jlm/aws-bundle without Composer

Status Badges (for master)

JLMAwsBundle

This bundle serves as a fairly thin wrapper around Amazon's AWS SDK 2.x to make it easier to configure the SDK and register its services as Symfony services.

The SDK itself is built on Guzzle using Guzzle's service builder and configuration style. This bundle allows you to configure AWS in a more idiomatic way for a Symfony project. The Symfony configuration is then translated directly to a Guzzle configuration which is passed to the SDK in order to generate the Guzzle service clients. The Guzzle service clients are then registered as services in the Symfony DI Container for use throughout your application.

Note: This is a fairly new bundle and it hasn't seen much real usage yet. While there are extensive unit tests, there are likely still issues with some advanced configurations. There are also several AWS configuration options not yet supported through configuration. All contributions are welcome!

Installation

This bundle can be installed via Composer by adding the following to your file:

Then add the bundle to your Kernel in (if using Symfony Standard):

That's it! You should be able to configure the SDK via Symfony and gain access to its services from the DIC now.

Configuration

To really understand the configuration, you should have a good understanding of how the AWS configuration looks without this bundle. We use the same names for most things and a very similar structure, but certain things are changed a bit for various reasons. Please see the AWS Configuration documentation if you are unfamiliar.

The general idea is that there are repeating blocks of service definitions keyed by service type and name. The first block is at the root level. These are global settings that all other services extend from (by default) and in many configurations is the only place where you'll need to add configuration such as credentials.

Below that under is there you define all the services you wish to use. Directly below is where you define the service type that you wish to configure. Under each service type, you may define one or more named services of that type. This allows you to have more than one S3 client, for example. Perhaps one for each region. You may optionally choose not to include any named services, but rather just set the value of the service type to or . This will create a single default version of that service.

The configuraiton below would enable the default version of all available services:

Each instance of a service type (including ) has the exact same child options, including , , and .

To see a full configuration from within your app, run:

Configuration Inheritance

There are two levels of inheritance at play with this bundle's configuration. The first is at the Symfony level. If you define a configuration for this bundle in a parent file (eg: ) and then import that configuration file in a child file (eg: ), the child file may overwrite any configuration directives in the parent file.

There is, however, a secondary level of inheritance at the AWS SDK/Guzzle level. By providing the attribute to a service instance, you can inherit the settings of another instance of the same type. By default, is inherited by all types, but you could chain several S3 instances, for example, together should you choose to do so.

The above configuration would create 3 S3 services in the container:

The first would have a region of inherited from but use its own and values. The second would be the same as the first except it would override the region to be . Finally, the 3rd would be the same as the 2nd except it would use different credentials.

This can be pretty powerful, but in most cases the configuration will be much simpler than what it is capable of.

S3 Wrapper

The AWS SDK provides an S3 Wrapper. We can automatically register a particular S3 service instance's stream wrapper by providing the configuration option to . This configuraiton option accepts either a value or the the name of an S3 instance that you wish to use for the stream. If is given, it will assume you wish to use the unnamed default S3 service instance.

Only one S3 instane can register the stream, so if you have multiple S3 service instances you won't be able to register multiple streams. You could do it at runtime by unreigstering a previous stream, getting an instance of the S3 client you want, and then re-registering the stream with that instance. Obviously we cannot facilitate that at configuration time, however.

The configuration above would create a default S3 client and register its stream wrapper.

Important: You must enable the S3 default service if you choose to use a value of for as we did above by adding to the config. You could also enable it via:

The above two configurations are equivalent. Likewise, if you choose to use a named instance, that instance must be registered under the S3 services configuration.

Integrations

This bundle integrates with PlaybloomGuzzleBundle automatically. The Playbloom bundle allows you to see Guzzle client requests in the profiler UI. The integration happens by way of a tag in the Symfony DI container and is enabled by default. Currently it cannot be disabled. It has no effect, however, unless you also include the PlayblooomGuzzleBundle in your project.