README

Amazon S3 or Amazon Simple Storage Service component for Yii2.

Yii2 AWS S3 uses SemVer.

Table of Contents

• Yii2 AWS S3
  • Table of Contents
  • Instalation
  • Dependencies
  • Configuration
  • Usage
    • Basic Usage
    • Advanced Usage
    • Custom Commands
  • Using Traits
    • Model Trait
      • Using Trait Methods
      • Overriding Trait Methods
        • getS3Component
        • attributePaths
        • getPresignedUrlDuration
        • isSuccessResponseStatus

Instalation

Package is available on Packagist, you can install it using Composer.

composer require diecoding/yii2-aws-s3 "^1.0"

or add to the require section of your composer.json file.

"diecoding/yii2-aws-s3": "^1.0"

Dependencies

• PHP 7.4+
• yiisoft/yii2
• aws/aws-sdk-php

Configuration

1. Add the component to config/main.php

   'components' => [
       // ...
       's3' => [
           'class' => \diecoding\aws\s3\Service::class,
           'endpoint' => 'my-endpoint',
           'usePathStyleEndpoint' => true,
           'credentials' => [ // Aws\Credentials\CredentialsInterface|array|callable
               'key' => 'my-key',
               'secret' => 'my-secret',
           ],
           'region' => 'my-region',
           'defaultBucket' => 'my-bucket',
           'defaultAcl' => 'public-read',
       ],
       // ...
   ],

Usage

Basic Usage

/** @var \diecoding\aws\s3\Service $s3 */
$s3 = Yii::$app->get('s3');
// or 
$s3 = Yii::$app->s3;

// Usage of the command factory and additional params
// ==================================================

/** @var \Aws\ResultInterface $result */
$result = $s3->commands()->get('filename.ext')->saveAs('/path/to/local/file.ext')->execute();

$result = $s3->commands()->put('filename.ext', 'body')->withContentType('text/plain')->execute();

$result = $s3->commands()->delete('filename.ext')->execute();

$result = $s3->commands()->upload('filename.ext', '/path/to/local/file.ext')->withAcl('private')->execute();

$result = $s3->commands()->restore('filename.ext', $days = 7)->execute();

$result = $s3->commands()->list('path/')->execute();

/** @var bool $exist */
$exist = $s3->commands()->exist('filename.ext')->execute();

/** @var string $url */
$url = $s3->commands()->getUrl('filename.ext')->execute();

/** @var string $signedUrl */
$signedUrl = $s3->commands()->getPresignedUrl('filename.ext', '+2 days')->execute();

// Short syntax
// ============

/** @var \Aws\ResultInterface $result */
$result = $s3->get('filename.ext');

$result = $s3->put('filename.ext', 'body');

$result = $s3->delete('filename.ext');

$result = $s3->upload('filename.ext', '/path/to/local/file.ext');

$result = $s3->restore('filename.ext', $days = 7);

$result = $s3->list('path/');

/** @var bool $exist */
$exist = $s3->exist('filename.ext');

/** @var string $url */
$url = $s3->getUrl('filename.ext');

/** @var string $signedUrl */
$signedUrl = $s3->getPresignedUrl('filename.ext', '+2 days');

// Asynchronous execution
// ======================

/** @var \GuzzleHttp\Promise\PromiseInterface $promise */
$promise = $s3->commands()->get('filename.ext')->async()->execute();

$promise = $s3->commands()->put('filename.ext', 'body')->async()->execute();

$promise = $s3->commands()->delete('filename.ext')->async()->execute();

$promise = $s3->commands()->upload('filename.ext', 'source')->async()->execute();

$promise = $s3->commands()->list('path/')->async()->execute();

Advanced Usage

/** @var \diecoding\aws\s3\Service $s3 */
$s3 = Yii::$app->get('s3');
// or 
$s3 = Yii::$app->s3;

/** @var \diecoding\aws\s3\commands\GetCommand $command */
$command = $s3->create(GetCommand::class);
$command->inBucket('my-another-bucket')->byFilename('filename.ext')->saveAs('/path/to/local/file.ext');

/** @var \Aws\ResultInterface $result */
$result = $s3->execute($command);

// or async
/** @var \GuzzleHttp\Promise\PromiseInterface $promise */
$promise = $s3->execute($command->async());

Custom Commands

Commands have two types: plain commands that's handled by the PlainCommandHandler and commands with their own handlers. The plain commands wrap the native AWS S3 commands.

The plain commands must implement the PlainCommand interface and the rest must implement the Command interface. If the command doesn't implement the PlainCommand interface, it must have its own handler.

Every handler must extend the Handler class or implement the Handler interface. Handlers gets the S3Client instance into its constructor.

The implementation of the HasBucket and HasAcl interfaces allows the command builder to set the values of bucket and acl by default.

To make the plain commands asynchronously, you have to implement the Asynchronous interface. Also, you can use the Async trait to implement this interface.

Consider the following command:

<?php

namespace app\components\s3\commands;

use diecoding\aws\s3\base\commands\traits\Options;
use diecoding\aws\s3\interfaces\commands\Command;
use diecoding\aws\s3\interfaces\commands\HasBucket;

class MyCommand implements Command, HasBucket
{
    use Options;

    protected $bucket;

    protected $something;

    public function getBucket()
    {
        return $this->bucket;
    }

    public function inBucket(string $bucket)
    {
        $this->bucket = $bucket;

        return $this;
    }

    public function getSomething()
    {
        return $this->something;
    }

    public function withSomething(string $something)
    {
        $this->something = $something;

        return $this;
    }
}

The handler for this command looks like this:

<?php

namespace app\components\s3\handlers;

use app\components\s3\commands\MyCommand;
use diecoding\aws\s3\base\handlers\Handler;

class MyCommandHandler extends Handler
{
    public function handle(MyCommand $command)
    {
        return $this->s3Client->someAction(
            $command->getBucket(),
            $command->getSomething(),
            $command->getOptions()
        );
    }
}

And usage this command:

/** @var \diecoding\aws\s3\Service $s3 */
$s3 = Yii::$app->get('s3');
// or 
$s3 = Yii::$app->s3;

/** @var \app\components\s3\commands\MyCommand $command */
$command = $s3->create(MyCommand::class);
$command->withSomething('some value')->withOption('OptionName', 'value');

/** @var \Aws\ResultInterface $result */
$result = $s3->execute($command);

Custom plain command looks like this:

<?php

namespace app\components\s3\commands;

use diecoding\aws\s3\interfaces\commands\HasBucket;
use diecoding\aws\s3\interfaces\commands\PlainCommand;

class MyPlainCommand implements PlainCommand, HasBucket
{
    protected $args = [];

    public function getBucket()
    {
        return $this->args['Bucket'] ?? '';
    }

    public function inBucket(string $bucket)
    {
        $this->args['Bucket'] = $bucket;

        return $this;
    }

    public function getSomething()
    {
        return $this->args['something'] ?? '';
    }

    public function withSomething($something)
    {
        $this->args['something'] = $something;

        return $this;
    }

    public function getName(): string
    {
        return 'AwsS3CommandName';
    }

    public function toArgs(): array
    {
        return $this->args;
    }
}

Any command can extend the ExecutableCommand class or implement the Executable interface that will allow to execute this command immediately: $command->withSomething('some value')->execute();.

Using Traits

Model Trait

Attach the Trait to the Model/ActiveRecord with some media attribute that will be saved in S3:

/**
 * @property string|null $file
 */
class Model extends \yii\db\ActiveRecord
{
    use \diecoding\aws\s3\traits\ModelTrait;

    // ...

    public function rules()
    {
        return [
            ['image', 'string'], // Stores the filename
        ];
    }

    /**
     * @inheritdoc
     */
    protected function attributePaths()
    {
        return [
            'image' => 'images/'
        ];
    }

    // ...
}

Override the attributePaths() method to change the base path where the files will be saved on AWS S3.

• You can map a different path to each file attribute of your Model/ActiveRecord.

Using Trait Methods

$image = \yii\web\UploadedFile::getInstance($model, 'image');

// Save image_thumb.* to S3 on //my_bucket/images/ path
// The extension of the file will be determined by the submitted file type
// This allows multiple file types upload (png,jpg,gif,...)
// $model->image will hold "image_thumb.png" after this call finish with success
$model->saveUploadedFile($image, 'image', 'image_thumb');

// Save image_thumb.png to S3 on //my_bucket/images/ path
// The extension of the file will be determined by the submitted file type
// This force the extension to *.png
$model->saveUploadedFile($image, 'image', 'image_thumb.png', false);

// Get the URL to the image on S3
$model->getFileUrl('image');

// Get the presigned URL to the image on S3
// The default duration is "+5 Minutes"
$model->getFilePresignedUrl('image');

// Remove the file with named saved on the image attribute
// Continuing the example, here "//my_bucket/images/my_image.png" will be deleted from S3
$model->removeFile('image');

Overriding Trait Methods

getS3Component

The S3MediaTrait depends on this component to be configured. The default configuration is to use this component on index 's3', but you may use another value. For this cases, override the getS3Component() method:

public function getS3Component()
{
    return Yii::$app->get('my_s3_component');
}

attributePaths

The main method to override is attributePaths(), which defines a path in S3 for each attribute of yout model. Allowing you to save each attribute in a different S3 folder.

Here an example:

protected function attributePaths()
{
    return [
        'logo' => 'logos/',
        'badge' => 'images/badges/'
    ];
}

// or use another attribute, example: id
// ! Note: id must contain a value first if you don't want it to be empty

protected function attributePaths()
{
    return [
        'logo' => 'thumbnail/' . $this->id . '/logos/',
        'badge' => 'thumbnail/' . $this->id . '/images/badges/'
    ];
}

getPresignedUrlDuration

The default pressigned URL duration is set to "+5 Minutes", override this method and use your own expiration.

protected function getPresignedUrlDuration($attribute)
{
    return '+2 Hours';
}

// or if you want to set the attribute differently

protected function getPresignedUrlDuration($attribute)
{
    switch ($attribute) {
        case 'badge':
            return '+2 Hours';
            break;
        
        default:
            return '+1 Days';
            break;
    }
}

The value should be a valid PHP datetime operation. Read PHP documentation for details

isSuccessResponseStatus

The isSuccessResponseStatus() method validate the AWS response for status codes is 2**. If needed, you can override this validation:

protected function isSuccessResponseStatus($response)
{
    // Response is always valid
    return true;
}

Read more docs: https://sugengsulistiyawan.my.id/docs/opensource/yii2/aws-s3/