Skip to content

Latest commit

 

History

History
314 lines (223 loc) · 9.53 KB

aws_s3.rst

File metadata and controls

314 lines (223 loc) · 9.53 KB
Raw

AWS S3 Resolver

The AwsS3Resolver resolver enables cache resolution using Amazon S3 using the Aws\S3\S3Client.

Dependencies

This cache resolver requires the aws-sdk-php library, which can be installed by executing the following command in your project directory:

$ composer require aws/aws-sdk-php

Configuration

To begin, you must assign your AWS key, secret, bucket, and region to their respective parameters.

# app/config/config.yml or app/config/parameters.yml

parameters:
    amazon.s3.key:     "your-aws-key"
    amazon.s3.secret:  "your-aws-secret"
    amazon.s3.bucket:  "your-bucket.example.com"
    amazon.s3.region:  "your-bucket-region"
    amazon.s3.version: "2006-03-01"

Note

To not confuse the cache resolver, use the bucket.domain.tld notation. Specifying the bucket in a path (domain.tld/bucket) does not work.

Prerequisites

Create Resolver from a Factory

# app/config/config.yml

liip_imagine:
    resolvers:
        aws_s3_resolver:
            aws_s3:
                client_config:
                    credentials:
                        key:    "%amazon.s3.key%"
                        secret: "%amazon.s3.secret%"
                    region: "%amazon.s3.region%"
                    version: "%amazon.s3.version%"
                bucket: "%amazon.s3.bucket%"
                get_options:
                    Scheme: https
                put_options:
                    CacheControl: "max-age=86400"

Tip

If using aws-sdk-php < 3.0.0, you must omit the credentials key and instead place the key and secret keys at the same level as region and bucket.

# app/config/services.yml

services:
    aws_s3:
        client_config:
            key:    "%amazon.s3.key%"
            secret: "%amazon.s3.secret%"
            region: "%amazon.s3.region%"
            bucket: "%amazon.s3.bucket%"

Create Resolver as a Service

While creating the resolver through a factory using the configuration above does the job for most use cases, it can sometimes be neccessary to create the resolver as a service.

Tip

For example, this is required if you do not want to hard code AWS credentials for your resolver, but instead make it use the Default Credential Provider Chain within AWS (for example, because you are running this on an EC2 instance which is already attached to an IAM role with the required permissions). In this case, simply setting up the resolver through a factory configuration block and leaving out the credentials block won't cut it. Instead, you need to set up the resolver as a service as shown below, passing an S3Client.

You have to set up the services required:

# app/config/services.yml

services:
    acme.amazon_s3:
        class: Aws\S3\S3Client
        factory: [Aws\S3\S3Client, factory]
        arguments:
            -
                credentials: { key: "%amazon.s3.key%", secret: "%amazon.s3.secret%" }
                region: "%amazon.s3.region%"
                version: "%amazon.s3.version%"

    acme.imagine.cache.resolver.aws_s3_resolver:
        class: Liip\ImagineBundle\Imagine\Cache\Resolver\AwsS3Resolver
        arguments:
            - "@acme.amazon_s3"
            - "%amazon.s3.bucket%"
        tags:
            - { name: "liip_imagine.cache.resolver", resolver: "aws_s3_resolver" }

Tip

If using aws-sdk-php < 3.0.0, you must omit the credentials key and instead place the key and secret keys at the same level as region and bucket.

# app/config/services.yml

services:
    acme.amazon_s3:
        # ...
        arguments:
            -
                key: "%amazon.s3.key%"
                secret: "%amazon.s3.secret%"
                region: "%amazon.s3.region%"

acme.amazon_s3:
    class: Aws\S3\S3Client
    factory: [Aws\S3\S3Client, factory]
    arguments:
        -
            credentials: { key: "%amazon.s3.key%", secret: "%amazon.s3.secret%" }
            region: "%amazon.s3.region%"
            version: "%amazon.s3.version%"

Usage

After configuring AwsS3Resolver, you can set it as the default cache resolver for LiipImagineBundle using the following configuration:

# app/config/config.yml

liip_imagine:
    cache: aws_s3_resolver

Usage on a Specific Filter

Alternatively, you can set AmazonS3Resolver as the cache resolver for a specific filter set using the following configuration.

# app/config/config.yml

liip_imagine:
    filter_sets:
        cache: ~
        my_thumb:
            cache: aws_s3_resolver
            filters:
                # the filter list

Tip

If you want to use other buckets for other images, simply alter the parameter names and create additional services.

Additional Options

You can use Cache <cache-resolver-cache> and Proxy <cache-resolver-proxy> resolvers in chain with current. You just need to configure them with defined options.

# app/config/config.yml

liip_imagine:
    resolvers:
       aws_s3_resolver:
          aws_s3:
              #...
              proxies: ["https://one.domain.com", "https://two.domain.com"]
              cache: true

If enabled both first one will be Cache <cache-resolver-cache>, then Proxy <cache-resolver-proxy> and after all process delegates to AwsS3 resolver.

Object GET Options

In order to make use of the object GET options, you can simply add a call to the service, to alter those options you need.

# app/config/services.yml

services:
    acme.imagine.cache.resolver.aws_s3_resolver:
        class: Liip\ImagineBundle\Imagine\Cache\Resolver\AwsS3Resolver
        arguments:
            - "@acme.amazon_s3"
            - "%amazon_s3.bucket%"
        calls:
             # This calls $service->setGetOption('Scheme', 'https');
             - [ setGetOption, [ Scheme, https ] ]
        tags:
            - { name: "liip_imagine.cache.resolver", resolver: "aws_s3_resolver" }

You can also use the constructor of the resolver to directly inject multiple options.

# app/config/services.yml

services:
    acme.imagine.cache.resolver.aws_s3_resolver:
        class: Liip\ImagineBundle\Imagine\Cache\Resolver\AwsS3Resolver
        arguments:
            - "@acme.amazon_s3"
            - "%amazon_s3.bucket%"
            - "public-read" # Aws\S3\Enum\CannedAcl::PUBLIC_READ (default)
            - { Scheme: https }
        tags:
            - { name: "liip_imagine.cache.resolver", resolver: "aws_s3_resolver" }

Object PUT Options

Similar to Object GET Options you can configure additional options to be passed to S3 when storing objects. This is useful, for example, to configure Cache-control headers returned when serving object from S3. See S3 SDK documentation for the list of available options.

Note, that the following options are configured automatically and will be ignored, even if you configure it via ObjectOptions:

  • Bucket
  • Key
  • Body
  • ContentType

In order to make use of the object PUT options, you can simply add a call to the service, to alter those options you need.

# app/config/services.yml

services:
    acme.imagine.cache.resolver.aws_s3_resolver:
        class: Liip\ImagineBundle\Imagine\Cache\Resolver\AwsS3Resolver
        arguments:
            - "@acme.amazon_s3"
            - "%amazon_s3.bucket%"
        calls:
             # This calls $service->setPutOption('CacheControl', 'max-age=86400');
             - [ setPutOption, [ CacheControl, "max-age=86400" ] ]
        tags:
            - { name: "liip_imagine.cache.resolver", resolver: "aws_s3_resolver" }

You can also use the constructor of the resolver to directly inject multiple options.

# app/config/services.yml

services:
    acme.imagine.cache.resolver.aws_s3_resolver:
        class: Liip\ImagineBundle\Imagine\Cache\Resolver\AwsS3Resolver
        arguments:
            - "@acme.amazon_s3"
            - "%amazon_s3.bucket%"
            - "public-read" # Aws\S3\Enum\CannedAcl::PUBLIC_READ (default)
            - { Scheme: https }
            - { CacheControl: "max-age=86400" }
        tags:
            - { name: "liip_imagine.cache.resolver", resolver: "aws_s3_resolver" }

You can find an example with private ACL and signed url on the events chapter </events>.