S3 Compatible Object Storage Driver

Introduction

The S3 Driver provides a seamless interface for interacting with AWS S3 and S3-compatible object storage providers (such as DigitalOcean Spaces, MinIO, UpCloud, Hetzner or custom solutions like Ceph). It supports multiple simultaneous connections, allowing you to manage buckets across different regions or providers within a single application.

Key features include:

• Multi-Connection Support: Configure and switch between multiple storage endpoints (e.g., default, asia, archive) easily.
• S3 Compatibility: Works with any S3-compliant API by allowing custom endpoints and regions.
• Environment-Driven: Credentials and endpoints are managed via environment variables for security.

Installation

Install the driver via composer by running:

composer require kipchak/driver-s3

Initialise the Driver

Add the following line to your drivers/drivers.php file:

\Mamluk\Kipchak\Driver\S3\S3::iniitalise($container);

Configuration

The configuration in kipchak.s3.php can be used to configure multiple storage connections:

Connection Settings

For each named connection, you can define:

• access_key: The API Access Key ID.
• secret_key: The API Secret Access Key.
• region: The geographical region of the bucket (e.g., us-east-1, sg).
• endpoint: The base URL of the S3 service. This is critical for non-AWS providers.

Example Configuration

<?php

use function Kipchak\Core\env;

return [
    // Primary storage connection
    'default' => [
        'access_key' => env('S3_ACCESS_KEY', ''),
        'secret_key' => env('S3_SECRET_KEY', ''),
        'region'     => 'sg',
        'endpoint'   => '[https://sg.objects.mamluk.net](https://sg.objects.mamluk.net)'
    ],

    // Secondary storage connection (e.g., different region)
    'asia' => [
        'access_key' => env('ASIA_ACCESS_KEY', ''),
        'secret_key' => env('ASIA_SECRET_KEY', ''),
        'region'     => 'ap-central-1',
        'endpoint'   => '[https://ap.objects.mamluk.net](https://ap.objects.mamluk.net)'
    ],
];

Please see the configuration file in the starter project at https://1x.ax/mamluk/kipchak/starter/~files/master/config/kipchak.s3.php for full configuration details.

Usage

Environment Variables

Ensure your .env file contains the credentials referenced in your config:

    S3_ACCESS_KEY=my-access-key
    S3_SECRET_KEY=my-secret-key
    ASIA_ACCESS_KEY=another-access-key
    ASIA_SECRET_KEY=another-secret-key

Code Example

The driver allows you to select a specific disk using the configuration keys defined above. If no disk is specified, it defaults to the default key.

<?php

use Kipchak\Drivers\S3\Client;

// 1. Initialize the client
$s3 = \Kipchak\Driver\S3\S3::get('default'); // default is the connection name in the config file.

2. Get all buckets in the 'default' connection
foreach ($s3->listBuckets() as $bucket) {
        echo $bucket->getName();
}

// 3. Upload a file to a bucket in the 'default' connection
$s3->put('bucket-name', avatars/user_1.jpg', file_get_contents('/tmp/image.jpg'));

Git Repository

The source code for this driver is available on 1x.ax at https://1x.ax/mamluk/kipchak/drivers/s3.