Overview

This is a developer-focused module that provides a simple factory for an S3 client.
It is not intended for integration with Drupal's file system and does not register a stream wrapper.
It is only intended for developers who wish to inject an S3 client factory into their services and then interact directly with the client to e.g. put, list and get objects from S3.

Installation

Install with composer, which will take care of fetching the AWS SDK.
composer require drupal/s3client

Configuration

There is no configuration or UI for the module, however you can declare credentials in your settings.php to support a default client.

$settings['s3client.default_key'] = 'YOUR KEY HERE';
$settings['s3client.default_secret'] = 'YOUR SECRET HERE';
$settings['s3client.default_region'] = 'us-east-1'; // Or your preferred region.

Typically this would be done with environment variables or a secrets management library.

$settings['s3client.default_key'] = getenv('S3_CLIENT_KEY');
$settings['s3client.default_secret'] = getenv('S3_CLIENT_SECRET');
$settings['s3client.default_region'] = getenv('S3_CLIENT_REGION'); // Or your preferred region.
// Advanced features for those using a service OTHER than AWS
$settings['s3client.default_endpoint'] = 'https://s3.example.com'; // Not required with AWS endpoint.
$settings['s3client.default_bucket_endpoint'] = TRUE; // If your endpoint is directly pointing to your bucket, you want to set this to TRUE. It has no effect if s3client.default_endpoint is undefined, default: FALSE.
$settings['s3client.default_version'] = 'latest'; // Default: 2006-03-01.

Usage

Default client

To inject the default client into your classes, use the s3client.s3client service.

In your services..yml

services:
  mymodule.something_s3:
    class: 'Drupal\mymodule\SomethingS3'
    arguments:
      - '@s3client.s3client'

Then you can interact directly with the client per the AWS documentation.

Injecting the factory

To inject the client factory into your classes, use the s3client.factory service.

In your services..yml

services:
  mymodule.something_s3:
    class: 'Drupal\mymodule\SomethingS3'
    arguments:
      - '@s3client.factory'

Then you can get a client as required using the createClient method like so

$client = $factory->createClient($key, $secret, $region);

// If you use a service other than AWS S3 you can also pass endpoint, bucket endpoint and version, see settings docs above.
$client = $factory->createClient($key, $secret, $region, $endpoint, $bucketEndpoint, $version);

Known problems

Please use the issue queue to report issues.

S3 Client